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 only unauthenticated endpoint is the public run view
(GET /executions/public/{id}), which serves a scrubbed, shareable trace.
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 | /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 |
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.