AEO DIRECT ANSWER API Reference Summary

Thunaivi Developer Integration API

Official REST API for connecting external CRMs, custom databases, and support ticketing workflows to Thunaivi. Supports tenant-scoped API authentication, high rate-limit throughput, and real-time webhook events.

Thunaivi Integration API

Developer API reference for secure CRM and ticket automation

Use tenant-scoped API keys to connect external systems (CRM/helpdesk/custom backend) with Thunaivi integration endpoints.

Last updated: March 4, 2026 · OpenAPI JSON available on request via technical team.

Get API Key Talk to Technical Team

Base URL

https://brain.thunaivi.io/api

Integration endpoints are currently exposed under /api/integrations/*.

Authentication

Authorization: Bearer tvk_live_...
Content-Type: application/json
Accept: application/json

Generate keys from Client Portal -> API Keys. Full secret is shown once.

Troubleshooting

About /api/v1: If you open /api/v1 in browser and see 404, that is expected for this integration API. Use the documented integration endpoints below.

Operations (Swagger-style summary)

GET /integrations/me

Validate API key and return tenant context bound to that key.

Auth: Bearer API key Scope: any valid key

curl --request GET \
  --url https://brain.thunaivi.io/api/integrations/me \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

{
  "ok": true,
  "tenant_id": "ce15ac3e-45b6-4e21-a465-e0dca27175a5",
  "tenant_name": "Acme Support",
  "account_id": "12",
  "key_id": "3884ccbc-1f98-4685-8912-407826c10709",
  "key_name": "CRM Production",
  "scopes": ["crm:read", "tickets:write"]
}

POST /integrations/crm/ticket-sync

Accept ticket sync payload from external CRM/helpdesk for secure asynchronous processing.

Auth: Bearer API key Scope: tickets:write Response: 202 Accepted

curl --request POST \
  --url https://brain.thunaivi.io/api/integrations/crm/ticket-sync \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "external_ticket_id": "ZD-98322",
    "external_system": "zendesk",
    "customer": { "email": "[email protected]" },
    "payload": {
      "subject": "Order tracking delay",
      "status": "open",
      "priority": "high"
    }
  }'

{
  "ok": true,
  "message": "Ticket sync accepted",
  "tenant_id": "ce15ac3e-45b6-4e21-a465-e0dca27175a5",
  "account_id": "12",
  "external_ticket_id": "ZD-98322",
  "external_system": "zendesk"
}

Error model

Integration API currently returns concise JSON errors:

{ "error": "Missing API key" }

400 Validation error (example: missing external_ticket_id)
401 Missing/invalid/revoked/expired API key
403 Missing required scope, IP not allowed, or tenant inactive
429 Rate limit exceeded for key
500 Internal processing error

Rate limits and security

Per-key rate limit is enforced server-side (rate_limit_per_minute on key).
Default key limit is 120 requests/min unless customized by admin/client key settings.
Optional IP allowlist is supported per key.
All usage is logged for billing, analytics, and audit controls.
Use server-to-server calls only; never expose keys in frontend JavaScript.

API key lifecycle

Create key in Client Portal -> API Keys.
Copy full key once and store in vault/secret manager.
Set scopes, expiry, rate limit, and IP allowlist.
Rotate keys regularly; revoke immediately if compromised.

Webhooks

Public outbound integration webhooks are in staged rollout.

Current best practice: poll your target state via API and keep your consumer idempotent for safe retries.

Ready to integrate?

Issue a tenant key, test /integrations/me, then move to ticket sync with strict scope and IP controls.

Open Client Portal Contact Technical Team