Skip to main content

​
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.
WhereNameExample
Header (preferred)x-correlation-idx-correlation-id: my-svc_2026-05-29_a73f9c
JSON body fieldcorrelationId{ "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.