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

# Developer hub: API sandbox, recent requests and API docs

> See your recent Flowella API requests, switch the organisation-wide API sandbox on or off, and open quickstarts, interactive API docs, Postman and OpenAPI.

The Developer hub brings together what you need to build on the [Flowella REST API](https://knowledge.flowella.io/api-reference/introduction.md). It shows the API address, a log of recent API requests, the organisation-wide **API sandbox** switch, quickstarts and links to the API docs.

To open it, go to **Settings**, then select **Developer hub** in the **Developer** group.

## Who can use it

| Part of the hub | Who can use it |
| - | - |
| **API base URL**, **Quickstarts** and **Links** | Everyone in the organisation. |
| **Recent API requests** | Owners and Admins. For other roles the card shows no requests. |
| **API sandbox** | Everyone can see whether it is **Active** or **Off**. Only Owners and Admins can turn it on or off. |
| The API keys and developer apps that the links open | Owners and Admins. See [API keys](https://knowledge.flowella.io/settings/api-keys.md) and [Developer apps](https://knowledge.flowella.io/settings/developer-apps.md). |

## API base URL

This card shows the address of the REST API. In your integration, use `https://api.flowella.io/v1` as the base URL, even if the card shows an address ending in `/api/v1`. See [Base URL](https://knowledge.flowella.io/api-reference/introduction.md#base-url) for why.

## Recent API requests

This card lists the 25 most recent API requests made to your organisation with API keys or OAuth access tokens, newest first.

| Column | What it shows |
| - | - |
| **Time** | When Flowella received the request. |
| **Method** | The HTTP method, for example `POST`. |
| **Path** | The endpoint that was called. |
| **Status** | The HTTP status Flowella returned. |
| **Actor** | Who made the call: `key:` followed by an identifier for an API key, or `oauth:` followed by the client ID of an OAuth app. The `key:` identifier is not the key prefix shown on the API keys screen. |
| **Request id** | The request's ID, the same value as the `X-Request-Id` response header. |

Requests that Flowella refuses before running them are not listed. These include requests with a missing or invalid token, a missing scope, an unsupported `API-Version` header, or one over the rate limit.

To see everything linked to a request, such as the events, jobs and webhook deliveries it caused, call `GET /v1/requests/{requestId}` with the **Request id**. It needs the `account:read` scope. See [Request IDs](https://knowledge.flowella.io/api-reference/introduction.md#request-ids).

## API sandbox

The **API sandbox** card has an organisation-wide switch for testing without sending anything to WhatsApp. The badge shows **Active** when the sandbox is on and **Off** when it is off. **Sandbox guide** opens the sandbox guide in the app.

To turn the sandbox on, an Owner or Admin ticks the checkbox at the bottom of the card. Untick it to turn the sandbox off. The change applies at once to the whole organisation. You can also read and change the setting with `GET /v1/sandbox` and `PATCH /v1/sandbox`, using the body `{ "enabled": true }` or `{ "enabled": false }`. Both need the `sandbox:manage` scope.

> [!WARNING]
>
> The API sandbox affects more than API calls. While it is on, [Bulk send](https://knowledge.flowella.io/app/bulk-send.md) in the app and the **Send WhatsApp Template** action in HubSpot workflows also stop reaching contacts. Replies from the inbox and the **Send WhatsApp Message** and **Send WhatsApp Reply** HubSpot actions still send for real. Turn the sandbox off as soon as you finish testing.

### API sandbox and sandbox keys

There are two ways to use the sandbox. The organisation-wide **API sandbox** covers every request, while a [sandbox key](https://knowledge.flowella.io/settings/api-keys.md#sandbox-keys) covers only the requests made with that key.

| | Organisation-wide **API sandbox** | **Sandbox key** |
| - | - | - |
| How you turn it on | An Owner or Admin ticks the switch here, or calls `PATCH /v1/sandbox`. | Tick **Sandbox key** when you create an API key. |
| Which requests it covers | All API requests in the organisation, from any API key or OAuth app. | Only requests made with that key. |
| `POST /v1/messages` | Stored in Flowella, not sent. | Stored in Flowella, not sent. |
| Template submission | Instant mock decision. | Instant mock decision. |
| Template test sends | Skipped. | Skipped. |
| `POST /v1/templates/send` | Recipients are recorded as done, nothing is sent. | Sent for real. |
| **Bulk send** in the app and the HubSpot **Send WhatsApp Template** action | Recipients are recorded as done, nothing is sent. | Not affected. |

### What changes in the sandbox

When the sandbox covers a request:

* `POST /v1/messages` stores the message in the conversation and returns `"sandbox": true` with `metaMessageId` set to `null`. Nothing reaches WhatsApp, and no `message.sent` webhook fires.
* Template submission with `POST /v1/templates/{id}/submit` does not reach Meta. It approves the template at once, or rejects it if the template name contains `reject_`. A media header whose sample is only a web address is refused with `400 INVALID_TEMPLATE_COMPONENTS`. The decision appears in the API and the event feed, but the **Templates** page in the app does not change.
* The sandbox runs in your real organisation. Contacts, conversations and messages created during tests are stored like any others and appear in the app.

### Sandbox test tools

These endpoints help you simulate activity. They need the `sandbox:manage` scope, and they work whether or not the sandbox is on, so use them only with test data.

| Method | Path | What it does |
| - | - | - |
| `GET` | `/v1/sandbox/status` | Returns whether the API sandbox is on, and `sandboxKey`, which says whether your key is a sandbox key. |
| `POST` | `/v1/test/contacts` | Creates or updates a contact from `phone` and an optional `name` and `email`. |
| `POST` | `/v1/test/messages/{id}/simulate-status` | Adds a `message.sent`, `message.delivered`, `message.read`, `message.failed` or `message.accepted` event for a message to the event feed. Send the `status` without the `message.` prefix. |
| `POST` | `/v1/test/webhooks/replay-event` | Adds an event of the `type` you choose to the event feed. |
| `POST` | `/v1/sandbox/fixtures/reset` | Clears sandbox events, sandbox jobs and mock template decisions. `POST /v1/test/reset` does the same. |

The test tools write only to the event feed (`GET /v1/events`). They do not send webhooks or change the message itself.

## Quickstarts

The **Quickstarts** card links to step-by-step guides. Each opens as a Markdown file in a new tab.

| Quickstart | What it covers |
| - | - |
| Salesforce | OAuth install, template send and form ingest. |
| Zoho CRM | Contact bulk upsert and outbound webhooks. |
| SurveyMonkey | Mapping survey details and inbound webhooks. |
| Typeform | Typeform provider flows and inbound webhooks. |
| n8n | HTTP Request nodes that call the API. |

## Links

| Link | What it opens |
| - | - |
| **Interactive API docs** | The API reference in the app, with request schemas and try-it examples. Paste an API key to send test requests. |
| **Manage API keys** | [API keys](https://knowledge.flowella.io/settings/api-keys.md), where you create and revoke keys. |
| **Developer apps** | [Developer apps](https://knowledge.flowella.io/settings/developer-apps.md), where you register OAuth apps. |
| **OpenAPI JSON** | The OpenAPI document for the API, which you can import into Postman, Insomnia or a code generator. |
| **Postman collection** | Downloads `flowella-v1.postman_collection.json`. |
| **Capabilities matrix (authenticated)** | `GET /v1/capabilities`, which lists your token's scopes, whether the sandbox is on, and supported message types and template categories. It needs an API key with the `account:read` scope, so a browser tab shows an authentication error. Call it from your API client instead. |

## Related

> **[API introduction](https://knowledge.flowella.io/api-reference/introduction.md)**
>
> Authentication, scopes, rate limits and errors.

> **[API keys](https://knowledge.flowella.io/settings/api-keys.md)**
>
> Create live and sandbox keys.

> **[Developer apps](https://knowledge.flowella.io/settings/developer-apps.md)**
>
> Register an OAuth app and manage installed apps.

> **[Webhooks reference](https://knowledge.flowella.io/api-reference/webhooks.md)**
>
> Event types, payloads and signature checks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.