Skip to main content
GET
List agents owned by the caller.

Authorizations

Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Query Parameters

instance_id
string

Filter agents by instance ID.

Maximum string length: 128
instanceId
string

CamelCase alias for instance_id.

Maximum string length: 128
status
string

Filter agents by runtime/directory status, for example active.

limit
integer<int32>
default:20
offset
integer<int32>
default:0

Response

Paginated list of agents.

success
boolean
required
data
object[]
required
total
integer<int64>
required
projection
object

Accepted runtime-directory projection fence for the requested instance. Present only for an owned, instance-scoped list after a runtime projection has been accepted.