API Reference
The Silvanexum REST API — authenticate, trigger runs, and fetch signed traces over HTTP.
The Silvanexum REST API is the language-agnostic surface beneath the SDKs. The TypeScript and Python SDKs are thin, ergonomic wrappers over exactly these endpoints — reach for raw HTTP when there's no SDK for your language, or to integrate from a shell.
Base URL
Authentication
Send your API key as a bearer token on every request:
Keys are scoped. A request with an insufficient scope returns 403:
| Scope | Grants |
|---|---|
read | Read agents, runs, listings, wallet balance |
run | Execute agents and suites |
manage | Create/update/publish agents, versions, connectors |
pay | Buy credits, purchase listings, request payouts |
The public run view (GET /executions/public/{id}) serves a scrubbed, shareable
trace with no auth; a few discovery endpoints (GET /openapi.json, public agent
cards) are also unauthenticated.
Conventions
- JSON in, JSON out. Send
Content-Type: application/json. - Envelopes. Most responses wrap the payload in a single key
(
{ "agent": {...} },{ "agents": [...] }); the SDKs unwrap this for you. - Idempotency. Mutating money operations (
purchase, payouts, templatedeploy) accept anidempotency-keyheader — reuse the same key to make a retry exactly-once. It is required for purchases and payouts. - Errors carry a JSON body
{ "message", "code" }and anx-request-idresponse header. Status codes:400/422validation,401auth,402insufficient credits,403scope,404not found,429rate limit,5xx.
Core endpoints
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /playground/run | run | Run an agent (captured + signed) |
GET | /executions/{id} | read | Fetch a run's full signed trace |
POST | /executions/{id}/visibility | manage | Make a run public/private |
GET | /executions/public/{id} | — | Public scrubbed run (no auth) |
GET / POST | /agents | read / manage | List / create agents |
GET / PATCH / DELETE | /agents/{id} | read / manage | Get / update / delete |
POST | /agents/{id}/publish · /fork | manage | Publish / fork |
GET / POST | /agents/{id}/versions | read / manage | List / publish signed versions |
POST | /agents/{id}/versions/{semver}/promote | manage | Promote a version to a channel |
GET | /marketplace/search | read | Proof-ranked listing search |
POST | /listings/{id}/purchase | pay | Purchase (idempotent) |
GET | /wallet | read | Credit balance + ledger |
POST | /wallet/credits/purchase | pay | Buy credits (Stripe Checkout) |
GET / POST | /budgets | read / manage | List (with live spend) / create a spend cap |
GET / PATCH / DELETE | /budgets/{id} | read / manage | Get / update / delete a budget |
GET | /budgets/{id}/status | read | Live spend + state (cheap poll for a meter) |
GET | /spending/summary · /spending/trends | read | Cost attributed by agent/project/model/provider + trends |
GET | /spending/mesh-trace/{rootRunId} | read | Multi-hop cost across an agent→agent trace |
GET / POST | /keys | read / manage | List / add a BYO provider key |
POST | /keys/validate | manage | Validate a provider key |
DELETE | /keys/{id} | manage | Remove a provider key |
POST | /gateway/openai/v1/chat/completions | run | OpenAI-compatible metered proxy (BYO key) |
GET | /gateway/usage | read | Recent proxied calls + 30-day spend |
GET / POST | /connectors | read / manage | List / create connectors |
GET / POST | /templates · /templates/{id}/deploy | read / manage | Browse / deploy templates |
GET / POST | /suites · /suites/{id}/run | read / run | Eval suites |
The gateway endpoints are OpenAI-compatible, non-streaming, and enabled per
deployment (GATEWAY_ENABLED); point any OpenAI client's base URL at
/gateway/openai/v1 for zero-code, metered spend capture on your BYO key.
OpenAPI
The full, machine-readable contract is published as an OpenAPI 3.1 document, generated from the same Zod contracts as the SDKs:
Operations tagged x-status: planned (notably the M11 /templates endpoints)
are specified but may not yet be live on every deployment. Generate a client
in any language with your favourite OpenAPI tool, or use the first-party
TypeScript / Python SDKs.