DOCS / AGENT API

Agent API

The versioned /api/v1 surface for external agents: keys, scopes, run lifecycle, errors and rate limits.

Marres exposes a small, versioned API at /api/v1 so external agents and integrations can read analyses, poll runs, and launch new work without a browser session. The machine-readable contract is published as an OpenAPI 3.1 document at:

https://marresinsights.com/api/v1/openapi.json

This page is the human companion: how to get a key, what the guarantees are, and a full walkthrough.

API keys and scopes

Access is by scoped agent API key only — browser sessions and login tokens are not accepted on /api/v1.

• A signed-in user creates keys in the platform (Settings → Agent API keys). The full secret (mk_...) is shown once at creation; only a hash is stored. Treat it like a password.
• Keys can be revoked at any time; a revoked key fails immediately with a 401.
• Keys are least-privilege. Request only the scopes you need:

Key-authenticated requests never carry administrator powers, regardless of the account that minted the key.

Base URL, versioning and authentication

• Base URL: https://marresinsights.com, all endpoints under /api/v1.
• Authenticate every request with a header: Authorization: Bearer mk_your_key_here
• /api/v1 is stable: fields may be added, but existing fields, error codes and run statuses will not change meaning or disappear within v1. Breaking changes would ship as /api/v2 with a deprecation window announced in the documentation.

Example:

curl -H "Authorization: Bearer mk_..." \
  https://marresinsights.com/api/v1/analyses

Walkthrough: discover → execute → poll → output

1. Discover — GET /api/v1/analyses lists your analyses. For one analysis, GET /api/v1/analyses/{id}/context returns a structured snapshot and GET /api/v1/analyses/{id}/capabilities tells you what can run next and which prerequisites are missing.
2. Preview — POST /api/v1/execute/preview with a body like {"tool": "preview_dmdu", "arguments": {...}} validates the request and queues a pending run. Nothing is charged yet; the response summarises what would launch and what it would cost. Only one preview action is pending at a time: a new preview replaces any previously queued preview (a MIMIRI batch preview queues all companies passed in that single call together). Always follow a preview with its confirm before previewing something else.
3. Confirm — POST /api/v1/execute/confirm charges credits and launches the queued preview, returning the run ids (a MIMIRI batch launches all its runs together). If confirm fails before launching — for example with insufficient credits — the queued preview is preserved and can be confirmed again once the problem is fixed. Confirming with an empty queue returns 409 CONFLICT, so a duplicate confirm cannot double-charge.
4. Poll — GET /api/v1/runs/{id} no more than once every 10 seconds. Statuses are canonical: queued → running → succeeded | failed | cancelled. Terminal states never change.
5. Output — when a run is succeeded, GET /api/v1/runs/{id}/output returns its outputs (JSON strings, parse them) and derived artefacts.

Errors

Every error is JSON with the same shape:

{ "error": "Human-readable message.", "code": "STABLE_CODE", "requestId": "..." }

Rate limits

Limits are enforced per key and per scope over a 60-second window: 60 requests/window for read scopes, 10/window for agent:run. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds); a 429 adds Retry-After. Back off exponentially and honour Retry-After — do not retry immediately.

Credits

Launching work (agent:run) spends the key owner's credits. Preview is free and shows the cost; confirm is the moment of charge. If credits are insufficient, confirm fails with 402 and nothing is launched or charged.

Preview expiry

A queued preview expires 10 minutes after it was first submitted. An expired preview is treated as absent: /execute/confirm returns 409 CONFLICT exactly as it would for an empty queue. There are two important implications:

• Confirm promptly. Don't let more than ~9 minutes pass between /execute/preview and /execute/confirm. If your agent workflow pauses for human approval, re-submit the preview if the approval might arrive near or after the 10-minute mark.

• Expiry is not reset on a failed confirm. If confirm fails — for example with 402 INSUFFICIENT_CREDITS — the preview is restored to the queue with its original expiry timestamp, not a fresh one. A confirm that fails at minute 9 leaves a preview that expires ~60 seconds later. If you then receive a 409 on the retry, re-submit the preview step to obtain a fresh 10-minute window.

preview submitted at T+0  →  expires at T+10m
confirm fails at T+9m     →  preview restored, still expires at T+10m
retry confirm at T+10m01s →  409 CONFLICT (preview expired)
re-preview at T+10m01s    →  new expiry at T+20m01s  ✓

Good citizenship

• Poll runs at most once every 10 seconds.
• Cache the OpenAPI document rather than refetching it per request.
• Use one key per integration so revocation is surgical.
• Never embed a key in client-side code or shared notebooks.

Related product page: For Developers — product page

Documentation draft · Source baseline 16 August 2026