AgentWifi API documentation

Start with a Workspace key

Endpoint placeholder

Examples use https://api.example.com only as a placeholder. Replace the origin with the deployment endpoint shown in Console; keep the documented /v1 paths unchanged.

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/catalog?availableOnly=true&category=web&limit=5' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>'

Bearer only, never URL or Cookie authentication

Every MCP and REST request requires Authorization: Bearer YOUR_WORKSPACE_API_KEY. Session cookies authenticate Console only and are rejected by the data plane. Query-string keys are rejected.

The plaintext key is returned only once at creation. Do not put it in URLs, prompts, chat, screenshots, source control, shell history, or logs. Revoke a key immediately if it may have leaked.

Remote Streamable HTTP MCP

The MCP endpoint accepts POST requests and supports initialize, tools/list, and tools/call. It is stateless in the first release.

Initialize the connection

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/mcp' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-03-26' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"agentwifi-docs-smoke","version":"1.0.0"}}}'

Five published MCP tools

Tool	Server capability	Input contract
`list_tools` List published tools from the current catalog snapshot	`catalog:read`	`prefix, query, category, provider, source, availability, availableOnly, maxCreditsPerCall, cursor, limit`
`find_tools` Find published tools using semantic and keyword search	`catalog:read`	`query, limit`
`describe_tool` Return the published contract for one canonical tool	`catalog:read`	`canonicalName, version`
`execute_tool` Execute one published canonical tool contract	`tools:execute`	`canonicalName, version, params, maxCredits, idempotencyKey`
`account` Return the current workspace balance and provider health	`account:read`	`verificationCode`

tools/list JSON-RPC payload

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

REST endpoints

REST is an HTTP adapter over the same Catalog, Account, and Execute application services used by MCP. Unknown or repeated query parameters and extra execute body fields fail validation.

Method and path	Server capability	Purpose	Parameters
`GET /v1/catalog`	`catalog:read`	List the complete published catalog with stable pagination and facets.	`prefix` — Canonical-name prefix. `query` — Full-text catalog filter. `category` — Exact category filter. `provider` — Exact provider slug filter. `source` — Exact data-source filter. `availability` — available, unavailable, or deprecated. `availableOnly` — true returns only entries with a published executable route. `maxCreditsPerCall` — Maximum per-call cost as canonical decimal credits. `cursor` — Opaque cursor returned by the previous page. `limit` — 1-100; defaults to 20.
`GET /v1/catalog/search`	`catalog:read`	Find published tools using semantic search with keyword fallback.	`query` * — Search text, 1-500 characters. `limit` — 1-50; defaults to 10.
`GET /v1/catalog/:canonicalName`	`catalog:read`	Describe one published canonical tool contract.	`version` — Exact published version.
`GET /v1/account`	`account:read`	Read the authenticated Workspace balance and provider-health summary.	None
`POST /v1/execute`	`tools:execute`	Execute one available published tool through the shared data plane.	`canonicalName, version, params, maxCredits, idempotencyKey`

Contract-checked examples

Find tools

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/catalog/search?query=latest%20AI%20news&limit=3' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>'

Execute with a replay key

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/execute' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"canonicalName":"web.search","params":{"query":"latest AI news"},"maxCredits":"1","idempotencyKey":"docs-web-search-001"}'

Catalog facts are stable and fail closed

The Catalog returns the complete published snapshot. availability describes the versioned product state; executionAvailable additionally requires at least one enabled published route. Only entries where both are usable can execute.

Treat nextCursor as opaque. It binds the snapshot and every filter, including availableOnly. Replaying it with different filters is rejected. A missing cursor means the final page.

Use availableOnly=true when you need entries that can execute now. Provider health does not rewrite Catalog availability, and unavailable or deprecated entries remain non-executable even if a UI is bypassed.

Account reads the immutable Ledger balance

GET /v1/account and the MCP account tool return the API key's Workspace and balance. availableCredits can be reserved for a call, reservedCredits is currently held, and totalCredits is their sum. Credits are canonical decimal strings, never floating-point values.

Execution reserves an upper bound, then settles actual usage or releases the reservation. The Ledger is the only balance source of truth; Provider output and client-side totals cannot mint or rewrite credits.

Replay safely; cancel deliberately

Idempotency

Set idempotencyKey on execute (8-255 characters) and reuse it only for the same logical request. The key is shared across MCP and REST: retrying through either transport returns the same execution fact instead of charging or calling a Provider twice.

Deadline and cancellation

Each execute has one server deadline across at most two Provider attempts. A client disconnect or AbortSignal cancels work; REST reports CANCELLED with HTTP 499 when a response can still be returned, while deadline expiry reports HTTP 504. Permits and active reservations are released on terminal paths.

Rate and concurrency

All authenticated requests consume per-key and per-Workspace rate capacity. Execute also uses per-key/per-Workspace concurrency and a Provider bulkhead. Saturation returns HTTP 429, RATE_LIMITED, retryAfterMs, a scope, and Retry-After in whole seconds. Retry-After is a backoff hint, not a queue promise.

Current rate, concurrency, and Provider bulkhead backends are in-memory and guarantee atomic limits only inside one API process. A multi-instance deployment must replace them with a shared atomic backend before claiming global limits.

Stable errors and request correlation

Route, authentication, validation, availability, and admission failures use the envelope below and return the same requestId in X-Request-Id. Execute failures return the typed ExecutionResult with status=failed and the same stable error metadata.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded",
    "retryAfterMs": 1000,
    "scope": "api_key_rate"
  },
  "requestId": "req_example_01"
}

Code	HTTP	Retry
`VALIDATION_ERROR`	400	No
`UNAUTHENTICATED`	401	No
`INSUFFICIENT_CREDITS`	402	No
`FORBIDDEN`	403	No
`NOT_FOUND`	404	No
`TOOL_UNAVAILABLE`	409	No
`RATE_LIMITED`	429	Yes, with policy
`CANCELLED`	499	Yes, with policy
`UPSTREAM_UNAVAILABLE`	502	Yes, with policy
`CATALOG_UNAVAILABLE`	503	Yes, with policy
`DEADLINE_EXCEEDED`	504	Yes, with policy
`UPSTREAM_TIMEOUT`	504	Yes, with policy
`INTERNAL_ERROR`	500	No

Verified Agent targets, not a wish list

This matrix is generated from the versioned client registry. Available means at least one exact target and method has PASS evidence; it does not cover unlisted operating systems, architectures, methods, or future client versions.

Windows is deferred and unavailable. Cursor, OpenClaw, Qoder, and WorkBuddy have no verified target. Prompt install is verified only for Codex on macOS arm64 at the registry-pinned versions; do not reuse it elsewhere.

Agent	Status	Verified targets and methods
Codex `codex`	Available in the listed scope	`macos/arm64` — script + Prompt `macos/x64` — script `linux/arm64` — script `linux/x64` — script
Claude Code `claude-code`	Available in the listed scope	`macos/arm64` — script `macos/x64` — script `linux/arm64` — script `linux/x64` — script
Cursor `cursor`	Unavailable / deferred	No verified target
Gemini CLI `gemini-cli`	Available in the listed scope	`macos/arm64` — script `macos/x64` — script `linux/arm64` — script `linux/x64` — script
OpenCode `opencode`	Available in the listed scope	`macos/arm64` — script `macos/x64` — script `linux/arm64` — script `linux/x64` — script
OpenClaw `openclaw`	Unavailable / deferred	No verified target
Hermes `hermes`	Available in the listed scope	`macos/arm64` — script `macos/x64` — script `linux/arm64` — script `linux/x64` — script
Qoder `qoder`	Unavailable / deferred	No verified target
WorkBuddy `workbuddy`	Unavailable / deferred	No verified target
Kimi CLI `kimi-cli`	Available in the listed scope	`macos/arm64` — script `macos/x64` — script `linux/arm64` — script `linux/x64` — script

For installation commands and an authenticated account probe, use Console Quick Start. It exposes only methods verified for the selected target.

الوثائق