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

# Introduction

> An overview of the API — what it does, how to authenticate, make requests, and read responses.

## What is this?

The API lets you connect your own systems to your workspace — sync contacts from a CRM, send an order-confirmation template from your app, or trigger an automation when something happens.

The API is listed in the sidebar with every endpoint:

| Part              | Use it to                                                                                                          | Access                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| **Workspace API** | Manage channels, contacts, labels, custom fields, WhatsApp messages and templates, and automations for a workspace | Any user with an API key |

<Info>
  Opening the Developer Portal — where you create your API key and can try requests — requires the **API Access** permission (`settings:api`). Ask an administrator to grant it if you can't see **Developer** in the profile menu.
</Info>

## Base URL

Every request goes to your own deployment:

```text theme={null}
https://YOUR_DOMAIN/api/workspace/v1/...
```

Replace `YOUR_DOMAIN` with the domain you sign in to, for example `app.example.com`.

## Request format

* Every endpoint accepts **POST** with a JSON body, and also accepts **GET** with the same parameters as query-string values. Prefer POST for anything that writes data.
* Send `Content-Type: application/json` with POST requests.
* Only the API key must go in a header — see [Authentication](/api-reference/authentication).
* All responses use one envelope: `{ "success": true, "data": … }` or `{ "success": false, "error": "…", "message": "…" }`. See [Errors](/api-reference/errors).

## Make your first request

<Steps>
  <Step title="Get an API key">
    In the app, open the profile menu, choose **Developer**, and click **Generate API Key**. Copy it right away — it's shown only once.
  </Step>

  <Step title="List your channels">
    Find the `channelId` you'll use in other requests:

    ```bash theme={null}
    curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/channels/list" \
      -H "X-API-Key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="Send a template message">
    ```bash theme={null}
    curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/whatsapp/templates/send" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "to": "919876543210",
        "templateName": "order_update",
        "variables": "John,ORD-1234"
      }'
    ```
  </Step>
</Steps>

If your account has only one channel, `channelId` is picked for you. With several channels, pass `channelId` explicitly.

## Try requests and download the spec

Each endpoint page in this reference has a request playground. The Developer Portal in the app also lets you try requests using your own session, and download the machine-readable definition as **OpenAPI JSON**, **OpenAPI YAML**, or a **Postman collection**.

## Troubleshooting / Technical Notes

* **You get `401`.** The key is missing or wrong, or you sent it in the query string or body. See [Authentication](/api-reference/authentication).
* **You get `429`.** You've hit a rate limit — see [Rate limits](/api-reference/rate-limits).
* **"No channel found for this user."** Pass a `channelId`, or create a channel first. Use **List channels** to find your IDs.

## Related docs

* [Authentication](/api-reference/authentication)
* [Rate limits](/api-reference/rate-limits)
* [Errors](/api-reference/errors)
* [Channels](/workspace/channels)
* [Team](/workspace/team)