Solace Agent Mesh Management API (2.0.0)

Download OpenAPI specification:

REST API for managing agents, connectors, entrypoints, models, and deployments in Solace Agent Mesh.

API Keys

Manage the API keys that let a pipeline call the management API as a system user.

Get a list of API keys

Returns one page of API keys, optionally only those of one system user or one status.

Token Permissions: the universal grant *:*:*. API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
userId
string
Example: userId=0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f

Limits the list to the keys of the system user with this UUID. Leave it out to list the keys of every owner. An empty value fails with 400.

status
string
Example: status=active

Limits the list to active or expired keys. Leave it out to list both. An empty value fails with 400.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(label|prefix|createdTime|updatedTime|expire...
Example: sort=label:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: label, prefix, createdTime, updatedTime, expiresTime, lastUsedTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an API key

Issues a key for a custom system user. Only this response shows the key's secret. If the owner already holds 10 active keys, the request fails with 409. On a deployment whose authorization mode is not default_rbac, it fails with 403 and a message naming that mode. If authorization state is unavailable, it fails with 503.

Token Permissions: the universal grant *:*:*, held by a person who signed in. API keys are refused.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

expiresTime
string or null <date-time>

When the key stops working, which must be in the future. Leave it out or send null when neverExpires is true.

label
required
string

The key's display name, 1 to 255 characters without control characters.

neverExpires
boolean

Issues a key that does not expire. Leave it out or send false when expiresTime is set.

scopes
required
Array of strings

The scopes the key can use. The owner must hold every one, and the key can never be widened later.

userId
required
string

The UUID of the custom system user that owns the key.

Responses

Request samples

Content type
application/json
{
  • "expiresTime": "2027-01-02T03:04:05.678Z",
  • "label": "deploy-pipeline",
  • "neverExpires": false,
  • "scopes": [
    ],
  • "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an API key

Revokes a key immediately. A task the key already submitted keeps running.

Token Permissions: the universal grant *:*:*, held by a person who signed in. API keys are refused.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an API key

Returns one API key without its secret.

Token Permissions: the universal grant *:*:*. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace an API key

Renames a key. The label is the only field that can be replaced. The scopes and expiry of a key are fixed when it is issued.

Token Permissions: the universal grant *:*:*, held by a person who signed in. API keys are refused.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a

The UUID of the key to rename.

Request Body schema: application/json
required

The request body.

label
required
string

The key's new display name, 1 to 255 characters without control characters.

Responses

Request samples

Content type
application/json
{
  • "label": "deploy-pipeline"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Access Control

Manage the roles, grants, claim mappings, default roles, and system users that decide what each caller can do, and read the scope catalog.

Get a list of claim mappings

Returns one page of claim mappings: those defined in the configuration first, then the custom ones.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
origin
string
Example: origin=custom

Limits the list to one origin: custom or yaml. Leave it out to list every mapping.

oidcProvider
string
Example: oidcProvider=okta

Limits the list to mappings of one identity provider.

roleId
string
Example: roleId=0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40

Limits the list to mappings that grant the role with this id. A value that is not a UUID fails with 400.

search
string
Example: search=platform

Limits the list to mappings whose name or claim value contains it, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|oidcProvider|claimValue|createdTime|up...
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, oidcProvider, claimValue, createdTime, updatedTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a claim mapping

Creates a claim mapping that grants roles to identities whose token carries the claim value.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

claimKey
string

The token claim the mapping reads. Leave it out to use the deployment's configured claim key.

claimValue
required
string

The claim value that triggers the mapping. Up to 256 characters. If another mapping uses this provider and value, or the configuration maps them to one of these roles, the request fails with 409.

name
required
string

The mapping's name.

oidcProvider
string

The identity provider whose tokens the mapping matches. Leave it out to use the deployment's configured provider.

roleIds
required
Array of strings

The ids of the custom or built-in roles to grant. At least one. A role defined in the configuration cannot be granted by a mapping created through the API.

Responses

Request samples

Content type
application/json
{
  • "claimKey": "groups",
  • "claimValue": "platform-engineers",
  • "name": "Platform engineers",
  • "oidcProvider": "okta",
  • "roleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a claim mapping

Deletes a custom claim mapping. If the mapping is defined in the configuration, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a claim mapping

Returns one claim mapping, whatever its origin.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace a claim mapping

Replaces a custom claim mapping with the fields sent. If the mapping is defined in the configuration, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the claim mapping to replace.

Request Body schema: application/json
required

The request body.

claimKey
string

The token claim the mapping reads. Leave it out to use the deployment's configured claim key, which replaces the mapping's current one.

claimValue
required
string

The claim value that triggers the mapping. Up to 256 characters. If another mapping uses this provider and value, or the configuration maps them to one of these roles, the request fails with 409.

name
required
string

The mapping's new name.

oidcProvider
string

The identity provider whose tokens the mapping matches. Leave it out to use the deployment's configured provider, which replaces the mapping's current one.

roleIds
required
Array of strings

The ids of the roles the mapping grants, replacing the current ones. At least one. A role defined in the configuration cannot be granted by a mapping created through the API.

Responses

Request samples

Content type
application/json
{
  • "claimKey": "groups",
  • "claimValue": "platform-engineers",
  • "name": "Platform engineers",
  • "oidcProvider": "okta",
  • "roleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the default roles

Returns the roles given to a user who holds no other role: the override set through the API, or else the defaults defined in the configuration.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace the default roles

Sets the default roles, overriding those defined in the configuration. An empty set clears the override.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

roleIds
Array of strings

The ids of the custom or built-in roles that a user with no other role holds. Send an empty list or leave it out to clear the override, so the configuration's defaults apply again.

Responses

Request samples

Content type
application/json
{
  • "roleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of grants

Returns one page of grants: those defined in the configuration first, then the custom ones. With expand=user, each concrete grant also carries how its user signs in now, so a client can find a grant recorded under a subject that no longer names its user.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
origin
string
Example: origin=custom

Limits the list to one origin: custom or yaml. Leave it out to list every grant.

state
string
Example: state=pending

Limits the list to concrete or pending grants. A grant defined in the configuration has no state, so it is left out.

roleId
string
Example: roleId=0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40

Limits the list to the grants of one role. A value that is not a UUID fails with 400.

expand
string
Example: expand=user

Takes one value, user, which fills each concrete grant's user with how that user signs in now. Any other value fails with 422.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(roleId|state|createdTime|updatedTime)(:(asc...
Example: sort=roleId:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: roleId, state, createdTime, updatedTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a grant

Gives a role to an identity. If the grant already exists, is defined in the configuration, or is for a built-in system user, the request fails with 409 and the existing grant is left unchanged.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

roleId
required
string

The id of the custom or built-in role to give. A role defined in the configuration cannot be granted through the API.

required
object

The identity to give the role to. If no user matches it yet, the grant is pending.

Responses

Request samples

Content type
application/json
{
  • "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
  • "subject": {}
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a grant

Deletes a custom grant. If the grant is defined in the configuration, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a grant

Returns one grant, whatever its origin.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a grant

Records a concrete grant under a different subject, such as an email in place of a legacy subject, keeping its id, user and role. The subject must name the grant's user, or the answer is 422 on subject; a null subject is also 422, and a subject left out changes nothing. A roleId or userId in the body is 422, because neither can change. A grant defined in the configuration, a pending grant, the grant of a system user, a subject that is a built-in system user, and a subject that the configuration already gives the role answer 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The grant's UUID.

Request Body schema: application/json
required

The request body.

roleId
string

Fixed when the grant is created. If the body includes it, the request fails with 422.

object

The subject to record the grant under, with the rules it has on create. It must name the grant's user, so the user and the role never change. Leave it out to keep it. Null fails with 422, because a grant needs a subject.

userId
string

Fixed when the grant is created. If the body includes it, the request fails with 422.

Responses

Request samples

Content type
application/json
{
  • "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
  • "subject": {},
  • "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of roles

Returns one page of roles: those defined in the configuration first, then the custom and built-in roles.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
origin
string
Example: origin=custom

Limits the list to one origin: custom, yaml, or builtin. Leave it out to list every role.

search
string
Example: search=support

Limits the list to roles whose name or description contains it, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|createdTime|updatedTime)(:(asc|desc))?...
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, createdTime, updatedTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a role

Creates a custom role.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

description
string

Says what the role is for.

inherits
Array of strings

The ids of the custom or built-in roles whose scopes this role also grants. A role defined in the configuration cannot be inherited, and the inheritance must not form a cycle.

name
required
string

The role's name: not blank, with no control characters. It must not be the name of another custom or built-in role, or of a role defined in the configuration.

scopes
Array of strings

The scopes the role grants directly, each in category:resource:verb form.

Responses

Request samples

Content type
application/json
{
  • "description": "Runs and monitors the support agents.",
  • "inherits": [
    ],
  • "name": "Support agent operator",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a role

Deletes a custom role and every grant of it, and removes it from claim mappings and inheriting roles. If the role is defined in the configuration, shipped by Solace, or a default role, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a role

Returns one role, whatever its origin.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace a role

Replaces a custom role with the fields sent. A field left out is cleared. If the role is defined in the configuration or shipped by Solace, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the role to replace.

Request Body schema: application/json
required

The request body.

description
string

Replaces the description. Leave it out to clear it.

inherits
Array of strings

Replaces the ids of the roles whose scopes this role also grants. Leave it out to clear them. A role defined in the configuration cannot be inherited, and the inheritance must not form a cycle.

name
required
string

The role's new name: not blank, with no control characters. No other role can already have it, whatever its origin. A role the configuration refers to by name cannot be renamed.

scopes
Array of strings

Replaces the scopes the role grants directly. Leave it out to clear them.

Responses

Request samples

Content type
application/json
{
  • "description": "Runs and monitors the support agents.",
  • "inherits": [
    ],
  • "name": "Support agent operator",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of system users

Returns one page of the system users an entrypoint can run as, built-in ones included.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=webhook

Limits the list to system users whose name or display name contains it, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name)(:(asc|desc))?$
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a system user

Creates a system user holding the roles given. If the name is already taken, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

displayName
string

A label for people to read.

name
required
string

The system user's name. It must not be taken by another system user or reserved for a built-in one, such as default.

roleIds
required
Array of strings

The ids of the custom or built-in roles to grant. At least one. A role defined in the configuration cannot be granted through the API.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Support webhook",
  • "name": "support-webhook",
  • "roleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a system user

Deletes a custom system user together with its grants, API keys, and budget assignments. If the system user is built in, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a system user

Returns one system user, whatever its origin.

Token Permissions: [ rbac:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace a system user

Replaces the roles and display name of a custom system user. A display name left out is cleared. If the system user is built in, the request fails with 409.

Token Permissions: the universal grant *:*:*. While Agent Mesh uses its built-in identity provider, the request fails with 403. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the system user to replace.

Request Body schema: application/json
required

The request body.

displayName
string

Replaces the display name. Leave it out to clear it.

roleIds
required
Array of strings

Replaces the roles the system user holds, so a role left out is revoked. At least one. Each must be a custom or built-in role. A role defined in the configuration cannot be granted through the API.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Support webhook",
  • "roleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Server Capabilities

Read what this server lets callers do.

Get what this server lets callers do

Returns what the server's configuration allows, whatever the caller's own permissions. A pipeline can use it to learn up front whether access-control writes and decision-model creates are honored.

Token Permissions: any signed-in caller. No scope is required. API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Agent Deployments

Deploy and undeploy agents, and read the outcome of each deployment.

Get a list of agent deployments

Returns one page of agent and remote agent deployments, failed ones included, optionally only those of one agent.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
agentId
string
Example: agentId=0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f

Limits the list to the deployments of one agent or remote agent, by UUID. Leave it out to list every deployment. If it is not a UUID, the request fails with 400.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Initiate an agent deployment

Deploys, updates, or undeploys an agent or remote agent and returns the deployment record. Send deploymentId to roll an agent back to the configuration an earlier deployment ran with. If the deploy runs and fails, the request fails with 502. If Agent Mesh refuses the settings while deploying, the request fails with 422. Both keep the deployment record, and the Location header links to it. If the server cannot deploy agents, the request fails with 503.

Token Permissions: [ agent_builder:*:deploy ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

action
required
string

What to do: deploy, update, or undeploy.

agentId
required
string

The UUID of the agent or remote agent to deploy.

deploymentId
string

The UUID of an earlier deployment to roll the agent back to. The deploy or update then sends that deployment's configuration. It must be a successful deploy or update of the same agent. Leave it out for undeploy. Remote agents cannot be rolled back.

skipIfCurrent
boolean

When true, returns the latest deployment instead of restarting an agent that already runs the configuration this deploy would send. Defaults to false. Must be false for undeploy and with deploymentId.

Responses

Request samples

Content type
application/json
{
  • "action": "deploy",
  • "agentId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
  • "deploymentId": "0190f5e5-0c1d-7e2f-9a3b-4c5d6e7f8091",
  • "skipIfCurrent": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an agent deployment

Returns one deployment of an agent or remote agent, with why it failed when it did.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Agents

Manage the agents that Agent Mesh builds.

Get a list of agents

Returns one page of agents, optionally only those that use one connector. Secret values are redacted.

Token Permissions: [ agent_builder:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
connectorId
string
Example: connectorId=0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e

Limits the list to agents that use this connector, by UUID. Leave it out to list every agent. If it is not a UUID, the request fails with 400.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an agent

Creates an agent without deploying it. Deploy it with POST /agentDeployments. Unknown additionalConfigurations keys are kept and listed in warnings.

Token Permissions: [ agent_builder:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
header Parameters
X-Sam-Client-Surface
string
Example: ui

The X-Sam-Client-Surface header: ui or cli names the first-party client making the request, and any other value, or no header, counts as api. Used only for usage statistics.

Request Body schema: application/json
required

The request body.

object

Holds extra agent settings merged into the deployed configuration. A JSON object of up to 64 KiB, nested up to 8 levels. If a key is one the platform sets itself or repeats another agent field, the request fails with 422. An unrecognized key is kept and listed in warnings.

agentType
string

The kind of agent to create. Only standard is accepted. Defaults to standard.

connectorIds
Array of strings

The UUIDs of the connectors whose tools the agent uses. Up to 5. If two connectors or toolsets have a tool with the same name, the request fails with 422.

description
required
string

Says what the agent does. 10 to 1,000 characters.

inputModes
Array of strings

Lists the content types the agent accepts. When it is empty, the agent card advertises text.

modelProvider
Array of strings

Names the model configuration to use, as an alias or ID, in its first entry. When it is empty, the agent uses the general model. If the model is not configured, the request fails with 422.

name
required
string

The agent's unique name. 3 to 255 characters. If the name is already in use, ignoring case and spaces, the request fails with 409.

outputModes
Array of strings

Lists the content types the agent produces. When it is empty, the agent card advertises text.

Array of objects (SkillConfig)

Sets the agent's own settings per skill. If a skill is missing from skillIds, the request fails with 422.

skillIds
Array of strings

Lists the UUIDs of the custom skills to attach. If an ID is unknown, the request fails with 422.

skillRefs
Array of strings

Names the built-in skills to attach. If a name starts with sam- and is not a known built-in skill, the request fails with 422.

Array of objects (AgentSkill)

Lists the abilities the agent advertises on its Agent-to-Agent (A2A) agent card. Up to 20.

systemPrompt
string

The agent's instructions to the model. Required for a standard agent. 1 to 32,000 characters by default. The server's configuration can change these limits.

Array of objects (ToolsetConfig)

Sets the agent's own settings per toolset. If a toolset is missing from toolsets or appears more than once, the request fails with 422.

object

Maps a toolset to the names of its tools the agent excludes.

toolsets
Array of strings

Lists the toolsets to use, each a built-in toolset ID or the name of a ready custom tool package. If a name is unknown, the request fails with 422.

Responses

Request samples

Content type
application/json
{
  • "additionalConfigurations": {
    },
  • "agentType": "standard",
  • "connectorIds": [
    ],
  • "description": "Answers customer questions about order status and delivery dates.",
  • "inputModes": [
    ],
  • "modelProvider": [
    ],
  • "name": "Order support agent",
  • "outputModes": [
    ],
  • "skillConfigs": [
    ],
  • "skillIds": [
    ],
  • "skillRefs": [
    ],
  • "skills": [
    ],
  • "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
  • "toolsetConfigs": [
    ],
  • "toolsetExcludedTools": {
    },
  • "toolsets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an agent

Undeploys the agent if it is deployed, then deletes it. If the undeploy fails, the agent is kept and the request fails with 502.

Token Permissions: [ agent_builder:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an agent

Returns one agent with its deployment and runtime status. Secret values are redacted.

Token Permissions: [ agent_builder:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace an agent

Replaces the agent with the fields sent. A field left out is cleared, except toolsetConfigs and skillConfigs, which are kept unless sent as an empty array. The agent type cannot change. A deployed agent runs the new settings after an update through POST /agentDeployments.

Token Permissions: [ agent_builder:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f

The UUID of the agent to replace. If the ID is unknown, the request fails with 404.

Request Body schema: application/json
required

The request body.

object

Holds extra agent settings merged into the deployed configuration. A JSON object of up to 64 KiB, nested up to 8 levels. If a key is one the platform sets itself or repeats another agent field, the request fails with 422. An unrecognized key is kept and listed in warnings.

connectorIds
Array of strings

The UUIDs of the connectors whose tools the agent uses. Up to 5. If two connectors or toolsets have a tool with the same name, the request fails with 422.

description
required
string

Says what the agent does. 10 to 1,000 characters.

inputModes
Array of strings

Lists the content types the agent accepts. When it is empty, the agent card advertises text.

modelProvider
Array of strings

Names the model configuration to use, as an alias or ID, in its first entry. When it is empty, the agent uses the general model. If the model is not configured, the request fails with 422.

name
required
string

The agent's new name. 3 to 255 characters.

outputModes
Array of strings

Lists the content types the agent produces. When it is empty, the agent card advertises text.

Array of objects or null (SkillConfig)

Sets the agent's own settings per skill. If a skill is missing from skillIds, the request fails with 422. Leave it out or send null to keep the stored settings of the skills that stay attached, and send [] to clear them.

skillIds
Array of strings

Lists the UUIDs of the custom skills to attach. If an ID is unknown, the request fails with 422.

skillRefs
Array of strings

Names the built-in skills to attach. If a name starts with sam- and is not a known built-in skill, the request fails with 422.

Array of objects (AgentSkill)

Lists the abilities the agent advertises on its Agent-to-Agent (A2A) agent card. Up to 20.

systemPrompt
string

The agent's instructions to the model. Required for a standard agent. 1 to 32,000 characters by default. The server's configuration can change these limits.

Array of objects or null (ToolsetConfig)

Sets the agent's own settings per toolset. If a toolset is missing from toolsets or appears more than once, the request fails with 422. Leave it out or send null to keep the stored settings, and send [] to clear them.

object

Maps a toolset to the names of its tools the agent excludes.

toolsets
Array of strings

Lists the toolsets to use, each a built-in toolset ID or the name of a ready custom tool package. If a name is unknown, the request fails with 422.

Responses

Request samples

Content type
application/json
{
  • "additionalConfigurations": {
    },
  • "connectorIds": [
    ],
  • "description": "Answers customer questions about order status and delivery dates.",
  • "inputModes": [
    ],
  • "modelProvider": [
    ],
  • "name": "Order support agent",
  • "outputModes": [
    ],
  • "skillConfigs": [
    ],
  • "skillIds": [
    ],
  • "skillRefs": [
    ],
  • "skills": [
    ],
  • "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
  • "toolsetConfigs": [
    ],
  • "toolsetExcludedTools": {
    },
  • "toolsets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate values against an agent's stored secrets

Returns, for each secret setting of the agent's toolsets and skills, whether saving the values sent would keep the stored secret. Secret values are never returned.

Token Permissions: [ agent_builder:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f

The UUID of the agent whose stored secrets are compared. If the ID is unknown, the request fails with 404.

Request Body schema: application/json
required

The request body.

required
object

Holds the toolset and skill settings to compare with the stored ones. Required.

Responses

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Connectors

Manage the connectors that give agents and workflows access to external systems.

Get a list of connectors

Returns one page of connectors, optionally only those of one kind. Secret settings are redacted.

Token Permissions: [ connector:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
connectorType
string
Example: connectorType=api

Limits the list to one connector type. Leave it out to list every type.

connectorSubtype
string
Example: connectorSubtype=openapi

Limits the list to one subtype. Leave it out to list every subtype.

name
string
Example: name=orders

Limits the list to connectors whose name contains this text, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|createdTime)(:(asc|desc))?$
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, createdTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a connector

Creates a connector. If another connector has the same name, ignoring case, the request fails with 409.

Token Permissions: [ connector:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

connectorSubtype
required
string

Narrows the kind, such as openapi for an api connector or postgres for a sql one. A declared type takes only its own declared subtypes. It cannot be changed later.

connectorType
required
string

The kind of system to reach: api, document_db, email, event_mesh, graph_db, knowledge_base, mcp, search, slack, or sql. A type that a plugin package registered at runtime is also accepted. Every setting of such a connector reads back as "". A type this deployment has turned off fails with 422. Cannot be changed later.

description
required
string

Says what the connector is for, 10 to 1,000 characters.

name
required
string

The connector's display name, 3 to 255 characters and unique ignoring case.

object

Holds the settings the subtype's schema defines. Leave it out to use the subtype's defaults.

Responses

Request samples

Content type
application/json
{
  • "connectorSubtype": "openapi",
  • "connectorType": "api",
  • "description": "The orders service used by the fulfilment agent",
  • "name": "Orders API",
  • "values": {}
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a connector

Deletes the connector and unbinds it from every agent and workflow, which then redeploy.

Token Permissions: [ connector:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a connector

Returns one connector with its agent registrations. Secret settings are redacted.

Token Permissions: [ connector:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a connector

Changes the fields sent and keeps the rest. Send a null description to clear it. The values object replaces all settings, but a secret left out, null, or "" keeps its stored value. The type and subtype cannot change. Bound agents and workflows redeploy.

Token Permissions: [ connector:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the connector to update.

Request Body schema: application/json
required

The request body.

connectorSubtype
string

Fixed when the connector is created. Including it fails with 422.

connectorType
string

Fixed when the connector is created. Including it fails with 422.

description
string or null

Says what the connector is for. Leave it out to keep it, or send null to clear it. An empty string fails with 422.

name
string

The display name. Leave it out to keep it. Null or an empty string fails with 422.

object

Replaces all of the connector's settings. A secret left out, sent as null, or sent as "" keeps its stored value. A hidden field, such as hil, is kept when left out or sent as null, and is removed only by sending {}. Leave values out to keep every setting. Null fails with 422.

Responses

Request samples

Content type
application/json
{
  • "connectorSubtype": "openapi",
  • "connectorType": "api",
  • "description": "The orders service used by the fulfilment agent",
  • "name": "Orders API",
  • "values": {}
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a connector's OpenAPI specification

Returns the stored OpenAPI specification as a file, not wrapped in a data envelope. If the connector has none, the request fails with 404.

Token Permissions: [ connector:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
"string"

Replace a connector's OpenAPI specification

Uploads an OpenAPI specification of up to 10 MiB, sent as multipart form data in a part named file, and points the connector's specification_url at it. Only api/openapi connectors accept one. Any other form part fails with 400.

Token Permissions: [ connector:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the connector whose specification is being replaced.

Request Body schema: multipart/form-data
required

The request body.

file
required
string <binary>

The specification file, sent as the multipart part named file.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate values against a connector's stored secrets

Returns, for each secret setting of the connector, whether saving the values sent would keep the stored secret. Secret values are never returned.

Token Permissions: [ connector:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210

The UUID of the connector whose stored secrets are compared.

Request Body schema: application/json
required

The request body.

required
object

Holds the settings to compare. Only secret settings are compared. The connector subtype sets the keys.

Responses

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Entrypoint Deployments

Deploy and undeploy entrypoints, and read the outcome of each deployment.

Get a list of entrypoint deployments

Returns one page of deployment records, newest first, optionally only those of one entrypoint.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
entrypointId
string
Example: entrypointId=0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

Limits the list to the deployments of the entrypoint with this UUID. Leave it out to list the deployments of every entrypoint.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Initiate an entrypoint deployment

Deploys, updates, or undeploys an entrypoint and returns the deployment record. If the deployment runs and fails, the request fails with 502. If it is refused while deploying, the request fails with 422. In both cases the Location header links the kept record. If it is refused before it starts, such as when settings are still to be filled in, the request fails with 422 and keeps no record. If the server has no event broker connection, the request fails with 503.

Token Permissions: [ entrypoint:*:deploy ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

action
required
string

The action to take: deploy, update, or undeploy.

entrypointId
required
string

The UUID of the entrypoint to act on.

Responses

Request samples

Content type
application/json
{
  • "action": "deploy",
  • "entrypointId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an entrypoint deployment

Returns one deployment record, including why it failed when it did.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Entrypoints

Manage the entrypoints that connect people and systems to Agent Mesh, such as Slack, Teams, webhooks, and WhatsApp.

Get a list of entrypoints

Returns one page of entrypoints, optionally only those of one entrypoint type. Secret values are redacted.

Token Permissions: [ entrypoint:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
entrypointType
string
Example: entrypointType=slack

Limits the list to one entrypoint type. Leave it out to list every type.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an entrypoint

Creates an entrypoint without deploying it. Deploy it with POST /entrypointDeployments.

Token Permissions: [ entrypoint:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

description
required
string

Says what the entrypoint is for: 10 to 1,000 characters with no control characters other than tabs and line breaks.

entrypointType
required
string

The kind of entrypoint, such as slack or webhook. It cannot be changed later.

name
required
string

The display name: 3 to 255 characters with no control characters, unique among entrypoints.

publicUrl
string

An https URL to record as the entrypoint's public address. Leave it out for none.

slug
string

A readable identifier that stands in for the id in the entrypoint's URLs. 3 to 63 lowercase letters, digits, and hyphens, starting with a letter and ending with a letter or digit. Must be unique and not oauth, api, well-known, gw, or health. Leave it out to use the id. It cannot be changed later.

object

Holds the entrypoint's settings. Leave it out to store none, which the email, teams, whatsapp, event_mesh, webhook, and google_chat types reject. Each entrypoint type has its own keys and value types.

Responses

Request samples

Content type
application/json
{
  • "description": "Answers customer support questions in Slack.",
  • "entrypointType": "slack",
  • "name": "Support Slack bot",
  • "slug": "support-slack-bot",
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an entrypoint

Undeploys the entrypoint if it is deployed, then deletes it. If the undeploy fails, the entrypoint is kept and the request fails with 502.

Token Permissions: [ entrypoint:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an entrypoint

Returns one entrypoint with its deployment and runtime status. Secret values are redacted.

Token Permissions: [ entrypoint:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an entrypoint

Changes the fields sent and keeps the rest. Only publicUrl can be cleared. The entrypoint type and slug cannot change. A deployed entrypoint runs its new settings after an update through POST /entrypointDeployments.

Token Permissions: [ entrypoint:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the entrypoint to update.

Request Body schema: application/json
required

The request body.

description
string

Says what the entrypoint is for, with the same rules as on create. Leave it out to keep it. Null or "" fails with 422.

entrypointType
string

Fixed at create. Including it fails with 422.

name
string

The display name, with the same rules as on create. Leave it out to keep it. Null or "" fails with 422.

publicUrl
string or null

The public address, an https URL. Leave it out to keep it, or send null or "" to clear it.

slug
string

Fixed at create. Including it fails with 422.

object

Changes the settings it includes and keeps the others. A secret setting sent as null or "" keeps its stored value, and "" clears an optional secret setting. Leave it out to keep every setting. Null fails with 422. Each entrypoint type has its own keys and value types.

Responses

Request samples

Content type
application/json
{
  • "description": "Answers customer support questions in Slack.",
  • "entrypointType": "slack",
  • "name": "Support Slack bot",
  • "slug": "support-slack-bot",
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate values against an entrypoint's stored secrets

Returns, for each secret setting of the entrypoint, whether saving the values sent would keep the stored secret. Secret values are never returned.

Token Permissions: [ entrypoint:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the entrypoint whose stored secrets are compared.

Request Body schema: application/json
required

The request body.

required
object

Holds the settings to compare. Only secret settings are compared. Each entrypoint type has its own keys and value types.

Responses

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Evaluation Datasets

Manage the datasets of examples that experiments run agents against.

Get a list of evaluation datasets

Returns one page of datasets with their example and experiment counts, newest first unless sorted, optionally only those whose name contains some text.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
name
string
Example: name=support

Limits the list to datasets whose name contains this text, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|createdTime|updatedTime|exampleCount|e...
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, createdTime, updatedTime, exampleCount, experimentCount.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an evaluation dataset

Creates an empty dataset. Add examples with POST /evaluations/datasets/{datasetId}/examples. If the name is taken, the request fails with 409.

Token Permissions: [ evaluation:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

description
string

Says what the examples cover. Up to 1,000 bytes.

name
required
string

The dataset's unique name. Up to 255 bytes.

Responses

Request samples

Content type
application/json
{
  • "description": "Questions customers asked support last month.",
  • "name": "Support tickets"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an evaluation dataset

Deletes the dataset with its examples and their files, its generation operations, and the run results scored against its examples. Experiments that ran the dataset are kept, with datasetId null. If one of those experiments has a run pending or running, the request fails with 422.

Token Permissions: [ evaluation:_:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an evaluation dataset

Returns one dataset with its example and experiment counts.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an evaluation dataset

Changes the fields the body includes and keeps the rest. If another dataset already has the name, the request fails with 409.

Token Permissions: [ evaluation:_:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the dataset to update.

Request Body schema: application/json
required

The request body.

description
string or null

Says what the examples cover. Up to 1,000 bytes. Leave it out to keep it, or send null to clear it.

name
string

The dataset's unique name. Up to 255 bytes. Leave it out to keep it. Null or an empty string fails with 422.

Responses

Request samples

Content type
application/json
{
  • "description": "Questions customers asked support in April.",
  • "name": "Support tickets, April"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Evaluation Evaluators

Manage the evaluators that score the answers an agent gives in an experiment.

Get a list of evaluation evaluators

Returns one page of evaluators with the number of experiments each is attached to: the built-in evaluators first, then the others oldest first, unless sorted.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|createdTime)(:(asc|desc))?$
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, createdTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an evaluation evaluator

Creates an llm_judge evaluator, or a decision evaluator while decision evaluators are enabled on the deployment. If the name is taken, the request fails with 409.

Token Permissions: [ evaluation:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
header Parameters
X-Sam-Client-Surface
string
Example: ui

The X-Sam-Client-Surface header: ui or cli names the first-party client that makes the request, and any other value, or no header, counts as api. Used only for usage statistics.

Request Body schema: application/json
required

The request body.

object

Maps each choice the model can answer with to its score. An llm_judge needs 2 to 26 choices. A decision evaluator needs one score from 0 to 1 for each option of a choice question, and none for any other question.

description
required
string

Says what the evaluator checks, 1 to 1,000 bytes.

escalateToEvaluatorId
string or null

The UUID of an llm_judge evaluator that scores a case the model is unsure of or fails on. Only for a decision evaluator.

evaluatorType
string

The kind of evaluator: llm_judge or decision. Defaults to llm_judge. Decision evaluators can be created only while they are enabled on the deployment. Heuristic evaluators are built in and cannot be created.

minConfidence
number or null

The confidence below which the case goes to escalateToEvaluatorId: more than 0 and up to 1, and more than 0.5 for a boolean question. Requires escalateToEvaluatorId. Only for a decision evaluator.

model
required
string

The alias or UUID of the model configuration that scores: a chat model for an llm_judge, a decision model for a decision evaluator. Required for both.

name
required
string

The evaluator's unique name. Up to 255 bytes.

promptTemplate
string or null

The llm_judge's grading prompt. Required for an llm_judge and not allowed for a decision evaluator. It must contain {{ Response }} and can use {{ Prompt }} and {{ Expected Response }}. In a workflow experiment, it can also use {{ Node Output: }} and {{ Node Input: }} so the judge can grade one node. Each takes a redacted, length-capped preview of what that node returned or took in the trial. In an agent experiment, these placeholders are left as written. Name a node of a nested sub-workflow under the node that ran it, as in {{ Node Output: enrich ▸ validate }}. A map or loop node reports once for the whole node. A map's output lists each item's result. A loop's output says only how many iterations ran and why it stopped. The nodes inside a map or loop cannot be named. While workflow evaluations are turned on, a template is refused if a node placeholder has no node id or is mistyped, such as {{ Node Outputs: x }}.

object or null

The question a decision evaluator asks. Required for a decision evaluator and not allowed for an llm_judge.

reads
Array of strings

The case fields a decision evaluator sends its model, from prompt, response, expected_response, transcript, and artifacts. Must include response. Defaults to prompt, response, and expected_response. In a workflow experiment, transcript sends the workflow's node-by-node run under the key workflow_trajectory. Only for a decision evaluator.

scoring
string

How a decision evaluator turns an answer into a score: chosen scores the option the model chose, and expected weighs every option by its probability. Defaults to chosen. Only for a decision evaluator.

Responses

Request samples

Content type
application/json
{
  • "choiceScores": {
    },
  • "description": "Judges whether the answer addresses the question.",
  • "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  • "evaluatorType": "llm_judge",
  • "minConfidence": 0.7,
  • "model": "general",
  • "name": "Answer relevance",
  • "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer relevant?",
  • "question": {
    },
  • "reads": [
    ],
  • "scoring": "chosen"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an evaluation evaluator

Deletes the evaluator and detaches it from its experiments. The scores it gave are kept. If the evaluator is built in, the request fails with 409. If a decision evaluator escalates to it, the request fails with 422.

Token Permissions: [ evaluation:_:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an evaluation evaluator

Returns one evaluator with the number of experiments it is attached to.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an evaluation evaluator

Changes the fields the body includes and keeps the rest. The evaluatorType cannot change. A decision evaluator cannot be edited while decision evaluators are disabled. A built-in evaluator accepts only a model change, and only when it is an llm_judge; any other change to it fails with 409, as does a name another evaluator has.

Token Permissions: [ evaluation:_:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the evaluator to update.

Request Body schema: application/json
required

The request body.

object or null

Replaces the score of each choice. Leave it out to keep them. For an llm_judge, null fails with 422. For a decision evaluator whose question is no longer a choice, null clears them.

description
string

Says what the evaluator checks, 1 to 1,000 bytes. Leave it out to keep it. Null or an empty string fails with 422.

escalateToEvaluatorId
string or null

The UUID of the llm_judge a decision evaluator escalates to. Leave it out to keep it, or send null to clear it.

evaluatorType
string

Fixed when the evaluator is created. If the body includes it, the request fails with 422.

minConfidence
number or null

The confidence below which a decision evaluator escalates. Leave it out to keep it, or send null to clear it.

model
string or null

The alias or UUID of the model configuration that scores. Leave it out to keep it. An empty string fails with 422. Null resets a built-in llm_judge to the general model, and fails with 422 for any other evaluator.

name
string

The evaluator's unique name. Up to 255 bytes. Leave it out to keep it. Null or an empty string fails with 422.

promptTemplate
string or null

The llm_judge's grading prompt. It must contain {{ Response }} and can name a workflow node, as on create. Leave it out to keep it. A template sent back unchanged, apart from placeholder spelling and surrounding whitespace, is never refused for its node placeholders. For an llm_judge, null fails with 422. A decision evaluator has no prompt template, so null is accepted.

object

Replaces a decision evaluator's question. Leave it out to keep it. Null fails with 422, because a question cannot be cleared. Send choiceScores with a changed choice question.

reads
Array of strings or null

Replaces the case fields a decision evaluator sends its model. Leave it out to keep them, or send null for prompt, response, and expected_response.

scoring
string or null

How a decision evaluator turns an answer into a score: chosen or expected. Leave it out to keep it, or send null for chosen.

Responses

Request samples

Content type
application/json
{
  • "choiceScores": {
    },
  • "description": "Judges whether the answer fully addresses the question.",
  • "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  • "evaluatorType": "llm_judge",
  • "minConfidence": 0.6,
  • "model": "planning",
  • "name": "Answer relevance, strict",
  • "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer fully relevant?",
  • "question": {
    },
  • "reads": [
    ],
  • "scoring": "expected"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Evaluation Examples

Manage the examples in an evaluation dataset: each prompt with its expected answer and files, added one at a time or imported and exported in bulk.

Get a list of examples in an evaluation dataset

Returns one page of the dataset's examples in sequenceNumber order, optionally only those whose prompt or expected response contains some text. If the dataset does not exist, the request fails with 404.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
datasetId
required
string <uuid>

The UUID of the dataset.

query Parameters
content
string
Example: content=refund

Limits the list to examples whose prompt or expected response contains this text, ignoring case.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(sequenceNumber|createdTime|updatedTime)(:(a...
Example: sort=sequenceNumber:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: sequenceNumber, createdTime, updatedTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an evaluation example

Adds an example to the dataset and returns a Location header that points to it. The example needs a prompt, an inputData object, or both. The request fails with 422 if the dataset already holds its limit of examples, if another example has the sequenceNumber, or if inputData, expectedPath, or expectedFacts is set while workflow evaluations are turned off.

Token Permissions: [ evaluation:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
datasetId
required
string <uuid>

The UUID of the dataset to add the example to.

Request Body schema: application/json
required

The request body.

object or null

What the example's response must and must not say, for the Output Facts evaluator. Leave it out or send null for none. Setting it fails with 422 unless workflow evaluations are turned on.

object or null

How the example's trials are expected to run, for the Workflow Path evaluator. Leave it out or send null for none. Setting it fails with 422 unless workflow evaluations are turned on.

expectedResponse
string or null

The answer to compare the agent's answer to. Leave it out or send null for none.

inputData
object or null

The structured input for a workflow example: a JSON object of up to 256 KiB, kept exactly as sent. Leave it out or send null for none. Setting it fails with 422 unless workflow evaluations are turned on.

prompt
string

The message the agent is given. Cannot be empty unless inputData is set.

sequenceNumber
integer or null <int64>

Places the example in the dataset, from 1. Leave it out to add the example after the others. If another example in the dataset has the number, the request fails with 422.

Responses

Request samples

Content type
application/json
{
  • "expectedFacts": {
    },
  • "expectedPath": {
    },
  • "expectedResponse": "4",
  • "inputData": {
    },
  • "prompt": "What is 2 + 2?",
  • "sequenceNumber": 3
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an evaluation example

Deletes the example with its files and the run results recorded for it.

Token Permissions: [ evaluation:_:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an evaluation example

Returns one example with the metadata of its input and expected files.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an evaluation example

Changes the prompt, expected response, inputData, expectedPath, and expectedFacts the body includes and keeps the rest. A null expectedPath or expectedFacts clears it. If the body includes sequenceNumber or datasetId, the request fails with 422, because both are fixed when the example is created.

Token Permissions: [ evaluation:_:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the example to update.

Request Body schema: application/json
required

The request body.

datasetId
string

Fixed when the example is created. If the body includes it, the request fails with 422.

object or null

Replaces what the example's response must and must not say. Leave it out to keep it, or send null to clear it. Setting it fails with 422 unless workflow evaluations are turned on, but clearing it does not.

object or null

Replaces how the example's trials are expected to run. Leave it out to keep it, or send null to clear it. Setting it fails with 422 unless workflow evaluations are turned on, but clearing it does not.

expectedResponse
string or null

The answer to compare the agent's answer to. Leave it out to keep it, or send null to clear it.

inputData
object or null

Replaces the structured input of a workflow example with a JSON object of up to 256 KiB. Leave it out to keep it, or send null to clear it. An example with no prompt cannot clear it. Setting it fails with 422 unless workflow evaluations are turned on, but clearing it does not.

prompt
string

The message the agent is given. Leave it out to keep it. Null fails with 422, and so does an empty string unless the example has inputData after the update.

sequenceNumber
integer <int64>

Fixed when the example is created. If the body includes it, the request fails with 422.

Responses

Request samples

Content type
application/json
{
  • "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  • "expectedFacts": {
    },
  • "expectedPath": {
    },
  • "expectedResponse": "6",
  • "inputData": {
    },
  • "prompt": "What is 3 + 3?",
  • "sequenceNumber": 3
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Evaluation Experiments

Define experiments that run an agent against a dataset's examples and score its answers with evaluators.

Get a list of evaluation experiments

Returns one page of experiments, newest first unless sorted, optionally only those that run one dataset, are scored by one evaluator, or evaluate one agent.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
datasetId
string
Example: datasetId=0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d

Limits the list to experiments that run this dataset UUID.

evaluatorId
string
Example: evaluatorId=0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d

Limits the list to experiments this evaluator UUID scores.

targetAgent
string
Example: targetAgent=OrderAgent

Limits the list to experiments that evaluate this agent name.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name|createdTime)(:(asc|desc))?$
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name, createdTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an evaluation experiment

Creates an experiment without running it. Start a run with PUT /evaluations/experiments/{experimentId}/trigger. If the name is taken, the request fails with 409.

Token Permissions: [ evaluation:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

datasetId
required
string

The UUID of the dataset whose examples the experiment runs.

description
string

Says what the experiment measures.

evaluatorIds
required
Array of strings

The UUIDs of 1 to 5 evaluators to score each answer with.

maxWorkers
integer or null <int64>

How many examples run at once, 1 to 20. Defaults to 4.

Array of objects (ExperimentModel)

The models to run the agent under, one run each. Up to 3. Leave it out to use the agent's own model.

name
required
string

The experiment's unique name. Up to 255 characters.

primaryEvaluatorId
string or null

The UUID of the evaluator whose score is the headline result. Must be one of evaluatorIds.

runAs
string or null

Names the system user the runs execute as. A bare name becomes system:. Leave it out for the built-in evaluation system user. The system users that entrypoints run as are not allowed, because the experiment would share their tool credentials.

runsPerExample
integer or null <int64>

How many times each example runs, 1 to 10. Defaults to 1.

targetAgent
string

The name of the agent to evaluate. Up to 255 characters. Send it or targetWorkflow, not both.

targetWorkflow
string

The name of the workflow to evaluate, in place of targetAgent. Up to 255 characters. Refused unless workflow evaluations are turned on.

Responses

Request samples

Content type
application/json
{
  • "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  • "description": "Checks the support agent against last month's tickets.",
  • "evaluatorIds": [
    ],
  • "maxWorkers": 4,
  • "models": [
    ],
  • "name": "Support answers, March",
  • "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  • "runAs": "nightly-evals",
  • "runsPerExample": 1,
  • "targetAgent": "support_agent",
  • "targetWorkflow": "order_exception_handler"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an evaluation experiment

Deletes the experiment with its runs and their results. If a run is pending or running, the request fails with 422. Cancel the run first.

Token Permissions: [ evaluation:_:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get an evaluation experiment

Returns one experiment with the status and start time of its latest run.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an evaluation experiment

Changes the fields the body includes and keeps the rest. Runs already started keep the settings they started with. If another experiment already has the name, the request fails with 409.

Token Permissions: [ evaluation:_:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the experiment to update.

Request Body schema: application/json
required

The request body.

datasetId
string

The UUID of the dataset to run. Leave it out to keep it. Null fails with 422.

description
string or null

Says what the experiment measures. Leave it out to keep it, or send null to clear it.

evaluatorIds
Array of strings

Replaces the evaluators, 1 to 5 UUIDs. Leave it out to keep them. Null fails with 422.

maxWorkers
integer <int64>

How many examples run at once, 1 to 20. Leave it out to keep it. Null fails with 422.

Array of objects or null

Replaces the models, up to 3. Leave it out to keep them, or send null to run the agent's own model.

name
string

The experiment's unique name. Leave it out to keep it. Null or an empty string fails with 422.

primaryEvaluatorId
string or null

The UUID of the headline evaluator, one of the evaluators. Leave it out to keep it, or send null to clear it.

runAs
string or null

Names the system user the runs execute as. Leave it out to keep it, or send null for the built-in evaluation system user.

runsPerExample
integer <int64>

How many times each example runs, 1 to 10. Leave it out to keep it. Null fails with 422.

targetAgent
string

The agent to evaluate. Leave it out to keep the target. Null or an empty string fails with 422. Sending it on a workflow experiment makes it an agent experiment.

targetWorkflow
string

The workflow to evaluate, in place of targetAgent. Leave it out to keep the target. Null or an empty string fails with 422. Sending it on an agent experiment makes it a workflow experiment. Send targetAgent or targetWorkflow, not both.

Responses

Request samples

Content type
application/json
{
  • "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  • "description": "Checks the support agent against this month's tickets.",
  • "evaluatorIds": [
    ],
  • "maxWorkers": 8,
  • "models": [
    ],
  • "name": "Support answers, April",
  • "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  • "runAs": "nightly-evals",
  • "runsPerExample": 2,
  • "targetAgent": "support_agent",
  • "targetWorkflow": "order_exception_handler"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Evaluation Run Results

Read the outcome of each trial of an evaluation run: the answer, the scores, the token use, and the files, messages, and events captured along the way.

Get the execution data of an evaluation run result

Returns the event broker messages captured while the trial ran. The messages list is empty when the trial captured nothing, or when Agent Mesh stores no evaluation data because none of EVAL_DATA_BUCKET_NAME, OBJECT_STORAGE_BUCKET_NAME, or OBJECT_STORAGE_FS_ROOT is set.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
runResultId
required
string <uuid>

The run result's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the task events of an evaluation run result

Returns the whole event stream recorded while the trial ran, in one response rather than in pages. The events list is empty when the trial recorded none, or when Agent Mesh stores no evaluation data because none of EVAL_DATA_BUCKET_NAME, OBJECT_STORAGE_BUCKET_NAME, or OBJECT_STORAGE_FS_ROOT is set.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
runResultId
required
string <uuid>

The run result's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of results for an evaluation run

Returns one page of the run's trial results, in dataset order and then trial order, each with its scores.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
runId
required
string <uuid>

The run's UUID.

query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Evaluation Runs

Start an experiment, follow its runs, read each run's status and scores, and cancel a run.

Get an operation of an evaluation experiment

Returns the operation a trigger started. Its status is pending until the first run starts, and inProgress until every run has finished. After that, the status is failed if any run failed, else cancelled if any run was canceled, else succeeded. A run stopped at its time limit finishes with the results it has, so the operation can still end succeeded. That run's errorMessage says it was stopped. The status comes from the operation's remaining runs, so deleting one of them can change it. It can also differ from the run group's status, which stays pending while any run waits to start. If the operation belongs to another experiment, the request fails with 404.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
experimentId
required
string <uuid>

The UUID of the experiment the operation acts on.

id
required
string <uuid>

The operation's UUID, the runGroupId of the runs it started.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of an evaluation experiment's runs

Returns one page of the experiment's runs, newest first.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
experimentId
required
string <uuid>

The UUID of the experiment whose runs to list.

query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Initiate a run of an evaluation experiment

Starts one run per model of the experiment and returns 202 with an operation for them. Poll the operation at the Location header until its status is succeeded, failed, or cancelled. If a run of the experiment is pending or running, the request fails with 409. If the experiment has no dataset, no evaluators, or a dataset with no examples, the request fails with 422. If the run cannot be started, the request fails with 503.

Token Permissions: [ evaluation:_:invoke ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
experimentId
required
string <uuid>

The UUID of the experiment to run.

Request Body schema: application/json
required

The request body.

runName
string

Names the runs in reports. Defaults to the experiment's name.

Responses

Request samples

Content type
application/json
{
  • "runName": "Support answers, March"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an evaluation run group

Returns one run group with its runs and whether the experiment changed since it started.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an evaluation run

Returns one run with its status, progress, scores, and the configuration it started with.

Token Permissions: [ evaluation:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an evaluation run to cancel it

Stops a pending or running run and returns it. If the run has already finished, the request fails with 422.

Token Permissions: [ evaluation:_:invoke ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Models

Manage the large language model (LLM) configurations that agents and workflows run on, see what uses each one, and probe a provider before saving one.

Get a list of models

Returns one page of the models agents and workflows can run on. Secret credential values are never returned.

Token Permissions: any signed-in caller. No scope is required. API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(alias|createdTime)(:(asc|desc))?$
Example: sort=alias:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: alias, createdTime.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a model

Creates a model configuration and returns it. If another model already has the alias, the request fails with 409.

Token Permissions: [ model_config:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
header Parameters
X-Sam-Client-Surface
string
Example: ui

The X-Sam-Client-Surface header, which says what kind of client is calling: ui, cli, or api. Any other value, or none, counts as api. It only feeds usage statistics.

Request Body schema: application/json
required

The request body.

alias
required
string

The name agents refer to the model by. If another model already has it, the request fails with 409.

apiBase
string

The provider endpoint. Leave it out to use the provider's default.

object

Holds the credential fields the auth type defines. A value of fails with 422, because reads send it in place of a stored secret.

authType
string

How Agent Mesh authenticates to the provider: none, apikey, oauth2, bearer, basic, aws_iam, gcp_service_account, or azure_workload_identity. Any other type fails with 422, with the error on authConfig.type. Matching is exact, so APIKey fails. Optional, and read only when authConfig carries no type.

description
string

Says what the model is for.

maxInputTokens
integer or null <int64>

Caps the prompt, in tokens. Leave it out to use the provider's own limit.

modelName
required
string

The provider's own name for the model.

object

The generation parameters forwarded to the provider.

modelType
string

The kind of model: chat or decision. Defaults to chat.

object or null

The model's token rates. Leave it out for an unpriced model.

provider
required
string

The large language model (LLM) provider, such as openai or anthropic.

Responses

Request samples

Content type
application/json
{
  • "alias": "support-chat",
  • "authConfig": {
    },
  • "authType": "apikey",
  • "description": "Fast model for support replies",
  • "maxInputTokens": 128000,
  • "modelName": "gpt-4o",
  • "modelParams": {
    },
  • "modelType": "chat",
  • "pricing": {
    },
  • "provider": "openai"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a model

Undeploys every agent and workflow that may still be running on the model, then deletes it. If any of them cannot be undeployed, nothing is deleted and the request fails with 502. Deleting the general or planning alias, which Agent Mesh itself runs on, fails with 409.

Token Permissions: [ model_config:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a model

Returns one model configuration. Secret credential values are never returned.

Token Permissions: any signed-in caller. No scope is required. API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a model

Changes the fields the body includes. A secret sent as keeps the stored value.

Token Permissions: [ model_config:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the model to update.

header Parameters
X-Sam-Client-Surface
string
Example: ui

The X-Sam-Client-Surface header, which says what kind of client is calling: ui, cli, or api. Any other value, or none, counts as api. It only feeds usage statistics.

Request Body schema: application/json
required

The request body.

alias
string

The name agents refer to the model by. Leave it out to keep it. Null or an empty string fails with 422.

apiBase
string

The provider endpoint. Leave it out to keep it, or send an empty string to use the provider's default. Null fails with 422.

object

Merges into the stored credentials. Leave it out to keep them. Null fails with 422. A field sent as , the value reads return for a secret, keeps its stored value. A type, when sent and not null, must be a string naming a supported auth type. Anything else fails with 422, with the error on authConfig.type.

authType
string

How Agent Mesh authenticates to the provider. Leave it out to keep it. Null or an empty string fails with 422. When authConfig carries a type, that type wins. Changing the type drops the old type's stored credentials, so send the new type's credentials in the same request. The supported types are none, apikey, oauth2, bearer, basic, aws_iam, gcp_service_account, and azure_workload_identity, matched exactly. Any other type fails with 422, with the error on authConfig.type, unless it is the type the model already holds.

description
string or null

Says what the model is for. Leave it out to keep it, or send null to clear it.

maxInputTokens
integer or null <int64>

Caps the prompt, in tokens. Leave it out to keep it, or send null to use the provider's limit.

modelName
string

The provider's own name for the model. Leave it out to keep it. Null or an empty string fails with 422.

object

Replaces every generation parameter. Leave it out to keep them. Null fails with 422.

modelType
string

Fixed when the model is created. Including it fails with 422.

object or null

Replaces the model's token rates: an object of optional decimal strings in US dollars per million tokens, named input, output, cacheRead, and cacheWrite. Any other key fails with 422. Leave it out to keep the stored price. Send null to clear the price. An object replaces the price whole, so a rate it leaves out or sets to null is cleared. Send input and output together, and the cache rates only alongside them.

provider
string

The large language model (LLM) provider. Leave it out to keep it. Null or an empty string fails with 422.

Responses

Request samples

Content type
application/json
{
  • "alias": "support-chat",
  • "authConfig": {
    },
  • "authType": "apikey",
  • "description": "Fast model for support replies",
  • "maxInputTokens": 128000,
  • "modelName": "gpt-4o",
  • "modelParams": {
    },
  • "modelType": "chat",
  • "pricing": {
    },
  • "provider": "openai"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of the agents and workflows that use a model

Returns one page of the agents and workflows that use the model. Use it to see what deleting the model affects; for that reason it requires the permission to delete a model.

Token Permissions: [ model_config:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The UUID of the model whose dependents to list.

query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

sort
string^(name)(:(asc|desc))?$
Example: sort=name:asc

The field to sort by and, optionally, the direction, as field, field:asc or field:desc. A field alone sorts ascending. Sortable fields: name.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Validate values against a model's stored secrets

Returns, for each secret credential field of the model's auth type, whether saving the values sent would keep the stored secret. Secret values are never returned.

Token Permissions: [ model_config:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a

The UUID of the model whose stored secrets are compared.

Request Body schema: application/json
required

The request body.

required
object

Holds the credential fields to compare. Only secret fields are compared. The model's auth type sets the keys.

Responses

Request samples

Content type
application/json
{
  • "authConfig": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Health

Check that the platform is running.

Get the platform's health

Returns 200 while the platform is up, for use as a health probe.

Token Permissions: none. The operation needs no sign-in.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Profile Provider

Set the service that supplies user profiles.

Delete the profile provider

Clears the wired toolset and keeps the lookup key. Returns 204 even when no toolset was wired.

Token Permissions: [ profile_provider:_:update ] API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get the profile provider

Returns the toolset that enriches a signed-in user's profile and the attribute it looks the user up by. The toolset is null when none is wired, and the lookup key is email until one is set.

Token Permissions: [ profile_provider:*:read or profile_provider:_:update ] API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace the profile provider

Wires a toolset as the profile provider and sets the attribute it looks the user up by, replacing both. The toolset must be ready, declare the profileProvider capability, and expose the enrich_authenticated_user tool. If it does not, the request fails with 422 and lists each unmet condition under toolsetId.

Token Permissions: [ profile_provider:_:update ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

lookupKey
required
string

The user attribute Agent Mesh sends the toolset to find the user by, such as email or upn. Required, because a PUT replaces the whole profile provider and does not fall back to email.

toolsetId
required
string

The UUID of the toolset to wire. It must be ready, declare the profileProvider capability, and expose the enrich_authenticated_user tool.

Responses

Request samples

Content type
application/json
{
  • "lookupKey": "upn",
  • "toolsetId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Version

Read the platform version.

Get the platform's version

Returns the version of each product in the build and the oldest sam CLI version the platform supports. The sam CLI checks that version before it plans or applies a configuration.

Token Permissions: none. The operation needs no sign-in.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Web UI Settings

Read and change the settings of the web UI.

Get the web UI settings

Returns the web UI settings an administrator has overridden for the whole instance. Every field is null when no override is stored, meaning the web UI entrypoint's own value applies.

Token Permissions: [ webui_settings:*:read ] API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace the web UI settings

Replaces every override with the body. A field left out or null stores no override. A body with every field null clears all overrides. If fields fail validation, the request fails with 422 and lists each one under its own name.

Token Permissions: [ webui_settings:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

appName
string or null

The application name. Up to 64 characters, with no control characters. Null or left out means no override, so the web UI entrypoint's own value applies.

collectFeedback
boolean or null

Sets whether users can rate responses. Null or left out means no override, so the web UI entrypoint's own value applies.

disclaimerText
string or null

The disclaimer shown beneath the chat input. Up to 800 characters. Null or left out means no override, so the web UI entrypoint's own value applies.

feedbackTaskInfoLevel
string or null

How much task content leaves the mesh with each published feedback event: none, summary, or stim. Null or left out means no override, so the web UI entrypoint's own value applies.

logoUrl
string or null

The full logo, as an http(s) URL, a site-relative path, or a data:image URI. An empty string shows no logo. Null or left out means no override, so the web UI entrypoint's own value applies.

publishFeedback
boolean or null

Sets whether feedback is published to the event broker. Null or left out means no override, so the web UI entrypoint's own value applies.

responseFormat
string or null

The response-format guidance added to every prompt. Up to 4,000 characters. Null or left out means no override, so the web UI entrypoint's own value applies.

smallLogoUrl
string or null

The compact logo, in the same forms as logoUrl. Null or left out means no override, so the web UI entrypoint's own value applies.

systemPurpose
string or null

The purpose text added to every prompt, so its length costs tokens on every task. Up to 4,000 characters. Null or left out means no override, so the web UI entrypoint's own value applies.

welcomeMessage
string or null

The greeting on a new chat. Up to 2,000 characters. Null or left out means no override, so the web UI entrypoint's own value applies.

Responses

Request samples

Content type
application/json
{
  • "appName": "Acme Assistant",
  • "collectFeedback": true,
  • "disclaimerText": "Responses may be inaccurate.",
  • "feedbackTaskInfoLevel": "summary",
  • "publishFeedback": false,
  • "responseFormat": "Answer in short paragraphs.",
  • "smallLogoUrl": "/assets/logo-small.svg",
  • "systemPurpose": "You help customers track their orders.",
  • "welcomeMessage": "Ask me anything about your orders."
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Skills

Manage the skills that give agents instructions, reference files, and tools: upload or download a skill's bundle, set the settings every agent gets, and see which agents use each skill.

Get a list of skills

Returns one page of skills, the built-in ones first, optionally only custom or built-in ones.

Token Permissions: [ skill:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
origin
string
Example: origin=custom

Limits the list to custom or builtin skills. Leave it out for both, built-in first.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a skill

Creates a skill from a ZIP sent as the file part of a multipart/form-data body, with an optional description part. The skill takes its name from the ZIP's SKILL.md. Its discoveryStatus is pending until the tool runtime has read the bundle. If a skill with that name exists, the request fails with 409.

Token Permissions: [ skill:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required

The request body.

description
string

Tells agents when to use the skill, sent as a part of the multipart/form-data body. Leave it out for none.

file
required
string <binary>

The skill's ZIP, sent as the file part of a multipart/form-data body, with a filename ending in .zip. Up to 100 MB, and up to 500 MB and 10,000 entries unpacked. Its SKILL.md, at the root or in one top-level directory, must start with YAML frontmatter that names the skill. The name has up to 128 letters, digits, hyphens, and underscores, and starts with a letter. It must be unique and must not start with the reserved prefix of a built-in skill.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a skill

Deletes the skill and its bundle, and removes it from every agent that uses it. For a built-in skill, which cannot be deleted, the request fails with 409.

Token Permissions: [ skill:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: sam-docs

The skill's UUID, or for a built-in skill its name, such as sam-docs.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a skill

Returns one skill, by its UUID or, for a built-in skill, its name.

Token Permissions: [ skill:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: sam-docs

The skill's UUID, or for a built-in skill its name, such as sam-docs.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a skill

Changes the description. The name comes from the bundle's SKILL.md and cannot be changed. For a built-in skill, which cannot be changed, the request fails with 409.

Token Permissions: [ skill:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the skill to update, or for a built-in skill its name, such as sam-docs.

Request Body schema: application/json
required

The request body.

description
string

Tells agents when to use the skill. Leave it out to keep it. Null or an empty string fails with 422.

name
string

Cannot be changed, because it comes from the bundle's SKILL.md: sending it, even as null, fails with 422.

Responses

Request samples

Content type
application/json
{
  • "description": "Look up and explain customer orders.",
  • "name": "order-lookup"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a skill's bundle

Downloads the skill's ZIP as application/zip, named after the skill. For a skill with no bundle, and for a built-in skill, the request fails with 409.

Token Permissions: [ skill:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: sam-docs

The skill's UUID, or for a built-in skill its name, such as sam-docs.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Replace a skill's bundle

Uploads the skill's ZIP as the file part of a multipart/form-data body and returns the skill. Its discoveryStatus is pending until the tool runtime has read the bundle. The ZIP's SKILL.md must name the skill. If the body is over 100 MB, the request fails with 413.

Token Permissions: [ skill:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the skill whose bundle to replace, or for a built-in skill its name, such as sam-docs.

Request Body schema: multipart/form-data
required

The request body.

file
required
string <binary>

The skill's ZIP, sent as the file part of a multipart/form-data body, with a filename ending in .zip. Its SKILL.md must name the skill. Up to 100 MB, and up to 500 MB and 10,000 entries unpacked.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a skill's configuration

Returns the settings the skill gives every agent that uses it. Secret values are redacted. A built-in skill has no settings. The request fails with 409 until the skill's discoveryStatus is ready.

Token Permissions: [ skill:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: sam-docs

The skill's UUID, or for a built-in skill its name, such as sam-docs.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Toolset Build Target

Read the platform to build toolset binaries for.

Get the build target for toolset bundles

Returns the platform and Python version to build a toolset's bundle for. If tool runtimes on different platforms are active, the request fails with 409 and lists the targets in validationDetails.

Token Permissions: [ toolset:*:read ] API keys can call this operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Toolset Uploads

Upload a toolset bundle in chunks.

Initiate a chunked upload of a toolset's bundle

Starts an upload of a toolset's ZIP in chunks, for a bundle too large for PUT /toolsets/{id}/bundle. The response gives the chunkSize to split the bundle at. PUT each chunk to /toolsetUploads/{toolsetUploadId}/chunks/{id}, then complete the upload. An upload is discarded 1 hour after it is created.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

filename
required
string

The name to store the bundle under. It must end in .zip.

toolsetId
required
string

The UUID of the toolset to upload the bundle for.

totalSize
required
integer <int64>

The size in bytes of the whole bundle, from 1 to the deployment's maximum upload size, 100 MB by default.

Responses

Request samples

Content type
application/json
{
  • "filename": "order_tools.zip",
  • "toolsetId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
  • "totalSize": 9437184
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a chunked toolset upload

Returns the upload's progress, to resume after an interruption: send the chunks missing from receivedChunks. After the upload is completed or has expired, the request fails with 404.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a toolset upload to complete it

Assembles the chunks, stores them as the toolset's bundle, and returns the toolset. Its discoveryStatus is pending until the tool runtime has found its tools. Agents that use the toolset are redeployed. If a chunk is missing, the request fails with 422. After the chunks are assembled, the upload is discarded.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace a chunk of a toolset upload

Stores the raw request body as chunk {id} of the upload, replacing any chunk already sent at that index. Every chunk but the last must be exactly chunkSize bytes. If the index is past the last chunk or the chunk is the wrong size, the request fails with 422. If the chunks received would exceed totalSize, the request fails with 413.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
toolsetUploadId
required
string <uuid>

The UUID of the upload the chunk belongs to.

id
required
integer <int64>

The chunk's index, counting from 0. Sending an index again replaces that chunk.

Request Body schema: application/octet-stream
required

The bytes, sent as the request body.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Toolsets

Manage the toolsets that give agents their tools: upload a bundle of tools, set the settings every agent gets, and see which agents use each toolset.

Get a list of toolsets

Returns one page of toolsets, the built-in ones first, optionally only custom or built-in ones, or custom ones in one discovery status.

Token Permissions: [ toolset:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
origin
string
Example: origin=custom

Limits the list to custom or builtin toolsets. Leave it out for both, built-in first.

discoveryStatus
string
Example: discoveryStatus=ready

Limits the list to custom toolsets in one discovery status: pending, ready, failed, or removed.

pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a toolset

Creates a toolset with no tools. Upload its bundle with PUT /toolsets/{id}/bundle, or in chunks with POST /toolsetUploads.

Token Permissions: [ toolset:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

description
string

Says what the toolset's tools do. Leave it out for none.

name
required
string

The toolset's name: up to 128 letters, digits, hyphens, and underscores, starting with a letter. It must be unique and must not be the name of a built-in toolset.

Responses

Request samples

Content type
application/json
{
  • "description": "Look up and update customer orders.",
  • "name": "order_tools"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a toolset

Deletes the toolset and its bundle, and removes it from every agent that uses it. Those agents are redeployed. For a built-in toolset, which cannot be deleted, the request fails with 409.

Token Permissions: [ toolset:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: builtin_artifact_tools

The toolset's UUID, or for a built-in toolset its id, such as builtin_artifact_tools.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a toolset

Returns one toolset, by its UUID or, for a built-in toolset, its id.

Token Permissions: [ toolset:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: builtin_artifact_tools

The toolset's UUID, or for a built-in toolset its id, such as builtin_artifact_tools.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a toolset

Changes the fields sent and keeps the rest. Null clears the description. The name cannot change after a bundle is uploaded. For a built-in toolset, which cannot be changed, the request fails with 409.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the toolset to update, or for a built-in toolset its id, such as builtin_artifact_tools.

Request Body schema: application/json
required

The request body.

description
string or null

Says what the toolset's tools do. Leave it out to keep it, or send null or "" to clear it.

name
string

The toolset's name, with the same rules as on create. It cannot change after a bundle is uploaded. Leave it out to keep it. Null or an empty string fails with 422.

Responses

Request samples

Content type
application/json
{
  • "description": "Look up and update customer orders.",
  • "name": "order_tools"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a toolset's bundle

Downloads the toolset's ZIP as application/zip. For a toolset with no bundle, and for a built-in toolset, the request fails with 409.

Token Permissions: [ toolset:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: builtin_artifact_tools

The toolset's UUID, or for a built-in toolset its id, such as builtin_artifact_tools.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Replace a toolset's bundle

Uploads the toolset's ZIP as the file part of a multipart/form-data body and returns the toolset. Its discoveryStatus is pending until the tool runtime has found its tools. Agents that use the toolset are redeployed. If the body is over 100 MB, the request fails with 413. Upload a larger bundle with POST /toolsetUploads.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the toolset whose bundle to replace, or for a built-in toolset its id, such as builtin_artifact_tools.

Request Body schema: multipart/form-data
required

The request body.

file
required
string <binary>

The toolset's ZIP, sent as the file part of a multipart/form-data body, with a filename ending in .zip. Up to 100 MB, and up to 500 MB and 10,000 entries unpacked.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a toolset's configuration

Returns the settings the toolset gives every agent that uses it. Secret values are redacted. The request fails with 409 until the toolset's discoveryStatus is ready.

Token Permissions: [ toolset:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: builtin_artifact_tools

The toolset's UUID, or for a built-in toolset its id, such as builtin_artifact_tools.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a toolset's configuration

Changes the settings sent and keeps the rest, then redeploys the agents that use the toolset. For a built-in toolset, and until the toolset's discoveryStatus is ready, the request fails with 409.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the toolset whose configuration to change, or for a built-in toolset its id, such as builtin_artifact_tools.

Request Body schema: application/json
required

The request body.

object

Maps each tool's name to the settings to change, and keeps the rest. A setting sent as null is cleared, but a secret sent as null or "" is kept. Leave values out to change nothing. Null fails with 422. Each tool's configSchema sets the keys of its settings.

Responses

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate settings against a toolset's stored secrets

Returns, for each secret setting of the toolset, whether saving the settings sent would keep the stored secret. Secret values are never returned. A built-in toolset has no secrets. The request fails with 409 until the toolset's discoveryStatus is ready.

Token Permissions: [ toolset:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f...
Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90

The UUID of the toolset whose stored secrets are compared, or for a built-in toolset its id, such as builtin_artifact_tools.

Request Body schema: application/json
required

The request body.

required
object

Holds the settings to compare, keyed by setting name or nested under each tool's name. Only secret settings are compared. Each tool's configSchema sets the keys of its settings.

Responses

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Workflow Deployments

Deploy and undeploy workflows, and read the outcome of each deployment.

Get a list of workflow deployments

Returns one page of workflow deployments, failed ones included.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Initiate a workflow deployment

Deploys, updates, or undeploys a workflow and returns the deployment record. Send deploymentId to roll back to the configuration an earlier deployment ran with. If the deploy runs and fails, the request fails with 502. If it is refused while deploying, such as for the workflow's own configuration, the request fails with 422. Both keep the record and link it in the Location header.

Token Permissions: [ workflow_builder:*:deploy ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

action
required
string

What to do: deploy, update, or undeploy.

deploymentId
string

Rolls the workflow back: the deploy or update sends the configuration this earlier deployment ran with instead of the workflow's current one. It must be a successful deploy or update of the same workflow. Leave it out for undeploy.

testMode
boolean

When true, adds an invoke scope for the caller alone to the deployed configuration. The workflow runtime does not enforce it yet. Defaults to false. Must be false for undeploy and with deploymentId.

workflowId
required
string

The UUID of the workflow to deploy.

Responses

Request samples

Content type
application/json
{
  • "action": "deploy",
  • "deploymentId": "0190f5eb-1e2f-7a3b-9c4d-5e6f7a8b9c0d",
  • "testMode": false,
  • "workflowId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a workflow deployment

Returns one deployment of a workflow, with why it failed when it did.

Token Permissions: [ deployment:_:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Workflows

Manage the workflows that run agents through a defined sequence of steps.

Get a list of workflows

Returns one page of workflows with their deployment and runtime status.

Token Permissions: [ workflow_builder:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
query Parameters
pageNumber
integer <int64> [ 1 .. 1000000 ]
Default: 1

The 1-based number of the page to return.

pageSize
integer <int64> [ 1 .. 100 ]
Default: 20

The maximum number of items on a page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a workflow

Creates a workflow without deploying it. Deploy it with POST /workflowDeployments. If the name is taken, the request fails with 409.

Token Permissions: [ workflow_builder:_:create ] API keys can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

The request body.

required
object

The workflow's app configuration, stored as sent. Its structure is up to the caller.

description
required
string

Says what the workflow does, 10 to 2,000 characters.

name
required
string

The workflow's unique name, 3 to 255 characters.

Responses

Request samples

Content type
application/json
{
  • "appConfig": {
    },
  • "description": "Routes each new order to the team that fulfils it.",
  • "name": "Order triage"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a workflow

Undeploys the workflow if it is deployed, then deletes it. If the undeploy fails, the workflow is kept and the request fails with 502.

Token Permissions: [ workflow_builder:*:delete ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
  • "message": "Request validation failed",
  • "validationDetails": {
    }
}

Get a workflow

Returns one workflow with its deployment and runtime status.

Token Permissions: [ workflow_builder:*:read ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

The resource's UUID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Replace a workflow

Replaces the workflow's name, description, and app configuration. A deployed workflow runs its new settings after it is updated through POST /workflowDeployments.

Token Permissions: [ workflow_builder:*:update ] API keys can call this operation.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a

The UUID of the workflow to replace.

Request Body schema: application/json
required

The request body.

required
object

Replaces the workflow's app configuration, stored as sent. Its structure is up to the caller.

description
required
string

The workflow's new description, 10 to 2,000 characters.

name
required
string

The workflow's new name, 3 to 255 characters.

Responses

Request samples

Content type
application/json
{
  • "appConfig": {
    },
  • "description": "Routes each new order to the team that fulfils it.",
  • "name": "Order triage"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}