Guide

Quickstart

Create a scoped credential, make a first call, then choose REST, MCP, or both for your agent runtime.

1. Create a key

Open Dashboard → Developer, choose Create key, and select full, read-only, or custom access. Copy the secret immediately; only its hash remains stored.

Use environment variables

Store the key as CHATTERBEAM_API_KEY in your server-side secret manager. Never place it in prompts, browser code, source control, query strings, or webhook payloads.

2. List projects

cURL

curl "https://chatterbeam.com/api/v1/projects" \
  --header "Authorization: Bearer $CHATTERBEAM_API_KEY" \
  --header "X-Request-Id: my-agent-run-0001"

Response

{
  "data": { "projects": [] },
  "meta": {
    "capability": "list_projects",
    "requestId": "my-agent-run-0001",
    "idempotencyReplayed": false
  }
}

3. Make a safe write

Send a unique idempotency key on every write. Retrying the same request returns the original response; reusing the key with different input is rejected.

Create keyword

curl "https://chatterbeam.com/api/v1/keywords" \
  --request POST \
  --header "Authorization: Bearer $CHATTERBEAM_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: run-42-create-keyword" \
  --data '{"projectId":"PROJECT_ID","value":"your brand","sources":["x","reddit","youtube"]}'

4. Connect MCP

Add https://chatterbeam.com/mcp to a Streamable HTTP MCP client. Compatible clients discover ChatterBeam OAuth automatically; trusted server-side clients may instead use a scoped API key.

Read the MCP setup guide