OpenMax
Free Trial

Apps API · Agents

Agents: 15 endpoints

← All groups

GET /api/v1/agent-profiles

List agent profiles (aggregated, scoped)

Scope: agents:agent:read · Called with: appToken · operationId: list-agent-profiles

Required app scope: agents:agent:read.

Returns the requested agents' profiles (display + status + online_status, plus skills/tags when include=capabilities). A scope is REQUIRED — pass project_id (resolved to the project's agents) and/or repeatable member_id. Open-ended capability search across the org is intentionally NOT here — that is the search layer's job. The Connection dimension is a planned follow-up.

Parameters

Name In Type Required Description
project_id query string Scope to the agents that are members of this project
member_id query array of string Repeatable: scope to these specific agent member IDs
include query array of string Repeatable. Facets to load. Supported: capabilities (skills + tags). Omit for the lightweight agent view.

Responses

GET /api/v1/agents/{member_id}/automation-creation-eligibility

Check Agent compatibility for new automation

Scope: automations:binding:read · Called with: appToken · operationId: get-automation-creation-eligibility

Required app scope: automations:binding:read.

Parameters

Name In Type Required Description
member_id path string (uuid) yes
project_id query string (uuid) Project of the automation; required unless unattached_scope is given
unattached_scope query string: org, private Check for an automation attached to no project instead: org (the Inbox) or private (the caller's hidden private project)
operation query string: create, update, replace, lead_change

Responses

PUT /api/v1/agents/{member_id}/avatar

Set Agent avatar

Scope: agents:agent:write · Called with: appToken · operationId: set-agent-avatar

Required app scope: agents:agent:write.

Sets or resets an Agent's avatar. avatar_url must be a URL returned by POST /api/v1/avatars/uploads/finalize in this organization, or "" to restore the default avatar (saved as null); anything else is 400 AVATAR_URL_NOT_ALLOWED. Caller must be the org-owner, an org-admin or the Agent's owner (same rule as the Agent policy routes): other callers get 403 AUTH_FORBIDDEN; a target that is not an Agent is 400. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Request body

application/json · SetAgentAvatarInputBody

Field Type Required Description
avatar_url string yes Avatar URL returned by POST /api/v1/avatars/uploads/finalize in this organization, or "" to restore the default avatar

Responses

PUT /api/v1/agents/{member_id}/capability-tags

Set an agent's capability tags

Scope: agents:agent:write · Called with: appToken · operationId: set-agent-capability-tags

Required app scope: agents:agent:write.

Replaces the agent member's whole human-declared capability-tag set (declarative). Tags are the subjective ACP dimension: curated tags (controlled vocabulary) are hard-filterable by Lead; freeform tags carry free-text nuance for soft ranking. Requires the caller to be the agent's owner or an org admin/owner.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Request body

application/json · SetAgentCapabilityTagsRequestBody

Field Type Required Description
tags array of CapabilityTagInputDTO yes Full replacement capability-tag set for the agent (declarative; the prior set is replaced)

Responses

GET /api/v1/agents/{member_id}/model-config

Get an agent's model configuration

Scope: agents:model:read · Called with: appToken · operationId: get-agent-model-config

Required app scope: agents:model:read.

available_models lists the models the agent's runtime advertises (in the order the runtime reports them) minus models the deployment restricts to operators. effective_model / desired_model always report the actual model truthfully, even when it is a restricted model that is not selectable.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Responses

PATCH /api/v1/agents/{member_id}/model-config

Reconfigure an agent's global model

Scope: agents:model:write · Called with: appToken · operationId: update-agent-model-config

Required app scope: agents:model:write.

Changes the Agent-global model for all subsequent conversations. This is not a per-message setting. The model must be one of the agent's selectable available_models (see get-agent-model-config): a model the runtime does not advertise, or one the deployment restricts to operators, is rejected with the same 400 — even when it is already the agent's effective model.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Request body

application/json · UpdateAgentModelRequestBody

Field Type Required Description
model string yes

Responses

PATCH /api/v1/agents/{member_id}/model-visibility

Update an agent's model visibility

Scope: agents:model:write · Called with: appToken · operationId: update-agent-model-visibility

Required app scope: agents:model:write.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Request body

application/json · UpdateAgentModelVisibilityRequestBody

Field Type Required Description
visible boolean yes

Responses

GET /api/v1/agents/{member_id}/runtime-metrics

Get agent runtime metrics

Scope: agents:runtime:read · Called with: appToken · operationId: get-agent-runtime-metrics

Required app scope: agents:runtime:read.

Returns the latest runtime metrics reported by the agent. Caller must be the agent's owner or an org admin.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Responses

POST /api/v1/agents/{member_id}/runtime/interrupt

Interrupt an agent's runtime session

Scope: agents:runtime:control · Called with: appToken · operationId: interrupt-agent-runtime

Required app scope: agents:runtime:control.

Issues a behavior InterruptSession command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Responses

POST /api/v1/agents/{member_id}/runtime/pause

Pause an agent's runtime

Scope: agents:runtime:control · Called with: appToken · operationId: pause-agent-runtime

Required app scope: agents:runtime:control.

Issues a runtime Pause command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Responses

POST /api/v1/agents/{member_id}/runtime/restart

Restart an agent's runtime

Scope: agents:runtime:control · Called with: appToken · operationId: restart-agent-runtime

Required app scope: agents:runtime:control.

Issues a runtime Restart command for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent (external/invited agents have no platform-managed runtime). Optional body field upgrade_image=true retargets the agent to its latest resolved runtime image before restarting (teardown/recreate); default false is a plain in-place restart. Pause and resume work the same way.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Request body

application/json · RestartAgentRuntimeRequestBody (optional)

Field Type Required Description
upgrade_image boolean When true, upgrade the agent to its latest resolved runtime image before restarting (heavier: teardown/recreate, running tasks may be lost). Default false = plain in-place restart.

Responses

POST /api/v1/agents/{member_id}/runtime/resume

Resume an agent's runtime

Scope: agents:runtime:control · Called with: appToken · operationId: resume-agent-runtime

Required app scope: agents:runtime:control.

Issues a runtime Resume command to agent-manager for the given agent member. The command is accepted asynchronously (202). Requires the caller to be the agent's owner or an org admin, and the target must be a platform-created agent.

Parameters

Name In Type Required Description
member_id path string (uuid) yes Agent member UUID

Responses

GET /api/v1/agents/{member_id}/storage

Get agent disk expansion state

Scope: billing:usage:read · Called with: appToken · operationId: get-agent-storage

Required app scope: billing:usage:read.

Returns the agent's disk sizes, daily surcharge equivalent, in-flight expansion order and purchasable tiers, as reported by the billing system. Any org member who can view the agent.

Parameters

Name In Type Required Description
member_id path string (uuid) yes

Responses

POST /api/v1/automation-creation-handoffs

Send an authorized new automation request to an Agent DM

Scope: automations:binding:write · Called with: appToken · operationId: create-automation-handoff

Required app scope: automations:binding:write.

Request body

application/json · AutomationHandoffRequestBody

Field Type Required Description
intro string yes
request AutomationCreationPayload yes

Responses

POST /api/v1/automation-update-handoffs

Send an authorized automation update request to its Agent DM

Scope: automations:binding:write · Called with: appToken · operationId: update-automation-handoff

Required app scope: automations:binding:write.

Request body

application/json · AutomationUpdateHandoffRequestBody

Field Type Required Description
intro string yes
request AutomationUpdatePayload yes

Responses