> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> The Xobito REST API lets you manage contacts, send WhatsApp messages, and receive outbound webhook events from any backend language.

<Note>
  **Platform version: v3.0.0** (released May 2026). The REST API is unchanged from v2.x — same base URL, same `v1` versioning, same auth, same envelope. See the [Changelog](/changelog) for the full v3.0.0 release notes.
</Note>

The Xobito API is a JSON-over-HTTPS REST API. It mirrors what the dashboard does — create contacts, send text / template / media / interactive / CTA-URL messages, and receive outbound webhook events for contact, status, and source changes. (Message status polling and phone-number validation endpoints are scheduled for a future release.)

This page is your starting point. If you already know the shape of REST APIs, skim the section below and jump to [Authentication](/developers/authentication).

## Base URL

The API is hosted on the main Xobito host. Your workspace subdomain is a **path parameter** — it is not a host-level subdomain.

```
https://dash.xobito.com/api/v1/{subdomain}/...
```

| Segment       | Example           | Notes                                          |
| ------------- | ----------------- | ---------------------------------------------- |
| Host          | `dash.xobito.com` | The single API host for all workspaces.        |
| `/api/v1/`    | —                 | Current API version.                           |
| `{subdomain}` | `acme`            | Your workspace subdomain, as a path parameter. |

### Example

If your workspace subdomain is `acme`, a list-contacts call looks like:

```
GET https://dash.xobito.com/api/v1/acme/contacts
```

<Note>
  The subdomain is part of the path, not the host. Do not call `acme.xobito.com` — that is the dashboard host, not the API.
</Note>

## Content type

All requests and responses use JSON.

| Header         | Value                                          |
| -------------- | ---------------------------------------------- |
| `Accept`       | `application/json`                             |
| `Content-Type` | `application/json` (on `POST`, `PUT`, `PATCH`) |

## Authentication at a glance

Xobito uses **bearer tokens**. Generate a token in the dashboard under **Settings → API Management**, then send it on every request:

```
Authorization: Bearer <your_token>
```

Tokens carry **scoped abilities** — a token limited to `contacts.read` cannot send messages. Full details in [Authentication](/developers/authentication).

## Rate limits at a glance

The default rate limit is **60 requests per minute, per token**. When you exceed the limit you receive `429 Too Many Requests` with a `retry_after` field in the JSON body. Full details in [Rate Limits](/developers/rate-limits).

## Response envelope

All successful responses use a consistent envelope:

```json theme={null}
{
  "status": "success",
  "data": { ... },
  "message": "..."
}
```

All errors use:

```json theme={null}
{
  "status": "error",
  "message": "...",
  "errors": { ... }
}
```

See [Errors](/developers/errors) for every error shape this API can return.

## Webhooks

Xobito can push events to your server for (1) **contacts / statuses / sources** CRUD events, and (2) **message delivery status** events (`message.sent`, `message.delivered`, `message.read`, `message.failed`) — the latter live as of 2026-05-28. Campaign events, template approval events, ticket events, and conversation events do **not** fire outbound webhooks; poll the relevant endpoint.

Start with [Webhooks Overview](/developers/webhooks-overview) and [Webhook Events](/developers/webhook-events).

## SDKs

There are no official Xobito SDKs. The API is small and every endpoint in this reference ships with ready-to-copy examples in cURL, JavaScript, Python, and PHP.

## Quick tour

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/authentication">
    Generate and use API tokens.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/developers/rate-limits">
    How throttling works and how to back off.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/developers/errors">
    Every error shape and what it means.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developers/webhooks-overview">
    Receive contact, status, and source events.
  </Card>

  <Card title="Data Types" icon="brackets-curly" href="/developers/data-types">
    Canonical schema for every object.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Endpoint-by-endpoint reference.
  </Card>
</CardGroup>

## Versioning

* The current API version is `v1`.
* Additive changes (new fields, new endpoints) ship inside `v1`.
* Breaking changes ship under a new version prefix.
* Depend on JSON field names, not ordering.