Using an AI agent as an API

Every channel belongs to one agent. You create it from that agent's page in MyCrew — you do not need Workbench for this part.

1. 1
   Open the agent in MyCrew, then click the three-dot menu at the top right of its page.
2. 2
   Choose Manage from the menu.
3. 3
   On the agent's page, open the Channels tab.
4. 4
   Inside Channels, switch to the API Keys sub-tab.
5. 5
   Click Create the first channel (or New channel at the top right).
6. 6
   In the dialog, pick API key as the channel type — not Chat widget or Indexer API.
7. 7
   Give it a slug. This becomes part of the URL you call, so keep it short and URL-safe — no spaces.
8. 8
   Set a rate limit in requests per minute. 60 is a reasonable default; you can change it later.
9. 9
   Click Create & generate key.

The key is shown once, on the next screen, in the form bsk_…. Copy it into your secrets store immediately — MyCrew cannot show it to you again. If you lose it, rotate the channel to mint a new one; the old key stops working the moment you do.

Send a POST request to the agent's invoke endpoint, with your key in the X-Botspot-Key header — not Authorization: Bearer.

curl -X POST "https://api.botspot.app/agent/v1/public/agents/<slug>/invoke" \
  -H "Content-Type: application/json" \
  -H "X-Botspot-Key: bsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello" }
    ],
    "session_id": "optional-conversation-id"
  }'

Swap <slug> for the slug you chose when creating the channel, and the key for your own. The response is plain JSON:

{
  "reply": "Hi! How can I help?",
  "session_id": "optional-conversation-id"
}

messages is the whole visible thread, not just the latest line — resend every earlier turn on each call, the same way the OpenAI chat format works. The agent reads the last user turn as the one it is answering.

session_id is optional and up to you to generate (a UUID is fine). Send the same one on every call in a conversation if your agent uses memory — without it, memory nodes quietly do nothing and every call behaves like a fresh, single-shot question. The response echoes it back unchanged.

Calls are billed in BICS from the channel owner's wallet — the person or organisation that created the channel in MyCrew — never from the caller of your API. There is no sign-in on this endpoint and nothing to bill a caller to, so keep your key private the same way you would a payment credential: anyone holding it can run your agent on your account's balance.

The rate limit you set when creating the channel caps how hard your own integration can hit the endpoint. If you expect to send more than the limit you chose, raise it on the channel rather than retrying aggressively against a low one.

The response body always has a readable reason. The common ones: