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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Consent request UUID |
Request body: handler.DecideConsentRequest
| Name | Type | Required | Description |
|---|---|---|---|
| status | object | no | Status 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
| Name | Type | Required | Description |
|---|---|---|---|
| label | string | no | |
| maxConcurrent | integer | no | MaxConcurrent is bounded to 1..16 by ck_agent_devices_max_concurrent. |
| platform | string | no | |
| scopes | domain.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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Device 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Run 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Run 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Run UUID |
| after | query | integer | no | Return events after this seq |
| limit | query | integer | no | Page 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
| Name | Type | Required | Description |
|---|---|---|---|
| avatarUrl | string | no | AvatarURL 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. |
| handle | string | no | Handle is what people type after '@'. Lowercased and validated against ck_agents_handle_shape; a leading '@' is accepted and stripped. |
| instructions | string | no | Instructions is the persona prompt, at most 16KB. |
| invocationScope | string | no | |
| name | string | no | Name is the display name, 1-80 characters. |
| policyProfile | string | no | |
| projectScope | string | no | ProjectScope, 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Agent UUID |
Request body: handler.UpdateAgentRequest
| Name | Type | Required | Description |
|---|---|---|---|
| avatarUrl | string | no | |
| enabled | boolean | no | |
| instructions | string | no | |
| invocationScope | string | no | |
| name | string | no | |
| policyProfile | string | no | |
| projectScope | string | no |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uuid | path | string | yes | Channel UUID |
Request body: handler.InvokeAgentRequest
| Name | Type | Required | Description |
|---|---|---|---|
| handle | string | no | Handle is the agent that was mentioned, with or without the '@'. |
| messageUuid | string | no | MessageUUID is the message the mention appeared in. |
| needsWorkspace | boolean | no | NeedsWorkspace declares that the ask requires a checkout. False — the common case — routes to tier 0 and never touches a device. |
| repoKey | string | no | RepoKey is the sha256 identity of the repository a workspace-bound turn needs. Never a path and never a URL. |
| requiredScopes | domain.DeviceScope[] | no | RequiredScopes are the device capabilities the turn needs. |
| topicUuid | string | no | TopicUUID 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