Developer API

API Keys

API keys are issued per workspace when your plan is activated and delivered to your billing email. Keys carry the prefix sk-dev- and should be treated like passwords: keep them server-side, rotate them quarterly, and never expose them in client-side code. You can request a rotation or additional keys at any time by emailing [email protected].

Authentication

All requests authenticate with a Bearer token in the Authorization header. The base URL for all endpoints is https://api.ciheco.com/v1.

curl https://api.ciheco.com/v1/chat/completions \
  -H "Authorization: Bearer sk-dev-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "support",
    "messages": [
      {"role": "user", "content": "Where is my order #4821?"}
    ]
  }'

Endpoints

Method	Endpoint	Description
POST	/v1/chat/completions	Send a conversation to an agent and receive a model response.
GET	/v1/agents	List the AI agents deployed in your workspace.
POST	/v1/agents	Create and configure a new agent (model, tone, knowledge base).
GET	/v1/usage	Conversation counts, token usage and cost breakdown per period.
GET	/v1/conversations	Paginated conversation transcripts with resolution metadata.
POST	/v1/webhooks	Register a webhook URL for escalation and resolution events.

Code Examples

JavaScript (fetch)

const res = await fetch("https://api.ciheco.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-dev-YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent: "support",
    messages: [{ role: "user", content: "Summarize today's tickets" }]
  })
});
const data = await res.json();
console.log(data.choices[0].message.content);

Python (requests)

import requests

res = requests.post(
    "https://api.ciheco.com/v1/usage",
    headers={"Authorization": "Bearer sk-dev-YOUR_KEY"},
    json={"period": "last_30_days"},
)
print(res.json())

Rate Limits

Plan	Requests	Conversations / month
Paid Pilot	60 req/min	Up to 50K (pilot window)
Enterprise	300 req/min (custom)	Custom volume

Errors

Code	Meaning	Action
401	Invalid or revoked API key	Check the key or request a rotation.
402	Plan quota exceeded	Upgrade your plan or add a conversations pack.
429	Rate limit hit	Retry with exponential backoff.
500	Platform error	Retry once, then contact support.

Webhooks

Register an HTTPS endpoint to receive signed JSON events for conversation.resolved, conversation.escalated and quota.warning. Every delivery is retried with backoff for up to 24 hours and signed with your workspace secret so you can verify authenticity.