API reference

Authentication

Bearer API keys on every request.

Every request carries an API key in the Authorization header.

Authorization: Bearer sapi_...

Keys start with sapi_. Create them in the portal at platform.simular.ai. A key is shown once at creation; store it in a secret manager or an environment variable, never in source.

Check a key

bash

curl -s "$SAI_API_URL/v1/agents/auth" \
  -H "Authorization: Bearer $SAI_API_KEY"

json

{ "ok": true, "userId": "3fA9kQ2xYz", "authType": "apiKey" }

A missing or revoked key returns 401.

Firebase ID tokens

The same endpoints also accept a Firebase ID token from a signed-in Sai session in the Authorization header. That is how the portal and the sai CLI call the API. Key management under /v1/account/keys accepts only a Firebase session; an API key cannot create, list or revoke keys. See Keys.

Who can use a key

Paid accounts: any live key on the account.
Free accounts: one key, after phone verification. Before verification, key creation returns 403 with { "error": "phone_verification_required" }. The check reads the sign-in token, so verify the phone first and then sign in; if you verified it just now, sign in again before creating the key.

Note

Free-account keys are available from October 1. Today's staging accepts API keys from paid accounts only.

Errors

Status	Meaning
`401`	No credential, or the key is unknown or revoked.
`403`	The key is valid but the account may not do this (plan, ownership).
`429`	A rate limit. See Billing and limits.

Error bodies are JSON with one error string:

json

{ "error": "Message rate limit exceeded. Maximum 60 messages per hour." }