Build

API reference

Endpoints for chat, streaming, workers, treasury, staking, and images.

Every ashao surface is built on a small set of JSON endpoints. They share a few conventions: requests and responses are JSON, inputs are validated, and routes that need a signed-in user return 401 with an { error } body when one is absent.

Conventions

  • Auth is a session cookie set after wallet sign-in. Server handlers resolve it with getCurrentUser().
  • Errors are returned as { error: string } with an appropriate HTTP status.
  • Streaming uses Server-Sent Events; everything else is request/response JSON.

Chat

POST/api/chat/send— enqueue a job and persist the conversation

Send a message. Deducts the tier's credit cost if you're signed in, persists the conversation and messages, and enqueues a job. Returns immediately with the ids you need to stream.

request
{
  "tier": "pro",
  "content": "Explain how ashao routes a prompt.",
  "conversationId": "conv_..."
}
response
{ "jobId": "job_...", "conversationId": "conv_..." }
GET/api/chat/stream?jobId=...— SSE stream of tokens for a job

Opens a Server-Sent Events stream for a job. Relays token events as they're produced, then a done event, or an error event on failure.

client
const es = new EventSource(`/api/chat/stream?jobId=${jobId}`);
es.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  // { type: "token", value } | { type: "done", tokens } | { type: "error", message }
  if (evt.type === "done" || evt.type === "error") es.close();
};

Workers

POST/api/worker/register— create a worker, returns workerId
POST/api/worker/claim— claim the next job for a tier
POST/api/worker/token— publish a token for a job
POST/api/worker/complete— finish a job and credit earnings
POST/api/worker/heartbeat— report liveness and throughput

A claim returns the job and its messages, or { job: null } when the queue is empty. Completing a job marks it done, credits the worker's earnings share, and bumps the worker's stats.

claim response
{
  "job": { "id": "job_...", "tier": "pro", "model": "ashao-pro" },
  "messages": [{ "role": "user", "content": "..." }]
}

Network & account

GET/api/stats— live network stats

Returns activeWorkers, queueDepth, jobsCompleted, and tokensPerSec.

GET/api/credits— the current user's credit balance

Returns { credits } for the signed-in user.

Treasury & staking

GET/api/treasury— latest treasury snapshot and series

Returns treasury balance, total burned, rewards paid, circulating supply, price, and a time series for charting.

POST/api/staking/stake— stake $ASHAO
POST/api/staking/unstake— unstake $ASHAO
request
{ "amount": 1000 }

Images

POST/api/images/generate— generate an image, deducts credits
request
{
  "prompt": "a violet aurora over a quiet network of cities",
  "style": "Cinematic",
  "aspect": "Landscape",
  "nsfw": false
}
response
{ "image": { "id": "img_...", "url": "...", "prompt": "..." } }

Economics live in one place

Credit costs, tier prices, and worker shares are defined once in lib/constants.ts. See Credits & tiers for the values.