Quickstart

From a key to your first themed signal in 15 minutes. Every step names the conformance check that proves it.

Set API to your Belora API origin, APP to the app origin that serves /mcp and the event streams, and BELORA_KEY to a service key from Settings, Keys, for the curl steps. The conformance run needs a person key minted with purpose conformance instead, exported as BELORA_CONFORMANCE_KEY. Every mutating call needs an Idempotency-Key.

Run every check at once

The steps below are executable. This runs all of them against your org and reports each by its check id.

npx @belora/conformance --key $BELORA_CONFORMANCE_KEY --api $API --mcp https://mcp.belora.dev/mcp

  1. 1. Check your keyauth.whoami2 min

    Create a service key under Settings, Keys, then ask Belora who it is. The answer names your org, the key tier and what the key may do.

    curl -s "$API/v1/whoami" -H "Authorization: Bearer $BELORA_KEY"

    Proves: GET /v1/whoami with a bearer key answers its org, tier and capabilities; a missing or wrong key answers 401 unauthorized in the error envelope.

  2. 2. Send what a person saidingest.signal3 min

    Relay one human utterance. The id comes back at once, before any pipeline step runs. The human sources (support, email, chat, feedback) require the author who said it.

    curl -s -X POST "$API/v1/ingest" -H "Authorization: Bearer $BELORA_KEY" -H "Idempotency-Key: quickstart-1" -H "Content-Type: application/json" -d '{"source":"support","author":"Dana at Acme","content":"Exports time out on workspaces with more than 10k rows"}'

    Proves: POST /v1/ingest with source support and an author answers 202 with a signalId before any pipeline step runs.

  3. 3. Retry it safelyingest.idempotent1 min

    Run the same command again. The same Idempotency-Key replays the first answer, and the same words under a new key answer 200 with the original id. Nothing is filed twice.

    Repeat the previous command unchanged.

    Proves: The same Idempotency-Key and body replays the first answer, and the same content again answers 200 with the original id.

  4. 4. Watch it become themedsignal.themed4 min

    Read the signal back with the signalId from the ingest step. Its status moves from ingesting to clustering to themed, and a themed signal carries a themeId.

    curl -s "$API/v1/signals/$SIGNAL_ID" -H "Authorization: Bearer $BELORA_KEY"

    Proves: GET /v1/signals/{id} moves from ingesting through clustering to themed, and then carries a themeId.

  5. 5. Be told instead of askingwebhooks.signature4 min

    Register an https endpoint for signal.clustered. Belora signs every delivery with the secret returned once at registration; verify the signature before you trust a body.

    curl -s -X POST "$API/v1/webhooks" -H "Authorization: Bearer $BELORA_KEY" -H "Idempotency-Key: quickstart-hook" -H "Content-Type: application/json" -d '{"url":"https://example.com/belora","events":["signal.clustered"]}'

    Proves: A Belora-Signature header captured from a delivery matches hmac_sha256(secret, t + "." + raw body) for the secret and raw body supplied with it. A wrong secret or an altered body fails. Whether the delivery arrived inside the tolerance is the receiver's own check.

  6. 6. Or drive it from an agentmcp.tools1 min

    Point an MCP client at /mcp with the same key as the bearer token. Every registry operation that exposes a tool is listed by tools/list.

    claude mcp add --transport http belora "$APP/mcp" --header "Authorization: Bearer $BELORA_KEY"

    Proves: tools/list at /mcp names every registry operation that exposes a tool, and tools/call returns the /v1 body as text.

That is a themed signal. The rest of the loop, a decision answered with a person key and a job claimed, built and graded, continues in the ladder guide and the job protocol guide, and the conformance command above runs it all against your org.