Reference

API Documentation

Everything you need to integrate with Agent Supply. Authenticate, browse products, place orders, and manage resources.

AI agents can read a machine-optimized version at agentsply.com/skill.md

Base URL

https://www.agentsply.com/api/v1

Authentication

All API requests require a Bearer token. Create an API key from your dashboard. Keys are prefixed with as_.

Authorization: Bearer as_your_api_key_here

Response Format

All endpoints return a consistent JSON envelope.

Success

{ "ok": true, "data": { ... } }

Error

{ "ok": false, "error": { "code": "...", "message": "...", "suggestion": "..." } }

Products

Available products and their pricing. Use GET /products for real-time details and config schemas.

Product	Price	Type	Config
web-search	1 credit/use	Instant	query (required), max_results: 1–20
vps	Per hour by instance type	Async	region (required), type (required), duration_hours: integer ≥ 1

Credits

1 credit = $0.01 USD, prepaid
Credits are deducted atomically when an order is created
VPS instances are charged in full-hour increments upfront — no proration
Failed orders are never charged

Endpoints

GET /account/balance

Returns the current credit balance for the authenticated account.

Response

{ "ok": true, "data": { "credits": 5000 } }

GET /products

Lists all available products with pricing, config schemas, and fulfillment type.

Response

{ "ok": true, "data": { "products": [...] } }

GET /products/:slug

Returns a single product with its full config schema.

Response

{ "ok": true, "data": { "product": { ... } } }

POST /orders

Creates an order. Requires Content-Type: application/json and an Idempotency-Key header to prevent duplicates on retry.

Request body

{ "product": "<slug>", "config": { ... } }

Response

{ "ok": true, "data": { "order": { ... } } }

— Instant products return results immediately in the response.
— Async products return status: "pending" — poll GET /orders/:id until fulfilled.
— Idempotency keys are permanent. A key always returns its original result, including failures.
— Validation failures (bad config, insufficient credits) do not consume the key.

GET /orders

Lists all orders. Optional filters: ?status=fulfilled&product=web-search.

Response

{ "ok": true, "data": { "orders": [...] } }

GET /orders/:id

Returns a single order with current status and fulfillment data.

Response

{ "ok": true, "data": { "order": { ... } } }

GET /orders/:id/credentials

Returns connection credentials for a running resource. Only available when instance_status is "running".

Response

{ "ok": true, "data": { "type": "ssh", "credentials": { "host", "port", "username", "private_key" } } }

POST /orders/:id/terminate

Terminates a running VPS instance. Works when instance_status is "running" or "initializing".

Response

{ "ok": true, "data": { "order": { ... } } }

VPS Lifecycle

1POST /orders → order status: "pending"

2Poll GET /orders/:id → status becomes "fulfilled", instance_status: "initializing"

3Continue polling → instance_status becomes "running"

4GET /orders/:id/credentials → retrieve SSH credentials

5When done: POST /orders/:id/terminate

Polling interval: wait 30s, 50s, 60s, then every 60s. Note that fulfilled does not mean ready — wait for instance_status: "running" before fetching credentials.

Error Codes

Code	HTTP	Action
unauthorized	401	Check your Authorization header
not_found	404	Verify the product slug or order ID
validation_error	400	Check request body against the config schema
insufficient_credits	402	Check balance — add more credits from the dashboard
spending_cap_exceeded	403	Use a smaller purchase or raise the spending cap
invalid_state	400	Check order status before operating on it
fulfillment_failed	502	Retry with a new idempotency key — no credits charged
internal_error	500	Retry after a short delay