API Getting Started #

The Your AI Connector REST API lets you build your own integration on top of your account. You can create and look up contacts, manage campaigns, FAQs, tasks and appointments, send messages, register webhooks, read analytics, and connect messaging channels — everything the dashboard does, driven by code.

This is the hub page for the API documentation. If you are connecting Your AI Connector to a tool that already has a built-in integration, you may not need the API at all. The API is for custom integrations and automation at scale.

Base URL #

Every request goes to the same base web address, and all paths in these docs are relative to it:

https://api.youraiconnector.com/v1

So the campaigns endpoint is https://api.youraiconnector.com/v1/campaigns, the contacts endpoint is https://api.youraiconnector.com/v1/contacts, and so on.

All requests must use a secure connection (HTTPS). Plain HTTP requests are rejected.

Getting an API key #

API access is a paid feature. If your plan does not include it, every request returns a 403 with this body:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Once API access is enabled on your plan, generate a key from the dashboard. The full step-by-step is in API Access — in short: go to Settings → Integrations → API Key to generate or regenerate your key. API Key is its own section under Integrations, separate from Webhooks, and it only appears once API access is on your plan. Treat the key like a password: it grants full access to your account.

Authentication #

You can send your API key four ways. All of them work on every endpoint that accepts API-key auth.

For production, prefer one of the header forms so your key never lands in a server log or browser history. The query-parameter form always works and is the simplest for a one-off test.

See Authentication for a full breakdown of each method, with examples and guidance on when to use which.

Your first request #

Here is a complete, working call that lists the campaigns on your account. It uses your API key and returns the most recent campaigns first.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

A successful response looks like this:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Success and error responses #

Every JSON response carries a success flag so you can branch on it without parsing status codes.

A successful response is success: true plus the data for that endpoint (the field name varies — campaigns, contacts, data, and so on):

{
  "success": true,
  "campaigns": []
}

A failed response is success: false with a human-readable error message and a numeric error_code that matches the HTTP status:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Always check success (or the HTTP status) before reading the data. See Errors & Pagination for the full status-code table and how to page through large result sets.

Rate limits #

Authenticated requests are limited to 300 requests per minute per API key. There is also a wider ceiling of 1,200 requests per minute per account, counting every authenticated request made for that account.

If you go over either limit, you get a 429 response:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Back off and retry after a short wait. You can also check your current usage at any time with GET https://api.youraiconnector.com/v1/api-keys/usage, which returns how many requests you have used in the current window and when it resets — useful for building client-side throttling. See API Keys.

Resource guides #

The resource groups below each have their own guide with the exact paths, request fields, and response shapes.

Agents, Entry Points and Broadcasts #

AI Agents, Entry Points and Broadcasts are all in the published OpenAPI specification, so you can browse their exact fields and run live requests against them in the API explorer. Each has its own guide: AI Agents, Entry Points and Broadcasts.

Reading these docs as Markdown #

Every page in this documentation has a plain-Markdown twin: take the page address and add /index.md to the end. So this page is also available at https://docs.youraiconnector.com/api/getting-started/index.md, and it comes back as plain text rather than a web page — handy when you want to paste a page into an AI assistant or pull it into a script.

To walk the whole set, start from https://docs.youraiconnector.com/sitemap.xml, which lists every page we publish. Note that the documentation is deliberately kept out of search engines, so fetching these addresses directly is the way to reach it from code.

There is no key-protected documentation endpoint and no bulk download yet — the Markdown twins and the sitemap are the whole interface, and neither needs an API key.

Next steps #

• Authentication — pick the right auth method for your integration.
• Errors & Pagination — handle failures and page through results.
• API Access — generate your key and see worked examples.