{ "openapi": "3.1.0", "info": { "title": "Nexfer Inference API", "version": "1.0.5", "description": "OpenAI-compatible inference gateway. The data plane under /v1 runs inference with `Authorization: Bearer nxf_live_…` keys; the control plane under /api manages accounts, keys, usage and admin. All money is USD; error responses use a single shape (`{error:{code,message,type}}`).", "contact": { "name": "Nexfer Inference", "url": "https://nexference.com/docs" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://nexference.com" } ], "tags": [ { "name": "Models" }, { "name": "Inference" }, { "name": "Keys" }, { "name": "Usage" }, { "name": "Session" }, { "name": "Account" }, { "name": "Agent" }, { "name": "Admin" }, { "name": "Status" }, { "name": "Meta" } ], "paths": { "/v1/models": { "get": { "tags": [ "Models" ], "operationId": "listModels", "summary": "List models", "description": "Public, cached 60s and IP rate limited (60/min). When called with a key that carries a model allowlist, only allowed models are returned.", "security": [ { "ApiKeyAuth": [] }, {} ], "responses": { "200": { "description": "The model catalogue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/chat/completions": { "post": { "tags": [ "Inference" ], "operationId": "chatCompletions", "summary": "Chat completions", "description": "OpenAI-compatible chat completions. Streaming (`stream:true`) returns server-sent events ending in `data: [DONE]`; when `stream_options` is omitted the gateway adds `stream_options.include_usage=true`. `max_tokens`/`max_completion_tokens` are clamped to 8192. Body cap 2 MiB.", "security": [ { "ApiKeyAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "example": "gpt-oss-20b" }, "messages": { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } } }, "stream": { "type": "boolean", "default": false }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "max_tokens": { "type": "integer", "example": 256 }, "max_completion_tokens": { "type": "integer" }, "temperature": { "type": "number" }, "top_p": { "type": "number" } } }, "example": { "model": "gpt-oss-20b", "messages": [ { "role": "user", "content": "ping" } ], "max_tokens": 24 } } } }, "responses": { "200": { "description": "A completion (JSON) or a server-sent event stream when `stream` is true.", "headers": { "x-nexfer-request-id": { "schema": { "type": "string" } }, "x-nexfer-key": { "schema": { "type": "string" } }, "x-nexfer-cost-usd": { "schema": { "type": "string" } }, "x-nexfer-balance-usd": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } }, "finish_reason": { "type": "string" } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "example": { "id": "chatcmpl_1", "object": "chat.completion", "model": "gpt-oss-20b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "pong" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 6, "completion_tokens": 4, "total_tokens": 10 } } }, "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"choices\":[{\"delta\":{\"content\":\"pong\"}}]}\n\ndata: [DONE]\n\n" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/completions": { "post": { "tags": [ "Inference" ], "operationId": "completions", "summary": "Legacy completions", "description": "Legacy text-completions passthrough (OpenAI-compatible).", "security": [ { "ApiKeyAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "stream": { "type": "boolean" }, "max_tokens": { "type": "integer" } } } } } }, "responses": { "200": { "description": "A completion (JSON) or SSE stream." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/embeddings": { "post": { "tags": [ "Inference" ], "operationId": "embeddings", "summary": "Embeddings", "description": "Embeddings passthrough (OpenAI-compatible).", "security": [ { "ApiKeyAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } } } }, "responses": { "200": { "description": "An embeddings response." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/responses": { "post": { "tags": [ "Inference" ], "operationId": "responses", "summary": "Responses", "description": "Responses API passthrough (OpenAI-compatible).", "security": [ { "ApiKeyAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string" }, "input": {}, "stream": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "A responses payload or SSE stream." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/key": { "get": { "tags": [ "Keys" ], "operationId": "getKeyInfo", "summary": "This key's metadata", "description": "Returns the presented key's metadata and limits plus the account balance and status. Requires the `models` scope.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Key metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "key" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rpm": { "type": [ "integer", "null" ] }, "concurrency": { "type": [ "integer", "null" ] }, "monthly_cap_usd": { "type": [ "number", "null" ] }, "daily_cap_usd": { "type": [ "number", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "balance_usd": { "type": "number" }, "status": { "type": "string" } } }, "base_url": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "operationId": "getKeyUsage", "summary": "This key's usage summary", "description": "Usage summary for the presented key. Requires the `usage` scope. `days` is 1-90 (default 30).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Per-key usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/session": { "get": { "tags": [ "Session" ], "operationId": "getSession", "summary": "Current session", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "The current user, a CSRF token, limits and public config.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "csrf": { "type": "string" }, "limits": { "type": "object" }, "config": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/signup": { "post": { "tags": [ "Session" ], "operationId": "signup", "summary": "Create an account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "description": "At least 10 characters." }, "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Account created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "requires_verification": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/verify": { "post": { "tags": [ "Session" ], "operationId": "verifyEmail", "summary": "Verify an email code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string" }, "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verified; session cookie set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "csrf": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/verify/resend": { "post": { "tags": [ "Session" ], "operationId": "resendVerify", "summary": "Resend a verification code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/login": { "post": { "tags": [ "Session" ], "operationId": "login", "summary": "Sign in", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Signed in; session cookie set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "csrf": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/logout": { "post": { "tags": [ "Session" ], "operationId": "logout", "summary": "Sign out", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Signed out; cookie cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } } } } }, "/api/password/reset": { "post": { "tags": [ "Session" ], "operationId": "passwordReset", "summary": "Request a password-reset code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/password/confirm": { "post": { "tags": [ "Session" ], "operationId": "passwordConfirm", "summary": "Confirm a password reset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code", "new_password" ], "properties": { "email": { "type": "string" }, "code": { "type": "string" }, "new_password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password changed; session cookie set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "csrf": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Get the current account", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Account with running usage, limits and key count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "running": { "type": "object", "properties": { "requests_month": { "type": "integer" }, "spend_month_usd": { "type": "number" } } }, "limits": { "type": "object" }, "keys": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Account" ], "operationId": "updateMe", "summary": "Update the profile", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/me/password": { "post": { "tags": [ "Account" ], "operationId": "changePassword", "summary": "Change the password", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/me/sessions": { "get": { "tags": [ "Account" ], "operationId": "listSessions", "summary": "List active sessions", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Sessions for this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "ip": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "current": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": [ "Account" ], "operationId": "revokeAllSessions", "summary": "Revoke all other sessions", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "responses": { "200": { "description": "Other sessions revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "revoked": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/me/sessions/{id}": { "delete": { "tags": [ "Account" ], "operationId": "revokeSession", "summary": "Revoke one session", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "responses": { "200": { "description": "Session revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/keys": { "get": { "tags": [ "Keys" ], "operationId": "listKeys", "summary": "List API keys", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "The account's keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Keys" ], "operationId": "createKey", "summary": "Create an API key", "description": "The `secret` is returned once and never again.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "prod-key" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "chat", "models", "usage" ] } }, "models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rpm": { "type": "integer" }, "concurrency": { "type": "integer" }, "monthly_cap_usd": { "type": [ "number", "null" ] }, "daily_cap_usd": { "type": [ "number", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "allowed_ips": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Key created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "example": "nxf_live_OVeJ357u_" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/keys/{id}": { "get": { "tags": [ "Keys" ], "operationId": "getKey", "summary": "Get one key with usage", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key and its 30-day usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "usage": { "type": "object", "properties": { "totals": { "$ref": "#/components/schemas/UsageTotals" }, "by_day": { "type": "array", "items": { "type": "object" } }, "by_model": { "type": "array", "items": { "type": "object" } }, "recent": { "type": "array", "items": { "type": "object" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Keys" ], "operationId": "updateKey", "summary": "Update a key", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rpm": { "type": "integer" }, "concurrency": { "type": "integer" }, "monthly_cap_usd": { "type": [ "number", "null" ] }, "daily_cap_usd": { "type": [ "number", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "allowed_ips": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Keys" ], "operationId": "deleteKey", "summary": "Delete a revoked key", "description": "Only an already-revoked key can be deleted; deleting a live key returns 409.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/keys/{id}/rotate": { "post": { "tags": [ "Keys" ], "operationId": "rotateKey", "summary": "Rotate a key", "description": "Keeps the same key id and issues a new secret/prefix. The old prefix works until `grace_until` (default 1440 minutes).", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grace_minutes": { "type": "integer", "minimum": 0, "maximum": 10080, "default": 1440 } } } } } }, "responses": { "200": { "description": "Rotated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string" }, "previous": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "grace_until": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/keys/{id}/revoke": { "post": { "tags": [ "Keys" ], "operationId": "revokeKey", "summary": "Revoke a key", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/quickstart": { "get": { "tags": [ "Agent" ], "operationId": "agentQuickstart", "summary": "Onboarding facts for agents", "responses": { "200": { "description": "Base URLs, auth header and ready-made first-call snippets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "base_url": { "type": "string" }, "auth_header": { "type": "string" }, "models_url": { "type": "string" }, "docs": { "type": "object" }, "first_call": { "type": "object", "properties": { "curl": { "type": "string" }, "python": { "type": "string" }, "node": { "type": "string" } } }, "signup": { "type": "object" } } } } } } } } }, "/api/models": { "get": { "tags": [ "Models" ], "operationId": "listModelsApi", "summary": "List models (control plane)", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] }, {} ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive filter on id/name." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Models plus cache metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "count": { "type": "integer" }, "cached_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } } } } } } } }, "/api/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsage", "summary": "Account usage summary", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Account-wide usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageDetailed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/play/chat": { "post": { "tags": [ "Inference" ], "operationId": "playgroundChat", "summary": "Playground streaming chat", "description": "Session-authenticated streaming chat for the in-site playground. Returns SSE identical to /v1/chat/completions and bills the call to the account balance. Rate limited to 20/min.", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object" } }, "max_tokens": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Server-sent event stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/agent/register": { "post": { "tags": [ "Agent" ], "operationId": "agentRegister", "summary": "Register an agent and get a key (no browser)", "description": "Creates an account and a working API key in one call. All fields are optional. IP rate limited and gated by a process-wide daily cap.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional label." }, "email": { "type": "string", "format": "email", "description": "Optional contact address." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Optional model allowlist." } } }, "example": { "name": "my-agent" } } } }, "responses": { "201": { "description": "Account and key created. The `secret` is shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/User" }, "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string" }, "base_url": { "type": "string" }, "models_url": { "type": "string" }, "docs_url": { "type": "string" }, "llms_txt": { "type": "string" }, "note": { "type": "string" } } }, "example": { "account": { "id": "usr_...", "email": "agent+xxxx@nexfer.invalid", "name": "my-agent", "role": "user", "status": "active", "verified": false, "balance_usd": 0.5, "spent_month_usd": 0, "requests_month": 0, "monthly_cap_usd": 1, "rpm": 20, "created_at": "2026-10-27T08:15:18.593Z", "last_login_at": null }, "key": { "id": "key_aTL0clPgqw2n", "name": "my-agent", "prefix": "nxf_live_OVeJ357u", "status": "active", "scopes": [ "chat", "models", "usage" ], "models": null, "rpm": 20, "concurrency": 2, "monthly_cap_usd": 1, "daily_cap_usd": 0.5, "expires_at": null, "allowed_ips": null, "created_at": "2026-10-27T08:15:18.746Z", "last_used_at": null, "grace_until": null, "revoked_at": null, "spend_month_usd": 0, "spend_today_usd": 0, "requests_month": 0, "upstream": "pending" }, "secret": "nxf_live_OVeJ357u_<32-hex-secret>", "base_url": "https://nexference.com/v1", "models_url": "https://nexference.com/v1/models", "docs_url": "https://nexference.com/docs.md", "llms_txt": "https://nexference.com/llms.txt", "note": "Store the secret now: it is shown once. Rotate with POST /api/keys/:id/rotate." } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/admin/overview": { "get": { "tags": [ "Admin" ], "operationId": "adminOverview", "summary": "Platform overview", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Platform totals, usage, revenue and health.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users": { "get": { "tags": [ "Admin" ], "operationId": "adminListUsers", "summary": "List users", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Users with key counts and totals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "total": { "type": "integer" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users/{id}/credit": { "post": { "tags": [ "Admin" ], "operationId": "adminCreditUser", "summary": "Credit or debit a user", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id (usr_…)." }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_usd": { "type": "number", "description": "Positive credits, negative debits. Non-zero." }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated user and new ledger entry.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users/{id}/status": { "post": { "tags": [ "Admin" ], "operationId": "adminSetUserStatus", "summary": "Set a user's status", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id (usr_…)." }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } } } } } }, "responses": { "200": { "description": "Updated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users/{id}/limits": { "post": { "tags": [ "Admin" ], "operationId": "adminSetUserLimits", "summary": "Set a user's limits", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id (usr_…)." }, { "name": "x-nexfer-csrf", "in": "header", "required": true, "schema": { "type": "string" }, "description": "CSRF token from GET /api/session." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly_cap_usd": { "type": [ "number", "null" ] }, "rpm": { "type": [ "integer", "null" ] } } } } } }, "responses": { "200": { "description": "Updated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users/{id}/ledger": { "get": { "tags": [ "Admin" ], "operationId": "adminUserLedger", "summary": "A user's balance ledger", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id (usr_…)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Ledger entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string" }, "kind": { "type": "string" }, "amount_usd": { "type": "number" }, "balance_after_usd": { "type": "number" }, "note": { "type": [ "string", "null" ] }, "actor": { "type": "string" } } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/users/{id}/keys": { "get": { "tags": [ "Admin" ], "operationId": "adminUserKeys", "summary": "A user's keys (owner view)", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id (usr_…)." } ], "responses": { "200": { "description": "The user's keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/audit": { "get": { "tags": [ "Admin" ], "operationId": "adminAudit", "summary": "Audit log", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "before", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string" }, "actor": { "type": "string" }, "action": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "detail": {} } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/admin/upstream": { "get": { "tags": [ "Admin" ], "operationId": "adminUpstream", "summary": "Capacity provisioning status", "security": [ { "SessionCookie": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Provisioning configuration, jobs and account status.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/status": { "get": { "tags": [ "Status" ], "operationId": "getStatus", "summary": "Public status", "responses": { "200": { "description": "Public configuration, model cache and uptime.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "env": { "type": "string" }, "publicBase": { "type": "string" }, "markupPercent": { "type": "number" }, "signupOpen": { "type": "boolean" }, "agentSignupOpen": { "type": "boolean" }, "requireEmailVerification": { "type": "boolean" }, "signupCreditUsd": { "type": "number" }, "agentSignupCreditUsd": { "type": "number" }, "defaultRpm": { "type": "integer" }, "defaultConcurrency": { "type": "integer" }, "defaultMonthlyCapUsd": { "type": "number" }, "models_cached_at": { "type": [ "string", "null" ] }, "models_count": { "type": "integer" }, "uptime_s": { "type": "integer" }, "config": { "type": "object" } } } } } } } } }, "/healthz": { "get": { "tags": [ "Meta" ], "operationId": "healthz", "summary": "Liveness and status", "description": "No auth, no secrets. Add `?deep=1` to probe capacity reachability.", "parameters": [ { "name": "deep", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Health report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "db": { "type": "string", "enum": [ "ok", "error" ] }, "models_cached": { "type": "integer" }, "uptime_s": { "type": "integer" }, "upstream": { "type": "object", "properties": { "reachable": { "type": [ "boolean", "null" ] }, "checked_at": { "type": [ "string", "null" ] } } } } } } } }, "503": { "description": "Database unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/llms.txt": { "get": { "tags": [ "Meta" ], "summary": "Agent-facing instructions.", "responses": { "200": { "description": "Agent-facing instructions.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/docs.md": { "get": { "tags": [ "Meta" ], "summary": "Full documentation (markdown).", "responses": { "200": { "description": "Full documentation (markdown).", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "This OpenAPI 3.1 document.", "responses": { "200": { "description": "This OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/security.txt": { "get": { "tags": [ "Meta" ], "summary": "RFC 9116 security contact.", "responses": { "200": { "description": "RFC 9116 security contact.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/robots.txt": { "get": { "tags": [ "Meta" ], "summary": "Crawler directives.", "responses": { "200": { "description": "Crawler directives.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/sitemap.xml": { "get": { "tags": [ "Meta" ], "summary": "Sitemap.", "responses": { "200": { "description": "Sitemap.", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/changelog.md": { "get": { "tags": [ "Meta" ], "summary": "Release history.", "responses": { "200": { "description": "Release history.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/v1/systemone": { "post": { "tags": [ "Inference" ], "operationId": "decisions", "summary": "Decision models", "description": "Decisions models (catalogue `kind: \"decisions\"`) are called on the `endpoint` each model advertises (currently `/v1/systemone`), not on /v1/chat/completions. Send a `model`, the `state` the questions are about, and a map of named `questions` (types `score`, `choice`, `noul`). Answer `type` matches each question. Billing is input tokens only; usage uses OpenAI names. Calling a decisions model on a chat path (or vice versa) returns 400 invalid_request.", "security": [ { "ApiKeyAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" }, "example": { "model": "clef", "state": "The team shipped the feature on time and every test passed.", "questions": { "quality": { "type": "score", "min": 0, "max": 10 }, "tone": { "type": "choice", "options": [ "formal", "casual" ], "criteria": { "formal": "uses formal language", "casual": "uses casual language" } }, "flag": { "type": "noul" } } } } } }, "responses": { "200": { "description": "The decision answers.", "headers": { "x-nexfer-request-id": { "schema": { "type": "string" } }, "x-nexfer-key": { "schema": { "type": "string" } }, "x-nexfer-cost-usd": { "schema": { "type": "string" } }, "x-nexfer-balance-usd": { "schema": { "type": "string" } }, "x-nexfer-tokens": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionResponse" }, "example": { "answers": { "flag": { "noul": 0.9415, "type": "noul" }, "quality": { "confidence": 0.5694, "legend": { "0": "very unlikely", "1": "unlikely", "2": "unsure", "3": "likely", "4": "very likely" }, "probabilities": { "0": 0.0099, "1": 0.01, "2": 0.0174, "3": 0.1718, "4": 0.7909 }, "score": 3.7239, "type": "score" }, "tone": { "choice": "formal", "confidence": 0.7419, "probabilities": { "casual": 0.0693, "formal": 0.9307 }, "type": "choice" } }, "id": "dec-0f0977b3030caf45b8b378e0", "model": "clef", "object": "decision", "usage": { "prompt_tokens": 308, "completion_tokens": 0, "total_tokens": 308 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid_request" }, "message": { "type": "string", "example": "Invalid request." }, "type": { "type": "string", "example": "invalid_request_error" }, "param": { "type": [ "string", "null" ], "example": null } }, "required": [ "code", "message", "type" ] } }, "required": [ "error" ] }, "User": { "type": "object", "description": "An account. Owner-only fields are omitted for non-owner callers.", "properties": { "id": { "type": "string", "example": "usr_26cd549f-3496-42b5-b0de-930f50327b86" }, "email": { "type": "string", "format": "email", "example": "you@example.com" }, "name": { "type": [ "string", "null" ], "example": "Ada" }, "role": { "type": "string", "enum": [ "user", "owner" ], "example": "user" }, "status": { "type": "string", "enum": [ "active", "paused" ], "example": "active" }, "verified": { "type": "boolean", "description": "Email verified.", "example": true }, "balance_usd": { "type": "number", "description": "Prepaid credit in USD.", "example": 0.5 }, "spent_month_usd": { "type": "number", "description": "Charged usage this calendar month.", "example": 0 }, "requests_month": { "type": "integer", "example": 0 }, "monthly_cap_usd": { "type": [ "number", "null" ], "example": 20 }, "rpm": { "type": "integer", "description": "Requests-per-minute ceiling for this account.", "example": 60 }, "created_at": { "type": "string", "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "role", "status", "verified", "balance_usd", "created_at" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "example": "key_aTL0clPgqw2n" }, "name": { "type": "string", "example": "prod-key" }, "prefix": { "type": "string", "description": "Safe-to-display key prefix.", "example": "nxf_live_OVeJ357u" }, "status": { "type": "string", "enum": [ "active", "rotating", "revoked" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "chat", "models", "usage" ] } }, "models": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Model-id allowlist; null = every model." }, "rpm": { "type": [ "integer", "null" ], "example": 60 }, "concurrency": { "type": [ "integer", "null" ], "example": 4 }, "monthly_cap_usd": { "type": [ "number", "null" ], "example": 10 }, "daily_cap_usd": { "type": [ "number", "null" ], "example": 5 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "allowed_ips": { "type": [ "array", "null" ], "items": { "type": "string" }, "example": null }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "grace_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Set only while status is rotating." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "spend_month_usd": { "type": "number", "example": 0 }, "spend_today_usd": { "type": "number", "example": 0 }, "requests_month": { "type": "integer", "example": 0 }, "upstream": { "type": "string", "enum": [ "provisioned", "pending", "shared", "none" ], "description": "Dedicated capacity state for this key." } }, "required": [ "id", "name", "prefix", "status", "scopes" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Send verbatim as `model`.", "example": "gpt-oss-20b" }, "object": { "type": "string", "enum": [ "model" ] }, "name": { "type": "string", "example": "GPT-OSS 20B" }, "kind": { "type": "string", "enum": [ "chat", "decisions" ] }, "owned_by": { "type": "string", "enum": [ "nexfer" ] }, "context_length": { "type": "integer", "example": 131072 }, "free": { "type": "boolean", "example": true }, "uncensored": { "type": "boolean", "example": false }, "created": { "type": "integer", "example": 0 }, "pricing": { "type": "object", "description": "Retail USD per 1,000,000 tokens (markup included).", "properties": { "prompt_usd_per_m": { "type": "number", "example": 0 }, "completion_usd_per_m": { "type": "number", "example": 0 }, "cache_read_usd_per_m": { "type": "number", "example": 0 }, "long_context": { "type": "array", "description": "Optional long-context tiers (retail USD per 1,000,000 tokens). For a request, the tier with the highest `above_tokens` that the prompt exceeds replaces the base rates.", "items": { "type": "object", "properties": { "above_tokens": { "type": "integer", "example": 100000 }, "prompt_usd_per_m": { "type": "number", "example": 0.5625 }, "completion_usd_per_m": { "type": "number", "example": 2.875 }, "cache_read_usd_per_m": { "type": "number", "example": 0.05625 } } } } }, "required": [ "prompt_usd_per_m", "completion_usd_per_m", "cache_read_usd_per_m" ] }, "endpoint": { "type": "string", "description": "The client-visible path this model is called on. Present on `decisions` models; chat models use /v1/chat/completions.", "example": "/v1/systemone" }, "free_until": { "type": [ "string", "null" ], "format": "date", "description": "When set and in the future, the model is free to call until this date.", "example": "2026-11-04" } }, "required": [ "id", "object", "owned_by", "pricing" ] }, "UsageTotals": { "type": "object", "properties": { "requests": { "type": "integer" }, "rejected": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "cost_usd": { "type": "number" } } }, "UsageSummary": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" } } }, "days": { "type": "integer", "example": 30 }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "by_day": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "requests": { "type": "integer" }, "cost_usd": { "type": "number" }, "tokens": { "type": "integer" } } } }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "cost_usd": { "type": "number" } } } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_key": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "requests": { "type": "integer" }, "cost_usd": { "type": "number" } } } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "tokens": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cost_usd": { "type": "number" }, "latency_ms": { "type": "integer" }, "stream": { "type": "boolean" }, "request_id": { "type": "string" } } } } }, "description": "Per-key usage summary (GET /v1/usage)." }, "UsageDetailed": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" } } }, "days": { "type": "integer", "example": 30 }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "by_day": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "requests": { "type": "integer" }, "cost_usd": { "type": "number" }, "tokens": { "type": "integer" } } } }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "cost_usd": { "type": "number" } } } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_key": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "requests": { "type": "integer" }, "cost_usd": { "type": "number" } } } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "tokens": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cost_usd": { "type": "number" }, "latency_ms": { "type": "integer" }, "stream": { "type": "boolean" }, "request_id": { "type": "string" } } } } }, "description": "Account-wide usage summary (GET /api/usage)." }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ] }, "DecisionAnswer": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "score" ] }, "score": { "type": "number", "example": 3.7239 }, "confidence": { "type": "number", "example": 0.5694 }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" } }, "legend": { "type": "object", "additionalProperties": { "type": "string" } } } }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "choice": { "type": "string", "example": "formal" }, "confidence": { "type": "number", "example": 0.7419 }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" } } } }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "noul" ] }, "noul": { "type": "number", "description": "Probability of the affirmative answer.", "example": 0.9415 } } } ] }, "DecisionRequest": { "type": "object", "required": [ "model", "state", "questions" ], "properties": { "model": { "type": "string", "example": "clef" }, "state": { "oneOf": [ { "type": "string" }, { "type": "object" } ], "description": "The text or JSON the questions are about." }, "questions": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "score", "choice", "noul" ] }, "min": { "type": "number", "description": "score only." }, "max": { "type": "number", "description": "score only." }, "options": { "type": "array", "items": { "type": "string" }, "description": "choice only: the candidate labels.", "example": [ "formal", "casual" ] }, "criteria": { "type": "object", "additionalProperties": { "type": "string" }, "description": "choice only: per-label criteria the model judges against.", "example": { "formal": "uses formal language", "casual": "uses casual language" } } } }, "example": { "quality": { "type": "score", "min": 0, "max": 10 }, "tone": { "type": "choice", "options": [ "formal", "casual" ], "criteria": { "formal": "uses formal language", "casual": "uses casual language" } }, "flag": { "type": "noul" } } } } }, "DecisionResponse": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DecisionAnswer" } }, "id": { "type": "string", "example": "dec-0f0977b3030caf45b8b378e0" }, "model": { "type": "string", "example": "clef" }, "object": { "type": "string", "enum": [ "decision" ] }, "usage": { "type": "object", "description": "OpenAI-style token counts (prompt_tokens/completion_tokens/total_tokens)." } }, "required": [ "answers", "id", "model", "object" ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "nxf_live", "description": "API key as `Authorization: Bearer nxf_live__`." }, "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "nx_s", "description": "Browser session cookie. Cookie-authenticated mutations (POST/PATCH/DELETE under /api) must also send the `x-nexfer-csrf` header matching `csrf` from GET /api/session." } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Not permitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Balance or spend cap exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Illegal state change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadGateway": { "description": "The model produced an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceUnavailable": { "description": "Inference temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "GatewayTimeout": { "description": "The model timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }