whoami
Return the org, key tier and person this API key acts as.
service keydata:readread onlyoperation whoami
MCP reference
One tool per registry operation that exposes one. Arguments are a flat object: path and query parameters and body fields sit side by side.
The endpoint is stateless streamable HTTP at /mcp and takes the same bearer key as REST. Every mutating tool also accepts idempotencyKey.
claude mcp add --transport http belora "$APP/mcp" --header "Authorization: Bearer $BELORA_KEY"
list_sops
List the org's SOPs: the procedures, conventions and checks its agents follow, with the triggers that fire them. Pass repo to narrow to one repository. A stale SOP is still listed; read it with that in mind.
service keydata:readread onlyoperation sops.list
Input
| repo? | string | Only the SOPs of the repository with this full name, such as acme/app |
| cursor? | string | nextCursor of the previous page |
| limit? | integer |
get_sop
Read one SOP in full: the trigger, the steps to follow and the check to run.
service keydata:readread onlyoperation sops.get
Input
| id | string |
get_repo_doc
Read Belora's derived understanding of one repository: overview, architecture, conventions, components, features, tests, or map (everything rendered at once). Cite the headSha; a stale doc says so and you must caveat it. 404 when the repo is not observed or nothing is derived yet.
service keydata:readread onlyoperation repoDocs.get
Input
| repo | string | A repository full name such as acme/app; percent-encode the slash in a path |
| kind | "overview" | "architecture" | "conventions" | "components" | "features" | "tests" | "map" | |
| area? | string | A path prefix for a per-area doc; omit for the repo-wide one. Ignored for the map |
search_symbols
Search the exported surface of the observed repos by name: components, routes, functions, classes, schema tables, design tokens. Cite the headSha; use repo to narrow to one repository and follow nextCursor for more. For anything not exported, read the code.
service keydata:readread onlyoperation symbols.search
Input
| query | string | A symbol name or a fragment of one |
| kind? | "component" | "route" | "function" | "class" | "table" | "token" | "export" | |
| repo? | string | Only the symbols of this repository; unknown is 404 |
| cursor? | string | nextCursor of the previous page |
| limit? | integer |
get_ownership
Read who owns which areas of one repository, from CODEOWNERS and recent authors, with the evidence behind each. Only codeowners owners are reliable routes for a question; blame only suggests.
service keydata:readread onlyoperation ownership.get
Input
| repo | string | A repository full name such as acme/app; percent-encode the slash in a path |
list_technologies
List the technologies (frameworks, libraries, tools) the org's repositories depend on, each with the repos and manifest that name it. Pass repo to narrow to one repository.
service keydata:readread onlyoperation technologies.list
Input
| repo? | string | Only the technologies of this repository; unknown is 404 |
ingest
Submit an observation as a hypothesis (the default source agent), relay a human utterance (support, email, chat, feedback; author required) as a signal, or submit a meeting transcript (source meeting). Returns the id at once.
service keysignal:ingestmutatingoperation ingest
Input
Variant 1 of 2
| source? | "agent" | "support" | "email" | "chat" | "feedback" | Defaults to agent: an agent observation, filed as a hypothesis that becomes a signal only once corroborated and promoted. The human-utterance sources (support, email, chat, feedback) file a signal; author names the human who said it and, on a person key, defaults to the person the key is bound to. |
| content | string | |
| externalRef? | string | |
| author? | string | |
| occurredAt? | integer |
Variant 2 of 2
| source | "meeting" | A transcript of a meeting: filed as a receipt, processed by the meeting workflow, and turned into signals. The speakers are in the transcript, so author is not accepted. |
| title? | string | |
| externalRef? | string | |
| occurredAt? | integer | When the meeting started, in epoch milliseconds |
| participants | object[] | |
| participants[].name | string | |
| participants[].role | "engineer" | "pm" | "designer" | "manager" | "executive" | "system" | "external" | "unknown" | "customer" | |
| transcript | object | object |
pipeline_status
Return how many signals are ingesting or clustering, how many decisions await a human, and how many jobs are open, with when the snapshot was computed. Counts saturate at 1000 and are at most 5 seconds stale.
service keydata:readread onlyoperation pipeline.status
list_decisions
List pending decisions with their options and owner. ownerIsCaller is true when this key's person owns the decision, so an agent may present the options in-IDE and submit the verdict.
service keydata:readread onlyoperation decisions.list
Input
| status? | "pending" | "resolved" |
submit_verdict
Record this key's person as the decider of a decision: pick one option label and give a rationale. Refused unless the person is verified and holds the capability the decision needs.
person keydecision:resolvemutatingoperation decisions.verdict
Input
| id | string | |
| option | string | The exact label of one of the decision's options |
| rationale | string | Why this option; stored on the decision |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
list_explorations
List the open claims that need corroboration, newest first, with what each would need. Attach a finding with a falsifier to one with attach_finding; the Detective keeps corroborating on its own.
service keydata:readread onlyoperation explorations.list
Input
| cursor? | string | nextCursor of the previous page |
attach_finding
Attach a finding to an open claim as evidence from this key. A falsifier is required: say what observation would show the finding wrong. A second distinct key corroborates the claim; the same key again adds evidence but no witness.
service keyexploration:writemutatingoperation explorations.findings
Input
| id | string | |
| finding | string | What you observed that bears on the claim |
| falsifier | string | What observation would show the finding wrong |
| refs? | string[] | Urls or ids the finding rests on |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
new_session
Open a conversation session, optionally on a topic or a theme. The conversation is scratch: record what matters with session_tool, and stage one commit with session_commit for a person to confirm. A session idles out after 30 minutes.
service keyexploration:writemutatingoperation sessions.open
Input
| topic? | string | |
| themeId? | string | Scopes the session to a theme; draft_artifact needs one |
| personId? | string | The person who may read, speak in and confirm this session; defaults to the key's own person |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
list_sessions
List the open sessions this key opened or is bound to. A session is scratch conversation; the proposal is the commit.
service keydata:readread onlyoperation sessions.list
get_session
Read a session's transcript and consulted context, oldest message first. The transcript is scratch and is pruned after the session ends; the proposal is the commit.
service keydata:readread onlyoperation sessions.get
Input
| id | string |
session_say
Append a message to a live session as the agent. Every message posted through the API is the agent's; the human speaks in the console. The conversation is scratch; the proposal is the commit.
service keyexploration:writemutatingoperation sessions.say
Input
| id | string | |
| content | string | |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
session_context
Record what this session consulted (decisions, signals, files, issues) as refs with a short quote each. They become the evidence snapshot of a confirmed commit. The conversation is scratch; the proposal is the commit.
service keyexploration:writemutatingoperation sessions.context
Input
| id | string | |
| rows | object[] | |
| rows[].kind | "decision" | "signal" | "sop" | "file" | "hypothesis" | "cell" | "issue" | |
| rows[].refId | string | |
| rows[].quote | string | |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
session_tool
Run one session tool with its input. The conversation is scratch; the proposal is the commit. note_hypothesis: Record a falsifiable claim the teammate raised or implied; it shows as a maybe with the quote as evidence and changes nothing else. propose: Stage one committed claim distilled from the conversation; nothing is filed until a person confirms it. draft_artifact: Draft a reviewable document on the session's theme; calling it again revises the same document. Needs a session with a theme.
service keyexploration:writemutatingoperation sessions.tool
Input
| id | string | |
| tool | "note_hypothesis" | "propose" | "draft_artifact" | |
| input | map of any | note_hypothesis: claim, quote; propose: claim; draft_artifact: title, body |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
session_commit
Stage one committed claim distilled from the conversation (a direction chosen, a conclusion reached). A person confirms it in the rail or with their own key; staging again replaces the claim. The conversation is scratch; the proposal is the commit, and confirming it is the bound person's act.
service keyexploration:writemutatingoperation sessions.commit
Input
| id | string | |
| claim | string | The one committed statement, self-contained, in plain words |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
list_jobs
List jobs by status (open by default): the repository, the decision ref, the linked jobs, the attempts and, for a claimed one, the lease expiry and who holds it.
service keydata:readread onlyoperation jobs.list
Input
| status? | "open" | "claimed" | "closing" | "closed" |
claim_job
Claim an open job as this key's person. Returns the payload, the lease expiry and the branch to use. Refused when another executor holds it or the org already runs its maximum of jobs.
person keyjob:claimmutatingoperation jobs.claim
Input
| id | string | |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
close_job
Close a job this key claimed. Send the recap (headline, changed files, decisions, what was verified, uncertainties, and any memory deltas: procedure edits, hypotheses, vocabulary) or send none and Belora synthesizes one from the pull request diff. The pull request is attributed by its head branch, so push to the branch the claim returned.
person keyjob:claimmutatingoperation jobs.recap
Input
| id | string | |
| headline | string | |
| changed | object[] | |
| changed[].path | string | |
| changed[].what | string | |
| decisions | object[] | |
| decisions[].question | string | |
| decisions[].choice | string | |
| verified | string[] | |
| uncertainties | string[] | |
| prTitle? | string | |
| prBody? | string | |
| deltas? | object | object | object | object[] | Memory this run learned, filed for the reviewer: a procedure edit (sop_edit), a claim to test (hypothesis) or a term to coin (vocab). Nothing here changes canon on its own |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
ask_decision
Pause a job this key holds on a product question a human must answer, with 2 to 4 options. Add quick { ttlMs, onExpiry: block | proceed, assumption } to bet on a fast verdict: on expiry the job blocks as a normal decision (block) or reopens with your assumption recorded in the recap (proceed, assumption required). The job reopens for claiming once answered.
person keyjob:claimmutatingoperation jobs.pause
Input
| id | string | |
| question | string | |
| options | object[] | |
| options[].label | string | |
| options[].tradeoff? | string | |
| context? | string | |
| quick? | object | object | |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |
claim_linked_jobs
Claim every open job linked to one decision, one per repository, in one step: either all are yours or none is. The linked jobs of one decision are claimed together, all or none, so one session can do the cross-repository work.
person keyjob:claimmutatingoperation jobs.claimLinked
Input
| id | string | |
| idempotencyKey? | string | Idempotency-Key for this call: 8 to 200 printable ASCII characters. Send the same key to retry safely; omitted, one is generated per call and a retry is not deduplicated. |