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

# API Overview

> How the Tuco AI API behaves from your point of view. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples in curl, Node.

## What the API Provides

The Tuco AI API lets your own systems work directly with the same data you see in the Tuco dashboard.

You can:

* Create and update leads.
* View and organize leads and lines.
* Send messages through your approved sending identities.
* Receive notifications when important events occur.

The system automatically keeps behavior consistent between the API and the product UI, so the same actions feel familiar in both places.

***

## Access & Authentication

API access is controlled from within your Tuco workspace.

You decide:

* Which workspaces may use the API.
* Which environments may use production data.

Once access is enabled, you receive credentials that allow your backend to act on behalf of your workspace. No action is required from you to keep these credentials recognized by Tuco; if they need to be changed or rotated, you handle that entirely from your own settings.

***

## Authorization with Tuco API Keys

Tuco uses a workspace‑level API key for server‑side access.

From your perspective:

* Each key clearly belongs to a specific workspace.
* You can enable or disable keys without affecting the rest of the product.
* Requests made with a valid key are treated as coming from your workspace.

You use the same Tuco key across all documented endpoints. For details on where to find this key and how it appears in the header, see `/api-reference/api-keys`.

***

## Request & Response Shape

All endpoints follow a simple pattern:

* A request either **succeeds** and confirms what was accepted.
* Or it **fails** and clearly indicates why.

You can rely on:

* Standard HTTP status codes to understand whether a call worked.
* Human‑readable messages that explain what went wrong when something is rejected.

Data is preserved safely, so successful calls appear in the Tuco UI and can be used in campaigns, reporting, and audits.

***

## Correlation IDs (request tracing)

Every request that hits a Tuco send endpoint can be tagged with a correlation
ID. Pass it either as a header or as a field on the JSON body — whichever is
easier from your client. If you don't pass one, Tuco generates a server-side
ID prefixed `app_…` and threads it through the rest of the pipeline.

| Where              | Name               | Example                                              |
| ------------------ | ------------------ | ---------------------------------------------------- |
| Header (preferred) | `x-correlation-id` | `x-correlation-id: my-svc_2026-05-29_a73f9c`         |
| JSON body field    | `correlationId`    | `{ "correlationId": "my-svc_2026-05-29_a73f9c", … }` |

The ID propagates into every Loki event for that send — `message.api.request`,
`message.api.create_message_returned`, `cap.reservation.entered/granted/denied`,
`message.send.summary`. Grepping a single ID lets you reconstruct the whole
request → gate → send → webhook chain.

A few endpoints accept additional trace headers when integrating with a
specific source system, so the same ID can stitch across multiple services:

* `x-execution-id` — GHL workflow execution ID (forwarded by tuco-ghl).
* `x-ghl-workflow-id` — GHL workflow definition ID.

These are optional and only relevant when you are calling Tuco from another
service that already has its own correlation context.

***

## Reliability & Limits

The API is designed so that normal usage from typical business systems works without special tuning.

If you reach a documented limit, you see clear error responses and nothing is changed unexpectedly. The system automatically handles internal protections to keep your account and recipients safe.

For specific status codes and common outcomes, see `/api-reference/errors`.

***

## SDKs & Tools (Coming Soon)

Official SDKs and helper libraries for popular languages are **Coming Soon**.

They will focus on giving you a smoother developer experience without exposing any internal implementation details of Tuco AI.