{ "openapi": "3.1.0", "info": { "title": "Agesic API", "version": "1.0.0", "summary": "Wallets, budgets and one API key for every AI agent.", "description": "OpenAI-compatible Chat Completions with per-agent spending limits, a model router and a pay-per-call API marketplace. Balances are funded with USDG or ETH on Robinhood Chain. Each call costs the provider price plus a 5% fee; refused and failed calls cost nothing.", "contact": { "name": "Agesic", "url": "https://agesic.cc/docs" }, "termsOfService": "https://agesic.cc/terms" }, "externalDocs": { "description": "Agesic documentation", "url": "https://agesic.cc/docs" }, "servers": [ { "url": "https://agesic.cc/v1", "description": "Production" } ], "security": [ { "agentKey": [] } ], "tags": [ { "name": "Chat", "description": "OpenAI-compatible chat completions." }, { "name": "Models", "description": "Models, prices and routing." }, { "name": "Marketplace", "description": "Paid APIs listed by builders, called through Agesic." } ], "paths": { "/chat/completions": { "post": { "tags": [ "Chat" ], "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "Accepts the standard OpenAI request body; other parameters are passed through to the provider. Use any OpenRouter model ID or a router model (`agesic/auto`, `agesic/cheap`, `agesic/code`, `agesic/reason`). `max_tokens` is lowered when needed so the call can't exceed the per-call cap, the balance or what's left of the daily cap. Set `stream: true` for server-sent events in the OpenAI format. The last event before `data: [DONE]` is a chunk with empty `choices` and `agesic: { charged_micro, charged_usd }`, the amount charged for the call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "The completion, or an SSE stream when `stream` is true. `model` is the model that actually answered.", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1). Streams carry it in their last chunk instead.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown model ID (`model_not_found`). See GET /models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No model provider is configured on this server (`provider_unconfigured`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models": { "get": { "tags": [ "Models" ], "operationId": "listModels", "summary": "List models and prices", "description": "Router models first, then every provider model with its price per million tokens. No key required.", "security": [], "responses": { "200": { "description": "OpenAI-style model list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "502": { "description": "The model list couldn't be loaded (`upstream_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/route/preview": { "post": { "tags": [ "Models" ], "operationId": "previewRoute", "summary": "Preview a routing decision", "description": "Shows which model `agesic/` would pick for a prompt, using the same router as real calls. Calls no model and stores nothing. No key required; rate limited.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 20000 }, "mode": { "type": "string", "enum": [ "auto", "cheap", "code", "reason" ], "default": "auto" } } }, "example": { "prompt": "Fix this failing unit test", "mode": "auto" } } } }, "responses": { "200": { "description": "The routing decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePreview" } } } }, "400": { "description": "`prompt` is missing or too long, or `mode` is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many previews in the last minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/apis/{slug}/{path}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The API's marketplace slug.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path forwarded to the builder's base URL. May be empty or contain slashes.", "schema": { "type": "string" } } ], "description": "Calls a paid API from the marketplace. Method, path, query and body are forwarded to the builder's base URL; the agent's key and cookies are not. The agent is charged the listed price for every response that isn't a 5xx. Agents with an allowlist need `api:` or `api:*`. Responses are capped at 5 MB and 30 seconds.", "get": { "tags": [ "Marketplace" ], "operationId": "callApiGet", "summary": "Call a paid API (GET)", "responses": { "200": { "description": "The builder's response, passed through. `X-Agesic-Charged-Micro` is the amount charged (0 for a 5xx).", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1).", "schema": { "type": "string" } }, "X-Agesic-Call-Id": { "description": "Call ID, also sent to the builder.", "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No API with this slug (`api_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body is over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The API is paused by its owner (`api_paused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other status the builder's API returns is passed through." } } }, "post": { "tags": [ "Marketplace" ], "operationId": "callApiPost", "summary": "Call a paid API (POST)", "requestBody": { "content": { "*/*": { "schema": {} } } }, "responses": { "200": { "description": "The builder's response, passed through. `X-Agesic-Charged-Micro` is the amount charged (0 for a 5xx).", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1).", "schema": { "type": "string" } }, "X-Agesic-Call-Id": { "description": "Call ID, also sent to the builder.", "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No API with this slug (`api_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body is over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The API is paused by its owner (`api_paused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other status the builder's API returns is passed through." } } }, "put": { "tags": [ "Marketplace" ], "operationId": "callApiPut", "summary": "Call a paid API (PUT)", "requestBody": { "content": { "*/*": { "schema": {} } } }, "responses": { "200": { "description": "The builder's response, passed through. `X-Agesic-Charged-Micro` is the amount charged (0 for a 5xx).", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1).", "schema": { "type": "string" } }, "X-Agesic-Call-Id": { "description": "Call ID, also sent to the builder.", "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No API with this slug (`api_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body is over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The API is paused by its owner (`api_paused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other status the builder's API returns is passed through." } } }, "patch": { "tags": [ "Marketplace" ], "operationId": "callApiPatch", "summary": "Call a paid API (PATCH)", "requestBody": { "content": { "*/*": { "schema": {} } } }, "responses": { "200": { "description": "The builder's response, passed through. `X-Agesic-Charged-Micro` is the amount charged (0 for a 5xx).", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1).", "schema": { "type": "string" } }, "X-Agesic-Call-Id": { "description": "Call ID, also sent to the builder.", "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No API with this slug (`api_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body is over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The API is paused by its owner (`api_paused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other status the builder's API returns is passed through." } } }, "delete": { "tags": [ "Marketplace" ], "operationId": "callApiDelete", "summary": "Call a paid API (DELETE)", "responses": { "200": { "description": "The builder's response, passed through. `X-Agesic-Charged-Micro` is the amount charged (0 for a 5xx).", "headers": { "X-Agesic-Charged-Micro": { "description": "Amount charged in micro-dollars (1,000,000 = $1).", "schema": { "type": "string" } }, "X-Agesic-Call-Id": { "description": "Call ID, also sent to the builder.", "schema": { "type": "string" } } } }, "400": { "description": "The body isn't valid JSON or a field is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key was sent (`missing_api_key`) or it is wrong or rotated (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance empty, the agent's daily cap or its project's budget reached, or the call would exceed the per-call cap (`insufficient_balance`, `daily_cap_reached`, `project_cap_reached`, `budget_exceeded`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The agent is paused or the model or API isn't on its allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No API with this slug (`api_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body is over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls in the last minute for this agent (loop breaker).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The provider couldn't be reached. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The API is paused by its owner (`api_paused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other status the builder's API returns is passed through." } } } } }, "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "description": "The agent's key, starting with `agk_`. Created in the dashboard and shown once." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request", "missing_api_key", "invalid_api_key", "insufficient_balance", "daily_cap_reached", "project_cap_reached", "budget_exceeded", "agent_paused", "model_not_allowed", "model_not_found", "model_not_supported", "api_not_found", "api_not_allowed", "api_paused", "own_api", "rate_limited", "upstream_error", "provider_unconfigured" ] }, "code": { "type": "string", "enum": [ "invalid_request", "missing_api_key", "invalid_api_key", "insufficient_balance", "daily_cap_reached", "project_cap_reached", "budget_exceeded", "agent_paused", "model_not_allowed", "model_not_found", "model_not_supported", "api_not_found", "api_not_allowed", "api_paused", "own_api", "rate_limited", "upstream_error", "provider_unconfigured" ] } } } }, "example": { "error": { "message": "This agent has reached its daily spending cap.", "type": "daily_cap_reached", "code": "daily_cap_reached" } } }, "ChatMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "description": "Text, or an array of content parts.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } }, { "type": "null" } ] }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object" } }, "tool_call_id": { "type": "string" } } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "An OpenRouter model ID such as `openai/gpt-5-mini`, or a router model such as `agesic/auto`.", "examples": [ "agesic/auto" ] }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatMessage" } }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 200000, "description": "Defaults to 4096. Lowered when needed to stay within the agent's limits." }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object" } }, "tool_choice": {}, "response_format": { "type": "object" }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "example": { "model": "agesic/auto", "messages": [ { "role": "user", "content": "Say hi in five words" } ], "max_tokens": 50 } }, "ChatCompletion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string", "description": "The model that answered; billing uses this model." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "Model": { "type": "object", "required": [ "id", "object", "owned_by", "name" ], "properties": { "id": { "type": "string", "examples": [ "openai/gpt-5-mini" ] }, "object": { "const": "model" }, "owned_by": { "type": "string" }, "name": { "type": "string" }, "context_length": { "type": "integer" }, "pricing": { "description": "USD per million tokens. Null for router models, which are priced by the model they pick.", "oneOf": [ { "type": "object", "properties": { "prompt_per_million": { "type": "number" }, "completion_per_million": { "type": "number" } } }, { "type": "null" } ] } } }, "RoutePreview": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "agesic/auto" ] }, "tier": { "type": "string", "enum": [ "fast", "balanced", "code", "reason", "hard" ] }, "tierLabel": { "type": "string" }, "picked": { "type": "string", "description": "The primary model for this request." }, "fallbacks": { "type": "array", "items": { "type": "string" } }, "why": { "type": "string" }, "estimate": { "oneOf": [ { "type": "object", "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "pickedUsd": { "type": [ "number", "null" ] }, "baselineUsd": { "type": [ "number", "null" ] }, "savingsPct": { "type": [ "integer", "null" ] } } }, { "type": "null" } ] }, "baseline": { "type": "string", "description": "The model used as the savings baseline." }, "decidedMs": { "type": "integer" } } } } } }