API
One endpoint, one API key, a real point of view instead of a neutral customer-service voice. This page covers authentication, the request/ response shape, and how to give Clancy a distinct persona for a specific integration.
https://us-central1-clancy-793e9.cloudfunctions.netEvery path below is relative to this.
Every request needs a Bearer API key in the Authorization
header. Generate one from your dashboard — you'll
need an active plan first. Keys are shown once at creation time; if you
lose one, revoke it and create a new one.
Authorization: Bearer clc_live_xxxxxxxxxxxxxxxxxxxxxxxxSend a message, get a response back. Optionally include prior turns so Clancy has context across a multi-turn conversation.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
input | string | Yes | The user's message. Max 8,000 characters. |
history | array | No | Prior turns, oldest first: [{role, content}, ...] where role is "user" or "assistant". Last 20 turns are kept; each turn's content is capped at 4,000 characters. |
curl -X POST https://us-central1-clancy-793e9.cloudfunctions.net/clancyComplete \
-H "Authorization: Bearer clc_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"input": "What do you think of this chord progression -- Am F C G?",
"history": [
{ "role": "user", "content": "I am writing a sad indie folk song." },
{ "role": "assistant", "content": "Nice -- what key are you thinking, and how bare do you want the arrangement?" }
]
}'Response
{
"output": "Am-F-C-G works, but it's the most-used progression in the genre for a reason -- it's safe. If you want it to feel sadder rather than just familiar, try...",
"usage": {
"promptTokens": 142,
"completionTokens": 87,
"totalTokens": 229
}
}
There's no persona or system
field in the request body — persona is set once per API key, not
per call. When you create a key from the dashboard, you can attach a
persona describing how Clancy should behave for calls made with
that key. This is what lets you run more than one
integration (a different product, a staging vs. production key,
whatever) from the same account, each with its own voice, without
the request shape changing at all.
Leave persona blank on a key and it uses Clancy's default voice.
| Status | Meaning |
|---|---|
| 400 | input missing or empty. |
| 401 | Missing, invalid, or revoked API key. |
| 403 | Account not active (subscription lapsed or canceled). |
| 429 | Monthly budget reached (Basic tier only — see Usage & billing below). |
| 502 | Model backend unavailable. Safe to retry. |
Error responses are JSON: { "error": "..." }.
Usage is metered in tokens (prompt + completion) and billed against whichever plan is active on your account — see pricing for current tiers. All keys on one account share that account's usage and budget; which specific key made a call doesn't change how it's billed.
Basic plan accounts have a monthly overage budget (default: none — requests fail with 429 once the included quota is used, until you raise your budget from the dashboard). Studio and Growth bill overage automatically with no cap.