Public API

The public API lets your own servers call your agents. It’s separate from the dashboard: its own keys, its own docs, its own limits.

Base URL: https://api.backcrew.ai/v1
Interactive reference: https://api.backcrew.ai/v1/docs

Authentication

Create a secret key in Settings → API Keys. It starts with bk_live_ and is shown once - store it somewhere safe. Send it on every request:

Authorization: Bearer bk_live_...

List your agents

curl https://api.backcrew.ai/v1/agents \
  -H "Authorization: Bearer $BACKCREW_API_KEY"

[{ "id": "7c9f…", "name": "support-bot", "status": "deployed" }]

Only deployed agents can answer.

Send a message

POST /v1/agents/{agent_id}/invoke

Field	Required	Meaning
`prompt`	yes	The message.
`session_id`	no	Groups messages into one conversation.
`user_id`	no	Your own id for the person you’re acting for. With memory on, each `user_id` gets its own memory.

curl -X POST https://api.backcrew.ai/v1/agents/$AGENT_ID/invoke \
  -H "Authorization: Bearer $BACKCREW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Where is my order?", "user_id": "customer-123", "session_id": "conversation-1"}'

{
  "response": "Your order shipped yesterday and should arrive on Thursday.",
  "usage": { "input_tokens": 1240, "output_tokens": 310, "credits_charged": 5, "unmetered": [] }
}

The full reply comes back once the agent finishes - responses aren’t streamed.

Python

import os, requests

res = requests.post(
    f"https://api.backcrew.ai/v1/agents/{os.environ['AGENT_ID']}/invoke",
    headers={"Authorization": f"Bearer {os.environ['BACKCREW_API_KEY']}"},
    json={"prompt": "Where is my order?", "user_id": "customer-123"},
    timeout=320,
)
res.raise_for_status()
print(res.json()["response"])

JavaScript

const res = await fetch(`https://api.backcrew.ai/v1/agents/${agentId}/invoke`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BACKCREW_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "Where is my order?", user_id: "customer-123" }),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log((await res.json()).response);

Errors

Status	Meaning
`401`	Missing, unknown or revoked key.
`402`	The workspace is out of credits (or past its monthly limit).
`404`	No agent with that id in this key’s workspace.
`409`	The agent isn’t deployed right now (e.g. it’s updating).
`429`	Rate limit reached - wait for the `Retry-After` seconds.
`502`	The agent failed to answer.
`504`	The agent took longer than the maximum request time (5 minutes).

Limits and cost

60 requests a minute per key.
Each call costs credits exactly like a request from the dashboard - see Credits.