Agent API Docs

Everything you need to hand an AI agent a key and let it log meals for you.

What this is

An API key lets an AI agent log food and supplements to your account on your behalf. The agent talks to the UA Strength API over HTTPS.

Base URL: https://api.ultimate-analysis.com
Authentication: send the key as a bearer token — Authorization: Bearer ua_sk_…

Getting a key

Create one on the API Keys settings page. The plaintext key is shown only once and cannot be recovered — copy it immediately and store it securely. If you lose it, revoke and create a new one.

What a key can do

Keys come in two presets. The table below is what each one can and cannot do, verified against the live server.

Action	Nutrition key	Full access key
Log / read food and supplements (`/v1/*`)	yes	yes
Read `/nutrition`	yes	yes
Read `/workouts`, `/activity`, `/biometrics`	403	yes
Create or revoke API keys	403	403
Undo agent activity	403	403

No API key can manage keys or undo its own activity, regardless of scope. Only a signed-in session can. That is what stops a leaked key from extending its own access or covering its tracks.

Endpoints

The nine endpoints an agent can call, plus the spec itself:

Method	Path	Scope	Purpose
`POST`	`/v1/food`	`nutrition:write`	Log a food entry
`GET`	`/v1/food`	`nutrition:read`	List food entries (newest first; optional `date`, `limit`)
`PATCH`	`/v1/food/{id}`	`nutrition:write`	Correct a food entry the caller logged (see below)
`DELETE`	`/v1/food/{id}`	`nutrition:write`	Delete a food entry the caller logged (see below)
`PATCH`	`/v1/supplements/{id}`	`nutrition:write`	Correct a supplement entry the caller logged (see below)
`DELETE`	`/v1/supplements/{id}`	`nutrition:write`	Delete a supplement entry the caller logged (see below)
`POST`	`/v1/supplements`	`nutrition:write`	Log a supplement entry
`GET`	`/v1/supplements`	`nutrition:read`	List supplement entries (newest first; optional `date`, `limit`)
`GET`	`/v1/foods/search`	`nutrition:read`	Search previously logged foods by name
`GET`	`/v1/openapi.json`	none	This API’s machine-readable OpenAPI 3.1 spec

Correcting and removing entries

An agent can fix its own mistakes. PATCH changes only the fields you send; anything omitted keeps its current value. DELETE removes the entry, and the account holder can still undo it afterwards.

Both are deliberately narrow. A key or connector may only amend an entry that it created itself, within the last 24 hours, that has not already been undone, and that nothing else has written to since. Entries logged in the app, entries belonging to a different key, and older entries are the account holder’s alone. The 24 hours runs from when the entry was created, not from the last edit, so an agent cannot hold a row open by touching it repeatedly.

A refusal is 403 carrying a machine-readable reason —not_authored_by_caller, outside_window, undone, orchanged_by_someone_else — so an agent can tell “not mine” from “too late” and say something useful rather than retrying.

Point an agent at GET /v1/openapi.json directly — it needs no credentials, so the agent can discover every endpoint before it authenticates. A key that lacks a required scope receives 403 insufficient_scope rather than an empty result, so a missing scope is never mistaken for empty data.

Worked examples

These run as-is once $UA_KEY holds your key.

Log a meal

# consumedAt is optional and defaults to now.
curl -X POST https://api.ultimate-analysis.com/v1/food \
  -H "Authorization: Bearer $UA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Chobani Yogurt","calories":140,"proteinGrams":20}'

Read today’s food

# date is YYYY-MM-DD. Omit it to list recent entries.
curl https://api.ultimate-analysis.com/v1/food?date=2026-08-19 \
  -H "Authorization: Bearer $UA_KEY"

Search previously logged foods

# Reuse your own known macros instead of guessing them.
curl "https://api.ultimate-analysis.com/v1/foods/search?q=chicken" \
  -H "Authorization: Bearer $UA_KEY"

The search endpoint exists so an agent reuses the calories and macros you already recorded for a food, rather than guessing them fresh each time. Before logging “chicken,” an agent should search first.

Using it with an agent

Claude Code, Cowork, custom GPTs, and scripts work today. For a custom GPT, point it at /v1/openapi.json as the Action schema and use the key as the API-key auth value.
MCP clients can connect to https://api.ultimate-analysis.com/mcp with your key as a bearer token. This is the nicer route for Claude Code and Cowork: the tools are discovered automatically, so you do not have to describe the API at all.
claude.ai web chat cannot use a pasted API key — ordinary Claude conversations cannot call an authenticated API directly. Instead, add the MCP endpoint above as a custom connector; it supports OAuth, so you approve access on a consent screen rather than handling a key. The connector endpoints are live, though this has not yet been confirmed end to end inside claude.ai.

Idempotency

Both POST endpoints accept an optional Idempotency-Key header. Retrying a POST with the same value returns the originally-created entry instead of creating a duplicate, which makes agent retries safe.

curl -X POST https://api.ultimate-analysis.com/v1/food \
  -H "Authorization: Bearer $UA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: meal-2026-08-19-001" \
  -d '{"name":"Banana","calories":105}'

Rate limits

Writes (POST, DELETE): 120 requests/minute per key
Reads (GET on /v1/*): 240 requests/minute per key
Spec (/v1/openapi.json): 60 requests/minute

Exceeding a limit returns 429.