Authentication

Anonymous

The first request your agent makes — POST /api/v1/agent/query — is fully public. There is no API key, no OAuth, no signed token to obtain. Just send the JSON body and the server creates an encounter on the fly.

The response includes two short-lived secrets your agent uses for everything that follows:

• session_token — pass it back on the next /agent/query call to continue the same encounter (for example, when the agent has gathered the missing information and wants to resubmit).
• encounter_token — a 64-character bearer token scoped to a single encounter. Used to drive the checkout URL and to poll the agent chat endpoints for the physician’s reply. Expires 72 hours after the encounter is created.

Personal API keys

Once you have an Appendix account, you can mint a personal API key (ak_…) from your account dashboard. Send it as Authorization: Bearer ak_… (or X-API-Key) on any authenticated endpoint. The key is a long-lived credential tied to your user account.

What an API key gets you

• Submit on behalf of a specific person. Pass patient_id on /api/v1/agent/query so the encounter is bound to your spouse, child, or yourself without picking the patient at checkout. See How to get a patient_id.
• One-call submission for active subscribers. If you’re subscribed and the patient has consented and verified ID, the encounter advances directly to submitted — no checkout URL to visit.
• Manage your account. List/create patients, list and read your own encounters, submit follow-up queries on an existing encounter, read your subscription and invoices, poll the agent chat endpoints.

When auto-submit isn’t possible

If a precondition is missing, the response still returns a checkout_url and an auto_submit object whose pending_reasons field tells the agent what to fix. Possible values: patient_required, patient_not_owned, telehealth_consent_required, patient_not_id_verified, subscription_required, rate_limit_reached.

Clerk session JWTs (browser sessions)

Appendix uses Clerk as its identity provider for the web app. Clerk JWTs are for use in the browser only, and are not accepted by the API for programmatic integration. Server-side and agent-side callers should use a personal API key instead.

/agent/query stays anonymous-friendly

API keys are not required to call /api/v1/agent/query. The initial submission stays available anonymously so any agent can help any user start an encounter without provisioning credentials first.

How to get a patient_id

Each person on your account has a stable UUID. List your patients with GET /api/v1/patients; the id field of each entry is the value to pass as patient_id. The relationship field (one of self, spouse, child, parent, guardian, dependent, other) lets an agent map a sentence like “this is for my wife” onto the right person without you having to type a name. Use POST /api/v1/patients to add new family members.

Rate limits

Limits apply to /api/v1/agent/query and key on, in order: the authenticated user, then the supplied session_token, then a hash of the client IP for fully-anonymous one-shots.

Need higher rate limits for a production integration? Contact hello@appendix.com.

Authentication errors