Skip to main content
GET
Get agent by ID

Authorizations

Authorization
string
header
required

Supabase JWT token in Authorization: Bearer header

Path Parameters

agent_id
string
required

Agent identifier (e.g. smolt-abc123)

Response

Agent details. Members of the agent's org (any role) get the full record with caller: "org_member"; everyone else, signed in or not, gets a fixed public projection (id, name, claimed, status, avatar_url, created_at) with caller: "authenticated" or "anonymous". The correction-history lists serve non-members a redacted view; the other /agents/{agent_id}/… reads are org-member only unless their own description says otherwise.

An agent. GET /v1/agents/{id} returns one of TWO projections by authorization: an ORGANIZATION-MEMBER (owner) caller receives the full agent row (all fields below); a NON-OWNER receives a reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url). additionalProperties is left open because the owner row is the full DB row and grows as agent-settings columns are added (ADR-053 / proof / DDR); over-constraining it would 500 the endpoint on the next migration under /v1 response enforcement.

id
string
claimed
boolean

Public projection only: whether the agent has been claimed by a user.

avatar_url
string | null
claimed_by
string | null

Owner projection: user id that claimed the agent.

created_by
string | null

Owner projection: user id that created the agent (provenance).

org_id
string | null

Owner projection: the agent's org binding (ADR-062 authz boundary).

agent_proof_hash
string | null

Owner projection: captured hash_proof of the bound key (mig 263).

agent_proof_captured_at
string<date-time> | null
deleted_at
string<date-time> | null

Owner projection: soft-delete timestamp (null when live).

agent_hash
string

First 16 hex chars of SHA256(apiKey + '|' + agentName) for named agents, or SHA256(apiKey) for unnamed singleton agents. The gateway computes the same value on each request and uses it as the lookup key. See Agent Identity.

Example:

"a1b2c3d4e5f6a7b8"

user_id
string | null
email
string | null
claimed_at
string<date-time> | null
last_seen
string<date-time> | null
name
string | null

Agent name (2-32 chars, alphanumeric + hyphens). Present on all list and get responses.

containment_status
enum<string> | null

Containment state of the agent (ADR-053).

Available options:
active,
paused,
killed
key_prefix
string | null

First 8 chars of the bound API key hash — useful for key-rotation debugging.

status
enum<string>
Available options:
active,
offline
caller
enum<string>

Self-describing caller context for THIS response. org_member callers receive the full owner record (all fields here); anonymous/authenticated (non-member) callers receive the reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url, caller). The differing field set is GOVERNED by this value — read it instead of inferring why a field is absent.

Available options:
anonymous,
authenticated,
org_member
public
boolean

Identity-record visibility axis — whether the agent's IDENTITY RECORD is publicly discoverable. This is DISTINCT from reputation visibility: every registered agent's reputation is public by accountability standard (see ReputationScore.visibility). public here governs only the identity record, never the Trust Rating.

aip_enforcement_mode
enum<string> | null
Available options:
observe,
enforce,
nudge
billing_account_id
string | null
created_at
string<date-time>
groups
object[]

Active groups this agent belongs to, name-ordered; [] when none. Present on org-fleet rows (GET /v1/orgs/{org_id}/agents). Archived groups are excluded.