Macrolizer Agent API

Discovery

Manifest: GET /.well-known/macrolizer.json — apiBase, OpenAPI URL, auth methods, and the MCP path.

Full OpenAPI: GET /api/agent/v1/openapi.json. This is the contract for personal access tokens (PAT) and OAuth clients. securitySchemes lists bearer PAT and oauth2, with the scope each operation actually requires.

ChatGPT Actions and the plugin use GET /.well-known/ai-plugin.json, the 8-operation GET /api/agent/v1/chatgpt/openapi.json, and OAuth 2.1. They do not call the full OpenAPI document.

Call the API, MCP, and plugin discovery on https://macrolizer.hu. The macrolizer.app apex may 308-redirect some paths to www; do not use it as an MCP base unless those redirects are guaranteed.

Entry paths for agents

ChatGPT Plugin and Action (recommended for ChatGPT): dedicated manifest (/.well-known/ai-plugin.json) and curated 8-operation OpenAPI (/api/agent/v1/chatgpt/openapi.json) with OAuth 2.1 (PKCE S256). Account linking is at /en/settings/chatgpt.

Personal access token (Bearer PAT — Claude, Cursor, scripts, other clients): call the full OpenAPI (/api/agent/v1/openapi.json) with an mlz_pat_... token created at /en/settings/api-key. A new key includes diary:read only. profile:read covers the profile and weight, diary:read or catalog:read covers the catalog, diary:write covers logging, and compare:write covers the comparison list.

OAuth tokens are issued only for the MCP resource (/api/mcp). A token whose audience is the agent API base or the site origin fails refresh and bearer checks; reconnect the app.

Cursor and MCP: stateless POST /api/mcp with streamable-http transport and a Bearer token on every request (PAT or OAuth 2.1). MCP exposes 25 tools, including restore_item and the comparison list (get_compare, add_compare_item, remove_compare_item, clear_compare). ChatGPT stays at 8 operations and does not include comparison. get_me returns the profile, including the eating style in effect today (eatingStyle, read-only).

Meal-group rename, move, merge, and split (rename_meal, move_diary_items, merge_meals, split_meal) are on MCP and on REST: PATCH /api/agent/v1/meals/groups/{id}, POST /api/agent/v1/meals/groups/{id}/items, POST /api/agent/v1/meals/groups/merge, POST /api/agent/v1/meals/groups/{id}/split. The ChatGPT 8 operations do not include them. Each write needs diary:write, agents_can_write, and Idempotency-Key.

Missing data

Unknown price, amount, or nutrient is not an error: the field is null, never a guessed number. Fiber (fiberG) and net carbs (netCarbG) follow the same rule. A day or week total is a number only when every item in it can be calculated. Meal-group totals also include coverage: complete, partial, or none.

Catalog and diary items declare weightBasis (dry, cooked, or null); if the user describes a cooked amount, prefer the cooked (*-fott) item and never log cooked grams against a dry-basis item.

When helpful, an explanatory field (e.g. missingReason) describes why the value is absent.

Error codes

Uniform envelope: { "error": { "code", "message", "details?" } }. Use HTTP status together with code.

Codes: unauthorized, forbidden, invalid, not_found, conflict, rate_limited, internal.

• unauthorized — missing or invalid Bearer token
• forbidden — insufficient scope
• invalid — bad parameter or body
• not_found — unknown resource
• conflict — state conflict (e.g. day revision)
• rate_limited — too many requests
• internal — unexpected server error

Locale and country

The agent API does not read locale/country from cookies. Resolution order: query (locale, country) → Accept-Language / X-Market-Country → saved profile → hu.