Skip to content

All resources

agents

12 endpoints

get /agent-consents

The caller's consent inbox

Requires authentication

Returns the pending "somebody wants to run work on YOUR machine" requests addressed to the caller. Only the device owner ever sees these, and only the device owner can decide them — there is no admin override anywhere in this feature.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /agent-consents/{uuid}

Approve, deny or revoke a consent request

Requires authentication

Records the device owner's decision. ONLY the executor — the person whose machine, checkout, keys and network are involved — may decide; not an admin, not the org owner, not the requester. On approval the SAME run row is resumed (awaiting_consent is re-routed and dispatched); a child run is never inserted, because the parent still holds the requester's in-flight slot and the fallback anybody reaches for on that rejection appends the approval to the run that is waiting for it.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesConsent request UUID

Request body: handler.DecideConsentRequest

NameTypeRequiredDescription
statusobjectnoStatus is one of approved / denied / revoked.

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope

get /agent-devices

List the org's paired devices

Requires authentication

The org's live devices, freshest heartbeat first. Revoked devices are absent: the row is kept so the runs that executed on the machine keep pointing at it, but a revoked device is not a device anybody can act on.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /agent-devices

Pair a machine to the caller

Requires authentication

Mints a device credential for the signed-in person's own machine and returns the raw secret ONCE. Enrollment CONFIRMS a device; it never authenticates one — there is no endpoint anywhere that turns an unauthenticated claim about a machine into a device row, so a human session is the only thing that can bring one into existence. The scope set must be non-empty and drawn from the closed set {read_repo, write_repo, run_tests, run_shell, network}: unlike api_tokens, an empty set is refused rather than treated as "everything", because what it would silently authorize is shell execution on somebody's laptop.

Request body: handler.EnrollDeviceRequest

NameTypeRequiredDescription
labelstringno
maxConcurrentintegernoMaxConcurrent is bounded to 1..16 by ck_agent_devices_max_concurrent.
platformstringno
scopesdomain.DeviceScope[]no

Responses

  • 201 Created · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 429 Too Many Requests · apimodel.ErrorEnvelope

delete /agent-devices/{uuid}

Revoke a paired device

Requires authentication

Ends a device immediately and totally. IMMEDIATE because every daemon route resolves its caller by secret hash on every request and that lookup rejects a revoked row — there is no cached session and no independently-lived token to wait out, and an open /daemon/connect stream closes on its next keepalive. TOTAL because revocation is stamped on the row the secret hashes to, so it applies to the credential itself rather than to something derived from it. The row is NOT deleted: the runs that executed on the machine keep pointing at it.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesDevice UUID

Responses

  • 204 No Content · string
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

get /agent-runs/{uuid}

Read one agent run

Requires authentication

Returns a run's current state and both of its principals. Reachability is the run's CHANNEL — the sole authz anchor of the chat feature — so anyone who can read the conversation can see that a run happened in it.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesRun UUID

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

delete /agent-runs/{uuid}

Cancel an agent run

Requires authentication

Stops a run and revokes its per-run credential. The requester may always stop their own; anybody else needs channel MANAGE, because cancelling somebody else's work is an administrative act rather than a participating one.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesRun UUID

Responses

  • 204 Cancelled
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

get /agent-runs/{uuid}/events

Read a run's transcript

Requires authentication

Returns the append-only tool-by-tool transcript of a run, forward from a cursor. Keyset on `seq`, never OFFSET. This — not the channel — is where the detail lives: the agent's ANSWER is posted into the conversation as a normal message, and pasting a transcript there instead would turn a channel into a log file.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesRun UUID
afterqueryintegernoReturn events after this seq
limitqueryintegernoPage size (max 200)

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

get /agents

List the org's agents

Requires authentication

Returns the agents defined in the caller's organization, by handle. An agent is a PERSONA; the identity it authors messages and holds memberships with is a linked `users` row carrying kind='agent' (migration 0039), which is why there is no avatar field here — the avatar is that user's.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope

post /agents

Create an agent

Requires authentication

Mints a new agent in the caller's organization: the persona, the `users` row that carries kind='agent' and is what @mentions and authorship resolve against, and the org membership that makes it reachable (channel_access joins org_members). Requires org.manage — an agent is a PRINCIPAL whose project_scope='all' reaches every project in the org, so a member who cannot reach every project must not be able to mint one that can. It costs no seat. The logo is written to the agent's actor row, never to `agents`, which has no avatar column by design.

Request body: handler.CreateAgentRequest

NameTypeRequiredDescription
avatarUrlstringnoAvatarURL is the agent's logo as a small client-resized `data:image/...` URL, the same shape and the same 100KB cap as dto.UpdateAvatarRequest. It is written to the agent's ACTOR row (users.avatar_url), because migration 0048 deliberately gives `agents` no avatar column.
handlestringnoHandle is what people type after '@'. Lowercased and validated against ck_agents_handle_shape; a leading '@' is accepted and stripped.
instructionsstringnoInstructions is the persona prompt, at most 16KB.
invocationScopestringno
namestringnoName is the display name, 1-80 characters.
policyProfilestringno
projectScopestringnoProjectScope, PolicyProfile and InvocationScope default to what the org's own BugBuddy is minted with. 'selected' is refused here — see AgentService.CreateAgent.

Responses

  • 201 Created · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope

patch /agents/{uuid}

Update an agent

Requires authentication

Applies a partial edit to one agent in the caller's organization. Requires org.manage: `instructions` is the standing prompt every future run executes under on behalf of whoever mentions the agent, so editing it is administration however small the diff. The handle is immutable — the actor's reserved address is derived from it. Setting projectScope to 'selected' while nothing is selected is rejected by trg_agents_project_scope at COMMIT and reported as 400.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesAgent UUID

Request body: handler.UpdateAgentRequest

NameTypeRequiredDescription
avatarUrlstringno
enabledbooleanno
instructionsstringno
invocationScopestringno
namestringno
policyProfilestringno
projectScopestringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope

post /channels/{uuid}/agent-runs

Invoke an agent in a channel

Requires authentication

Turns an @agent mention into a run and routes it. Routing starts at tier 0 (server-side, read-only, no daemon) on EVERY turn and only descends when the ask actually needs a checkout. The caller must be able to WRITE in the channel — invoking an agent puts a message into the conversation — and the agent's own actor row must independently be able to reach it, so a person cannot summon an agent into a conversation it was never invited to. At most one run per (channel, requester) is in flight at a time; a second returns 409, which is NOT "the agent is busy" — somebody else's run in the same channel is expected and allowed.

Parameters

NameInTypeRequiredDescription
uuidpathstringyesChannel UUID

Request body: handler.InvokeAgentRequest

NameTypeRequiredDescription
handlestringnoHandle is the agent that was mentioned, with or without the '@'.
messageUuidstringnoMessageUUID is the message the mention appeared in.
needsWorkspacebooleannoNeedsWorkspace declares that the ask requires a checkout. False — the common case — routes to tier 0 and never touches a device.
repoKeystringnoRepoKey is the sha256 identity of the repository a workspace-bound turn needs. Never a path and never a URL.
requiredScopesdomain.DeviceScope[]noRequiredScopes are the device capabilities the turn needs.
topicUuidstringnoTopicUUID optionally tags the reply with the tab the question was asked under.

Responses

  • 201 Created · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope