API reference

Talk to your agents over HTTP — streaming, cited answers, and an OpenAI-compatible endpoint that works with the tools you already use. Create a key under Developers in your workspace, then try it below.

Try it live

Paste a key and an agent id to stream a real answer. Your key stays in the browser and is sent only to this endpoint.

API key

Agent ID

Message

Examples

Backend

Frontend

Agent frameworks

bash

# Streams a documented named-event SSE (message.delta, citations, …)
curl -N https://kissmyapps.ai/chat/api/v1/agents/agent_YOUR_AGENT/messages \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "How do refunds work?" }],
    "stream": true
  }'

Authentication

Every request needs a secret key in the Authorization header. Create one under Developers in your workspace. Keep it server-side — never ship it in a browser or app bundle.

bash

Authorization: Bearer sk_live_…

Base URL: https://kissmyapps.ai/chat/api/v1

POST

/api/v1/agents/{agentId}/messages

Talk to an agent. Set stream: true (or send Accept: text/event-stream) for token streaming; otherwise you get one buffered JSON reply. Pass a conversationId from a previous response to continue a thread.

json

// Request body
{
  "messages": [{ "role": "user", "content": "How do refunds work?" }],
  "stream": true,
  "conversationId": "conv_…"   // optional
}

Streaming — named-event SSE

event	data
`message.start`	{ conversationId, agentId } — sent first.
`citations`	{ citations: [{ n, title, url }] } — grounding sources, if any.
`message.delta`	{ delta } — a chunk of answer text.
`message.completed`	{ text, conversationId, usage } — the full answer + token usage.
`error`	{ error: { type, message } } — mid-stream failure.
`done`	[DONE] — terminator.

Buffered — JSON

json

{
  "id": "msg_…",
  "conversationId": "conv_…",
  "text": "Refunds take 3–5 business days.",
  "citations": [{ "n": 1, "title": "Refund policy", "url": "https://…" }],
  "usage": { "inputTokens": 812, "outputTokens": 34 }
}

POST

/api/v1/chat/completions

OpenAI-compatible

Drop-in for OpenAI-style clients (OpenAI SDK, LangChain, Vercel AI SDK, LiteLLM). Point the SDK’s base URL at https://kissmyapps.ai/chat/api/v1 and set the model to your agent id. Returns standard chat.completion objects / chat.completion.chunk stream (citations are omitted from this shape).

Errors

Errors return { "error": { "type", "message" } } with the status below.

Status	type	When
400	`invalid_request`	Malformed body / no user message.
401	`unauthorized`	Missing, malformed, or revoked key.
403	`agent_not_in_scope`	Key isn’t allowed to call that agent.
404	`agent_not_found`	No such agent in the key’s workspace.
429	`rate_limited`	Too many requests.
500	`internal_error`	Something went wrong our side.