API Overview

The Wirebox REST API provides programmatic access to manage agent identities, mailboxes, messages, and webhooks.

Base URL

Environment	Base URL
Production	`https://api.wirebox.sh/api/v1`
Staging	`https://staging-api.wirebox.sh/api/v1`

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

Authorization: Bearer wb_live_xxxxxxxxxxxxxxxxxxxxxxxx

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

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."
  }
}

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.