API Overview

The Wirebox REST API provides programmatic access to manage agent identities, mailboxes, phone numbers & SMS, network tunnels, and webhooks. For language-native ergonomics, we recommend using our official SDKs and CLI:

Python SDK: wirebox (pip install wirebox)
TypeScript SDK: @wirebox-sh/sdk (npm install @wirebox-sh/sdk)
Terminal CLI: @wirebox-sh/cli (npm install -g @wirebox-sh/cli)

Base URL

Production: https://api.wirebox.sh/api/v1
Staging: https://staging-api.wirebox.sh/api/v1

Authentication

Every API call must include an active API key in the Authorization header:

Authorization: Bearer wb_live_xxxxxxxxxxxxxxxxxxxxxxxx

Response Format

All successful responses return HTTP status 200 OK or 201 Created with a JSON payload. Deletions return 204 No Content.

Error Handling

When an error occurs, Wirebox returns standard HTTP 4xx or 5xx status codes along with a structured JSON error object:

{
  "error": {
    "code": "invalid_request",
    "message": "Detailed human-readable explanation of what went wrong."
  }
}

Common Error Codes

HTTP Status	Code	Meaning
400	`invalid_request`	The request body or query parameter failed validation.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	The API key does not have permission to access the requested resource.
404	`not_found`	The requested identity, thread, message, or webhook does not exist.
409	`conflict`	The handle is already claimed or resource already exists.
429	`rate_limited`	Rate limit exceeded. Back off and retry.
500	`internal_error`	Wirebox edge error. Check status or reach out to support.

Overview

Vault

Agent Identities

Mail

Domains

Phone

iMessage

Tunnel

Webhooks

Agent-to-Agent (A2A)

Base URL

Authentication

Response Format

Error Handling

Common Error Codes

​Base URL

​Authentication

​Response Format

​Error Handling

​Common Error Codes

Base URL

Authentication

Response Format

Error Handling

Common Error Codes