API reference

Base URL: https://api.askaimee.com/v1. All routes except a public health ping require Authorization: Bearer.

Method	Path	Purpose
GET	/health	Liveness. Full dependency checks with a key.
POST	/hosted-session	Mint a SKU 2 hosted session token. Does not consume daily quota.
POST	/stream	Synchronous chunked Markdown stream. Consumes client daily quota.
POST	/jobs	Enqueue a chat job. Consumes client daily quota.
GET	/jobs/{uuid}	Job status and queue position.
GET	/jobs/{uuid}/output	Streamed-so-far text and final answer.
GET	/conversations	List conversations for the end user.
GET	/conversations/{uuid}	Display-safe history.
PATCH	/conversations/{uuid}	Rename.
DELETE	/conversations/{uuid}	Delete.
POST	/conversations/{uuid}/feedback	Quota-free thumbs feedback.
GET	/usage	UTC-day usage for the external actor.
GET	/providers	Providers allowed for this client.

Stream body

{
  "prompt": "Does M48.06 need laterality?",
  "agent_slug": "aimee-partner",
  "conversation_uuid": "optional-reuse-for-follow-ups",
  "context": { "external_user_id": "user-123" },
  "options": { "detailed_response": false }
}

Response is chunked text/plain. X-Conversation-Id is set when a conversation is created or reused. Partner keys cannot select the FAC aimee or hcccoder agents unless sales binds that slug.

options.detailed_response and options.think_harder_retry (Deep Dive) are rejected unless the API client has Deep Dive enabled. Hosted non-admins cannot set detailed_response on a first send; they use the post-response Deep Dive button, which sends think_harder_retry.

Jobs body

{
  "prompt": "Does M48.06 need laterality?",
  "agent_slug": "aimee-partner",
  "conversation_uuid": "optional-reuse-for-follow-ups",
  "context": { "external_user_id": "user-123" }
}

Returns 202 with a job UUID, conversation UUID, queue name/position, and a usage object. Poll GET /jobs/{uuid} and GET /jobs/{uuid}/output with the same external_user_id. Prefer jobs from your backend when you want queue backpressure and a worker pool; use stream when the client needs chunked tokens on one HTTP connection. Identity rules are the same on both paths (see end-user identity).

Conversations

Pass external_user_id as a query parameter on GET list/read. Ownership is source_app + external_user_id + agent. Reuse conversation_uuid for follow-up turns in the same thread.

Usage

GET /usage?external_user_id=… returns three UTC-day dimensions. A null limit means unlimited for that dimension.

{
  "ok": true,
  "usage": {
    "requests": { "used": 3, "limit": 50, "remaining": 47, "label": "3/50", "reset_at": "2026-09-04T00:00:00Z" },
    "priority": { "used": 0, "limit": null, "remaining": null, "label": "0/unlimited", "reset_at": "2026-09-04T00:00:00Z" },
    "deep_dive": { "used": 1, "limit": 5, "remaining": 4, "label": "1/5", "reset_at": "2026-09-04T00:00:00Z" },
    "reset_at": "2026-09-04T00:00:00Z",
    "timezone": "UTC"
  }
}

Hosted session (SKU 2)

POST /hosted-session
{
  "external_user_id": "user-123",
  "ttl_seconds": 3600
}

Optional SSO path — most tenants just have users sign in at login.askaimee.com. Requires the same Bearer key as other partner routes (chat scope). source_app comes from the key, never the body, and the hu: prefix is reserved for Aimee-managed accounts. Default TTL is 3600 seconds, clamped 300–43200. Returns token, expires_at, external_user_id, and tenant_url. Inject the token into the launcher or iframe. See end-user identity.

Hosted equivalent

The tenant origin exposes the same capabilities as same-origin /chat/stream and /chat/conversations. Identity comes from the verified handoff token (header or cookie), not from ?user= or body external_user_id. The browser still must not call api.askaimee.com with your secret.