OpenAPI Specification
openapi: 3.0.1
info:
title: Elementum Access Token Agents API
description: Manage access tokens using OAuth 2.0 standards
contact:
email: apiteam@elementum.io
version: 0.0.1
servers:
- url: /v1
tags:
- name: Agents
description: Manage AI agents
paths:
/apps/{alias}/agents:
get:
tags:
- Agents
summary: List agents under an app
operationId: listAgents
parameters:
- $ref: '#/components/parameters/alias'
- $ref: '#/components/parameters/first'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/last'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/filter'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/AgentPagedList'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
security:
- ClientCredentials: []
x-codegen-request-body-name: body
post:
tags:
- Agents
summary: Create an agent under an app
operationId: createAgent
parameters:
- $ref: '#/components/parameters/alias'
requestBody:
description: Agent creation request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentBundleCreateRequest'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/PassthroughObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
security:
- ClientCredentials: []
x-codegen-request-body-name: body
/apps/{alias}/agents/{id}:
put:
tags:
- Agents
summary: Update an agent by ID
operationId: updateAgent
parameters:
- $ref: '#/components/parameters/alias'
- $ref: '#/components/parameters/passthroughId'
requestBody:
description: Agent update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentBundleUpdateRequest'
required: true
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/PassthroughObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
security:
- ClientCredentials: []
x-codegen-request-body-name: body
components:
parameters:
last:
name: last
in: query
description: The number of elements to retrieve before the 'before' cursor location
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
first:
name: first
in: query
description: The number of elements to retrieve after the 'after' cursor location
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 100
filter:
name: filter
in: query
description: An RSQL filter string.
required: false
schema:
type: string
format: string
examples:
In:
summary: In
description: In the provided list
value: Number=in=1:2:3:4:5
Between:
summary: Between
description: Between two values
value: Number=bt=1:10
Equals:
summary: Equals
description: Equals
value: Status==Open
LikeIgnoreCase:
summary: LikeIgnoreCase
description: Contains value, case insensitive
value: Title=lki=Incidents
And:
summary: And
description: The and ';' operator
value: Created At!=null;Created At=ge=2021-01-01T07:58:30.000Z
NotLike:
summary: NotLike
description: Doesn't contains value
value: Title!lk=Incidents
-- select --:
value: ''
Or:
summary: Or
description: The or ',' operator
value: Created At!=null,Created At=ge=2021-01-01T07:58:30.00Z
NotLikeIgnoreCase:
summary: NotLikeIgnoreCase
description: Doesn't contains value, case insensitive
value: Title!lki=Incidents
GreaterOrEqualTo:
summary: GreaterOrEqualTo
description: Greater than inclusive
value: Created At=ge=2021-01-01T07:58:30.000Z
NotBetween:
summary: NotBetween
description: Not Between two values
value: Number!bt=1:10
NotIn:
summary: NotIn
description: Not in the provided list
value: Number!in=1:2:3:4:5
LessThan:
summary: LessThan
description: Less than exclusive
value: Created At=lt=2022-03-15T07:58:30.000Z
Like:
summary: Like
description: Contains value
value: Title=lk=Incidents
LessOrEqualTo:
summary: LessOrEqualTo
description: Less than inclusive
value: Created At=le=2021-01-01T07:58:30.000Z
NotEquals:
summary: NotEquals
description: Not Equals
value: Created At!=null
GreaterThan:
summary: GreaterThan
description: Greater than exclusive
value: Created At=gt=2022-03-15T07:58:30.000Z
passthroughId:
name: id
in: path
description: The resource ID
required: true
schema:
type: string
format: string
alias:
name: alias
in: path
description: The app's namespace or its UUID
required: true
schema:
type: string
format: string
after:
name: after
in: query
description: The starting cursor to begin searching, defaults to the beginning of the list
required: false
schema:
type: string
before:
name: before
in: query
description: The starting cursor to begin searching, defaults to the end of the list
required: false
schema:
type: string
schemas:
PagingState:
type: object
properties:
has_previous_page:
type: boolean
start_cursor:
type: string
end_cursor:
type: string
has_next_page:
type: boolean
PassthroughObject:
type: object
additionalProperties: true
description: Free-form JSON object forwarded to/from the downstream service.
AgentBundleCreateRequest:
required:
- agent
type: object
properties:
tools:
type: array
description: Optional tools to attach to the new agent
items:
type: object
additionalProperties: true
a2aSkills:
type: array
description: Optional A2A skills to attach to the new agent
items:
type: object
additionalProperties: true
agent:
$ref: '#/components/schemas/AgentCreateInput'
description: Body for POST /v1/apps/{alias}/agents.
AgentBundleUpdateRequest:
required:
- agent
type: object
properties:
tools:
type: array
description: Optional tool list. If present, the agent's existing tools are replaced with this list.
items:
type: object
additionalProperties: true
a2aSkills:
type: array
description: Optional A2A skill list. If present, the agent's existing A2A skills are replaced with this list.
items:
type: object
additionalProperties: true
agent:
$ref: '#/components/schemas/AgentUpdateInput'
description: Body for PUT /v1/apps/{alias}/agents/{id}.
AgentUpdateInput:
type: object
properties:
elementum:
$ref: '#/components/schemas/AgentSubtypeUpdateInput'
description: Discriminator wrapper. Exactly one subtype field must be populated.
AgentPagedList:
type: object
properties:
paging:
$ref: '#/components/schemas/PagingState'
total:
type: integer
format: int32
items:
type: array
items:
$ref: '#/components/schemas/Agent'
AgentSubtypeCreateInput:
type: object
properties:
avatarAttachmentId:
type: string
description: Attachment ID for the agent's avatar image
format: uuid
maxLength:
type: integer
description: Maximum tokens the model may return per turn
format: int32
firstMessage:
type: string
description: Opening message the agent posts when a conversation starts
reasoningEffort:
type: string
description: How much hidden reasoning the model is allowed before answering
enum:
- MINIMAL
- LOW
- MEDIUM
- HIGH
name:
type: string
description: The agent's display name
description:
type: string
description: Short summary shown to users picking an agent
aiProviderConnectorId:
type: string
description: ID of the AI provider connector the agent uses
format: uuid
temperature:
type: number
description: Model sampling temperature; typical range 0.0–2.0
instructions:
type: string
description: System prompt steering the agent's behavior
additionalProperties: true
description: Agent creation input. Less common fields (voiceConfig, agentAuthentication, runAs, startingActions, skillAccessConfig, systemToolsConfig, a2aStreaming, a2aRecordConfig, conversationIdleTimeout) are accepted and forwarded as-is.
AgentCreateInput:
type: object
properties:
elementum:
$ref: '#/components/schemas/AgentSubtypeCreateInput'
description: Discriminator wrapper. Exactly one subtype field must be populated.
AgentSubtypeUpdateInput:
type: object
properties:
avatarAttachmentId:
type: string
description: Attachment ID for the agent's avatar image
format: uuid
maxLength:
type: integer
description: Maximum tokens the model may return per turn
format: int32
firstMessage:
type: string
description: Opening message the agent posts when a conversation starts
reasoningEffort:
type: string
description: How much hidden reasoning the model is allowed before answering
enum:
- MINIMAL
- LOW
- MEDIUM
- HIGH
name:
type: string
description: The agent's display name
description:
type: string
description: Short summary shown to users picking an agent
aiProviderConnectorId:
type: string
description: ID of the AI provider connector the agent uses
format: uuid
temperature:
type: number
description: Model sampling temperature; typical range 0.0–2.0
instructions:
type: string
description: System prompt steering the agent's behavior
additionalProperties: true
description: Agent update input. Only fields you wish to change need to be included; omitted fields keep their current value. Less common fields (voiceConfig, agentAuthentication, runAs, startingActions, skillAccessConfig, systemToolsConfig, a2aStreaming, a2aRecordConfig, conversationIdleTimeout) are accepted and forwarded as-is.
Agent:
type: object
properties:
type:
type: string
description: The agent variant (AgentElementum, AgentSystem, AgentBrowserUse, AgentSnowflake, AgentBedrock, AgentExternal)
id:
type: string
description: The agent ID
format: uuid
maxLength:
type: integer
description: Maximum tokens the model may return per turn
format: int32
reasoningEffort:
type: string
description: How much hidden reasoning the model is allowed before answering
enum:
- MINIMAL
- LOW
- MEDIUM
- HIGH
description:
type: string
description: Short summary shown to users picking an agent
name:
type: string
description: The agent's display name
temperature:
type: number
description: Model sampling temperature; typical range 0.0–2.0
description: An agent returned by the agents list endpoint (summary projection).
responses:
'401':
description: Unauthorized
'422':
description: Unprocessable Entity
'429':
description: Too Many Requests
'403':
description: Forbidden
'500':
description: Internal Server Error
'404':
description: Not Found
'400':
description: Bad Request
securitySchemes:
ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: /oauth/token
externalDocs:
description: Find out more about Elementum
url: https://www.elementum.com/