Frontend contract

AICharli customer API

HTTP routes for a new frontend. They run the same server functions as the live dashboard.

Cookie session. CSRF on POST: GET /api/csrf, then header x-csrf-token. Do not send GPU names or API keys. Chat is Agent Zero after launch.

Dashboard vs HTTP

The live UI calls Next.js server actions. Use the HTTP column in a new app.

Dashboard	HTTP
login()	POST /api/v1/auth/login
logout()	POST /api/v1/auth/logout
createPodRequest()	POST /api/v1/assistants/claim
getUserActiveAssignments()	GET /api/v1/assistants
getUnassignedPods()	GET /api/v1/assistants
getPodActivationStatus()	GET /api/v1/assistants
upgradeToPrivate()	POST /api/v1/assistants/upgrade
extendSession()	POST /api/v1/assistants/extend
releaseMyPod()	POST /api/v1/assistants/release
Open assistant	GET /api/agent-zero/launch
Resume	POST /api/pods/{id}/resume
Proxy health	GET /api/proxy/health

Typical flow

GET /api/csrf then POST /api/v1/auth/login with x-csrf-token.
GET /api/v1/assistants and show Shared vs Private from `plans`.
POST /api/v1/assistants/claim with `tier` and `durationHours` only.
Poll GET /api/v1/assistants until `current.status` is READY.
Navigate to `current.launchPath` to open the managed assistant.

Auth

CSRF, register, session

GET/api/csrf

Issue a CSRF token

POST/api/register

Create an account

POST/api/v1/auth/login

Same backend as dashboard server action login() in src/actions/auth.ts. The live login page calls the action; this route runs that function.

POST/api/v1/auth/logout

Clear the session cookie

Same backend as dashboard server action logout() in src/actions/auth.ts.

GET/api/v1/me

Current account

GET/api/user

Current account (legacy path)

Existing dashboard JSON route. Prefer GET /api/v1/me, which adds credits.

Assistants

Shared vs Private claim, session, launch

GET/api/v1/assistants

Current assistant, plans, and credits

Same backend as getUserActiveAssignments() and getUnassignedPods() in src/actions/dashboard-data.ts, plus getPodActivationStatus() via current.status. Poll until current.status is READY, then open current.launchPath.

POST/api/v1/assistants/claim

Claim Shared or Private

Same backend as dashboard server action createPodRequest() in src/actions/requests.ts. The live claim modal calls the action with an internal pod id; this route picks the pod and then runs that function. Send only tier and durationHours.

POST/api/v1/assistants/release

End the current session and refund unused time

Same backend as dashboard server action releaseMyPod() in src/actions/pod-assignment.ts. Looks up the caller's assignment so the client does not send a pod id.

POST/api/v1/assistants/extend

Add hours to the current session

Same backend as dashboard server action extendSession() in src/actions/pod-assignment.ts.

POST/api/v1/assistants/upgrade

Move Shared to Private on the same account

Same backend as dashboard server action upgradeToPrivate() in src/actions/pod-assignment.ts. Memory stays on the account. Unused shared time is refunded first.

GET/api/agent-zero/launch

Open the managed assistant (browser redirect)

Same URL the live dashboard Open assistant button uses. Requires a session cookie. Returns 302 to the auto-login entrypoint when READY, or an HTML wait page while starting. Use from a top-level navigation or window.open, not as JSON.

POST/api/pods/{id}/resume

Resume a stopped assistant runtime

HTTP fetch used by the live dashboard user-pod-actions (POST /api/pods/{id}/resume). This is not a server action. A new frontend can keep using it if it has the assignment's internal id, or prefer polling GET /api/v1/assistants after claim.

History

Conversation metadata stored on the account

GET/api/conversations

List account conversations

POST/api/conversations

Create a conversation record

Does not start a model reply.

GET/api/conversations/{id}/messages

List messages in a conversation

POST/api/conversations/{id}/messages

Store a message

Persists history. It does not call the GPU model.

Health

Liveness and readiness

GET/api/proxy/health

Auth-proxy health (dashboard poll)

HTTP fetch used by the live dashboard ProxyStatusCard. Not a server action.

GET/api/health/live

Process liveness

GET/api/health/ready

Accepts traffic when the database is up

GET/api/openapi.json

This OpenAPI document

Inference

Managed OpenAI-compatible proxy on api.aicharli.com

POST/v1/chat/completions

OpenAI-compatible chat completions

Managed assistant inference. Authorization is a Bearer key minted for the claimed assistant, not a customer-supplied key. Prefer launchPath for the product chat UI.

GET/v1/models

List managed models

POST/v1/memory/search

Search the account's conversation memory