Download OpenAPI specification:
REST API for managing agents, connectors, entrypoints, models, and deployments in Solace Agent Mesh.
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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "expiresTime": "2027-01-02T03:04:05.678Z",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "label": "deploy-pipeline",
- "lastUsedTime": "2026-01-03T10:15:30.000Z",
- "prefix": "Ab3dE-ex",
- "scopes": [
- "agent_builder:*:read"
], - "status": "active",
- "type": "apiKey",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "expiresTime": "2027-01-02T03:04:05.678Z",
- "label": "deploy-pipeline",
- "neverExpires": false,
- "scopes": [
- "agent_builder:*:read"
], - "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "expiresTime": "2027-01-02T03:04:05.678Z",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "label": "deploy-pipeline",
- "lastUsedTime": "2022-03-14T15:01:34.000Z",
- "prefix": "Ab3dE-ex",
- "scopes": [
- "agent_builder:*:read"
], - "secret": "samk_Ab3dE-example-secret-not-real",
- "status": "active",
- "type": "apiKey",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-02T03:04:05.678Z",
- "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one API key without its secret.
Token Permissions: the universal grant *:*:*. API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "expiresTime": "2027-01-02T03:04:05.678Z",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "label": "deploy-pipeline",
- "lastUsedTime": "2026-01-03T10:15:30.000Z",
- "prefix": "Ab3dE-ex",
- "scopes": [
- "agent_builder:*:read"
], - "status": "active",
- "type": "apiKey",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}
}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.
| id required | string <uuid> Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a The UUID of the key to rename. |
The request body.
| label required | string The key's new display name, 1 to 255 characters without control characters. |
{- "label": "deploy-pipeline"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "expiresTime": "2027-01-02T03:04:05.678Z",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "label": "deploy-pipeline",
- "lastUsedTime": "2026-01-03T10:15:30.000Z",
- "prefix": "Ab3dE-ex",
- "scopes": [
- "agent_builder:*:read"
], - "status": "active",
- "type": "apiKey",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "userId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f"
}
}Manage the roles, grants, claim mappings, default roles, and system users that decide what each caller can do, and read the scope catalog.
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.
| 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. |
{- "data": [
- {
- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "type": "claimMapping",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}{- "data": {
- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "type": "claimMapping",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one claim mapping, whatever its origin.
Token Permissions: [ rbac:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "type": "claimMapping",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The UUID of the claim mapping to replace. |
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. |
{- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}{- "data": {
- "claimKey": "groups",
- "claimValue": "platform-engineers",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "Platform engineers",
- "oidcProvider": "okta",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "type": "claimMapping",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
{- "data": {
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}
}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.
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. |
{- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}{- "data": {
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}
}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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "origin": "custom",
- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
- "state": "pending",
- "type": "grant",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "user": {
- "email": "jane.doe@example.com",
- "emailShared": false,
- "sub": "00u1abcd2EFGH3ijk4l5"
}, - "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "origin": "custom",
- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
- "state": "pending",
- "type": "grant",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "user": {
- "email": "jane.doe@example.com",
- "emailShared": false,
- "sub": "00u1abcd2EFGH3ijk4l5"
}, - "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one grant, whatever its origin.
Token Permissions: [ rbac:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "origin": "custom",
- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
- "state": "pending",
- "type": "grant",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "user": {
- "email": "jane.doe@example.com",
- "emailShared": false,
- "sub": "00u1abcd2EFGH3ijk4l5"
}, - "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}
}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.
| id required | string <uuid> The grant's UUID. |
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. |
{- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
- "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "origin": "custom",
- "roleId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40",
- "state": "pending",
- "type": "grant",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "user": {
- "email": "jane.doe@example.com",
- "emailShared": false,
- "sub": "00u1abcd2EFGH3ijk4l5"
}, - "userId": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e41"
}
}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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "description": "Runs and monitors the support agents.",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "nameConflict": false,
- "origin": "custom",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
], - "type": "role",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "description": "Runs and monitors the support agents.",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
]
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "description": "Runs and monitors the support agents.",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "nameConflict": false,
- "origin": "custom",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
], - "type": "role",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one role, whatever its origin.
Token Permissions: [ rbac:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "description": "Runs and monitors the support agents.",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "nameConflict": false,
- "origin": "custom",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
], - "type": "role",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The UUID of the role to replace. |
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. |
{- "description": "Runs and monitors the support agents.",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
]
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "description": "Runs and monitors the support agents.",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "inherits": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "name": "Support agent operator",
- "nameConflict": false,
- "origin": "custom",
- "scopes": [
- "agent:*:invoke",
- "agent_builder:*:read"
], - "type": "role",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "displayName": "Support webhook",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "support-webhook",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "sub": "system:support-webhook",
- "type": "systemUser",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "displayName": "Support webhook",
- "name": "support-webhook",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "displayName": "Support webhook",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "support-webhook",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "sub": "system:support-webhook",
- "type": "systemUser",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one system user, whatever its origin.
Token Permissions: [ rbac:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "displayName": "Support webhook",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "support-webhook",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "sub": "system:support-webhook",
- "type": "systemUser",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The UUID of the system user to replace. |
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. |
{- "displayName": "Support webhook",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
]
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "displayName": "Support webhook",
- "id": "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e3f",
- "name": "support-webhook",
- "origin": "custom",
- "roleIds": [
- "0190f5ec-6f7a-7b8c-ad0e-8a9b0c1d2e40"
], - "sub": "system:support-webhook",
- "type": "systemUser",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
{- "data": {
- "createDecisionModels": true,
- "manageRbac": true
}
}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.
| 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. |
{- "data": [
- {
- "action": "deploy",
- "agentId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5e5-1a2b-7d4e-8f60-718293a4b5c6",
- "status": "success",
- "type": "agentDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "action": "deploy",
- "agentId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "deploymentId": "0190f5e5-0c1d-7e2f-9a3b-4c5d6e7f8091",
- "skipIfCurrent": false
}{- "data": {
- "action": "deploy",
- "agentId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5e5-1a2b-7d4e-8f60-718293a4b5c6",
- "status": "success",
- "type": "agentDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "action": "deploy",
- "agentId": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5e5-1a2b-7d4e-8f60-718293a4b5c6",
- "status": "success",
- "type": "agentDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| 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. |
{- "data": [
- {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "agentType": "standard",
- "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deployed": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "deployedBy": "jane.doe@example.com",
- "deployedTime": "2026-01-03T10:16:00.000Z",
- "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}, - "deploymentStatus": "deployed",
- "description": "Answers customer questions about order status and delivery dates.",
- "expiresTime": "2026-01-02T04:04:05.678Z",
- "id": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "inputModes": [
- "text"
], - "instanceName": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "isEphemeral": false,
- "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "skillConfigFields": {
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d": [
- {
- "coveredByAgent": true,
- "coveredBySkill": false,
- "default": "us-east-1",
- "description": "Region the order service runs in.",
- "fieldType": "string",
- "key": "region",
- "required": true,
- "secret": false,
- "toolName": "lookup_order"
}
]
}, - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "sourceComponentKind": "agent",
- "sourceComponentName": "Order support agent",
- "sourceSessionId": "0190f5e8-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "syncStatus": "in_sync",
- "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolRegistrations": [
- {
- "connectorId": "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e",
- "error": "Some of this entry's tools were not registered. The agent's log has the cause.",
- "name": "orders_api",
- "status": "ready",
- "toolCount": 3,
- "toolNames": [
- "get_order",
- "list_orders",
- "update_order"
], - "toolType": "openapi"
}
], - "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
], - "type": "agent",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "warnings": [
- "additionalConfigurations: unknown key \"maxLlmCalls\" is not consumed by the agent runtime; check for typos"
]
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| 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. |
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. |
{- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "agentType": "standard",
- "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}{- "data": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "agentType": "standard",
- "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deployed": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "deployedBy": "jane.doe@example.com",
- "deployedTime": "2026-01-03T10:16:00.000Z",
- "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}, - "deploymentStatus": "deployed",
- "description": "Answers customer questions about order status and delivery dates.",
- "expiresTime": "2026-01-02T04:04:05.678Z",
- "id": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "inputModes": [
- "text"
], - "instanceName": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "isEphemeral": false,
- "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "skillConfigFields": {
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d": [
- {
- "coveredByAgent": true,
- "coveredBySkill": false,
- "default": "us-east-1",
- "description": "Region the order service runs in.",
- "fieldType": "string",
- "key": "region",
- "required": true,
- "secret": false,
- "toolName": "lookup_order"
}
]
}, - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "sourceComponentKind": "agent",
- "sourceComponentName": "Order support agent",
- "sourceSessionId": "0190f5e8-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "syncStatus": "in_sync",
- "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolRegistrations": [
- {
- "connectorId": "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e",
- "error": "Some of this entry's tools were not registered. The agent's log has the cause.",
- "name": "orders_api",
- "status": "ready",
- "toolCount": 3,
- "toolNames": [
- "get_order",
- "list_orders",
- "update_order"
], - "toolType": "openapi"
}
], - "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
], - "type": "agent",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "warnings": [
- "additionalConfigurations: unknown key \"maxLlmCalls\" is not consumed by the agent runtime; check for typos"
]
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one agent with its deployment and runtime status. Secret values are redacted.
Token Permissions: [ agent_builder:*:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "agentType": "standard",
- "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deployed": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "deployedBy": "jane.doe@example.com",
- "deployedTime": "2026-01-03T10:16:00.000Z",
- "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}, - "deploymentStatus": "deployed",
- "description": "Answers customer questions about order status and delivery dates.",
- "expiresTime": "2026-01-02T04:04:05.678Z",
- "id": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "inputModes": [
- "text"
], - "instanceName": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "isEphemeral": false,
- "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "skillConfigFields": {
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d": [
- {
- "coveredByAgent": true,
- "coveredBySkill": false,
- "default": "us-east-1",
- "description": "Region the order service runs in.",
- "fieldType": "string",
- "key": "region",
- "required": true,
- "secret": false,
- "toolName": "lookup_order"
}
]
}, - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "sourceComponentKind": "agent",
- "sourceComponentName": "Order support agent",
- "sourceSessionId": "0190f5e8-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "syncStatus": "in_sync",
- "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolRegistrations": [
- {
- "connectorId": "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e",
- "error": "Some of this entry's tools were not registered. The agent's log has the cause.",
- "name": "orders_api",
- "status": "ready",
- "toolCount": 3,
- "toolNames": [
- "get_order",
- "list_orders",
- "update_order"
], - "toolType": "openapi"
}
], - "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
], - "type": "agent",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "warnings": [
- "additionalConfigurations: unknown key \"maxLlmCalls\" is not consumed by the agent runtime; check for typos"
]
}
}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.
| 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. |
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. |
{- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}{- "data": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "agentType": "standard",
- "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deployed": {
- "additionalConfigurations": {
- "injectCurrentTime": true,
- "maxLlmCallsPerTask": 20
}, - "connectorIds": [
- "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e"
], - "deployedBy": "jane.doe@example.com",
- "deployedTime": "2026-01-03T10:16:00.000Z",
- "description": "Answers customer questions about order status and delivery dates.",
- "inputModes": [
- "text"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
]
}, - "deploymentStatus": "deployed",
- "description": "Answers customer questions about order status and delivery dates.",
- "expiresTime": "2026-01-02T04:04:05.678Z",
- "id": "0190f5e4-8b2c-7c3e-9a1d-2f4b6c8d0e1f",
- "inputModes": [
- "text"
], - "instanceName": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "isEphemeral": false,
- "modelProvider": [
- "planning"
], - "name": "Order support agent",
- "outputModes": [
- "text"
], - "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "skillConfigFields": {
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d": [
- {
- "coveredByAgent": true,
- "coveredBySkill": false,
- "default": "us-east-1",
- "description": "Region the order service runs in.",
- "fieldType": "string",
- "key": "region",
- "required": true,
- "secret": false,
- "toolName": "lookup_order"
}
]
}, - "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "skillIds": [
- "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d"
], - "skillRefs": [
- "sam-docs"
], - "skills": [
- {
- "description": "Looks up an order and reports where it is.",
- "examples": [
- "Where is order 10023?"
], - "id": "track_order",
- "inputModes": [
- "text"
], - "name": "Track order",
- "optional": [
- "customer_email"
], - "outputModes": [
- "text"
], - "required": [
- "order_id"
], - "tags": [
- "orders",
- "shipping"
]
}
], - "sourceComponentKind": "agent",
- "sourceComponentName": "Order support agent",
- "sourceSessionId": "0190f5e8-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "syncStatus": "in_sync",
- "systemPrompt": "You help customers track their orders. Look up the order before you answer.",
- "toolRegistrations": [
- {
- "connectorId": "0190f5e7-5e6f-7b8c-9d0e-1f2a3b4c5d6e",
- "error": "Some of this entry's tools were not registered. The agent's log has the cause.",
- "name": "orders_api",
- "status": "ready",
- "toolCount": 3,
- "toolNames": [
- "get_order",
- "list_orders",
- "update_order"
], - "toolType": "openapi"
}
], - "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
], - "toolsetExcludedTools": {
- "builtin_web_request_tools": [
- "web_search_google"
]
}, - "toolsets": [
- "builtin_artifact_tools",
- "builtin_web_request_tools"
], - "type": "agent",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "warnings": [
- "additionalConfigurations: unknown key \"maxLlmCalls\" is not consumed by the agent runtime; check for typos"
]
}
}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.
| 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. |
The request body.
required | object Holds the toolset and skill settings to compare with the stored ones. Required. |
{- "values": {
- "skillConfigs": [
- {
- "configValues": {
- "lookup_order": {
- "api_token": "<REDACTED>",
- "region": "us-east-1"
}
}, - "skillId": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "skillName": "order-lookup"
}
], - "toolsetConfigs": [
- {
- "configValues": {
- "web_request": {
- "timeout_seconds": 30
}
}, - "networkBindings": {
- "base_url": "egress-default"
}, - "toolsetName": "builtin_web_request_tools",
- "volumeBindings": {
- "workspace": "data"
}
}
]
}
}{- "data": {
- "secrets": {
- "app_token": {
- "matches": false
}, - "bot_token": {
- "matches": true
}
}
}
}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.
| 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. |
{- "data": [
- {
- "agentCount": 2,
- "agentRegistrations": [
- {
- "agent": {
- "id": "7c2e4411-8aa0-4a55-9f0d-6b2a1e3c4d5f",
- "name": "fulfilment-agent"
}, - "error": "tool orders_create failed to register",
- "status": "ready",
- "toolCount": 7
}
], - "connectorSubtype": "openapi",
- "connectorType": "api",
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "The orders service used by the fulfilment agent",
- "hasResource": true,
- "id": "3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210",
- "name": "Orders API",
- "type": "connector",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "warnings": [
- "specification_url is not reachable from the platform"
]
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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 " |
| 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. |
{- "connectorSubtype": "openapi",
- "connectorType": "api",
- "description": "The orders service used by the fulfilment agent",
- "name": "Orders API",
}{- "data": {
- "agentCount": 2,
- "agentRegistrations": [
- {
- "agent": {
- "id": "7c2e4411-8aa0-4a55-9f0d-6b2a1e3c4d5f",
- "name": "fulfilment-agent"
}, - "error": "tool orders_create failed to register",
- "status": "ready",
- "toolCount": 7
}
], - "connectorSubtype": "openapi",
- "connectorType": "api",
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "The orders service used by the fulfilment agent",
- "hasResource": true,
- "id": "3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210",
- "name": "Orders API",
- "type": "connector",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "warnings": [
- "specification_url is not reachable from the platform"
]
}
}Deletes the connector and unbinds it from every agent and workflow, which then redeploy.
Token Permissions: [ connector:*:delete ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one connector with its agent registrations. Secret settings are redacted.
Token Permissions: [ connector:*:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "agentCount": 2,
- "agentRegistrations": [
- {
- "agent": {
- "id": "7c2e4411-8aa0-4a55-9f0d-6b2a1e3c4d5f",
- "name": "fulfilment-agent"
}, - "error": "tool orders_create failed to register",
- "status": "ready",
- "toolCount": 7
}
], - "connectorSubtype": "openapi",
- "connectorType": "api",
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "The orders service used by the fulfilment agent",
- "hasResource": true,
- "id": "3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210",
- "name": "Orders API",
- "type": "connector",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "warnings": [
- "specification_url is not reachable from the platform"
]
}
}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 "
Token Permissions: [ connector:*:update ] API keys can call this operation.
| id required | string <uuid> The UUID of the connector to update. |
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 " |
{- "connectorSubtype": "openapi",
- "connectorType": "api",
- "description": "The orders service used by the fulfilment agent",
- "name": "Orders API",
}{- "data": {
- "agentCount": 2,
- "agentRegistrations": [
- {
- "agent": {
- "id": "7c2e4411-8aa0-4a55-9f0d-6b2a1e3c4d5f",
- "name": "fulfilment-agent"
}, - "error": "tool orders_create failed to register",
- "status": "ready",
- "toolCount": 7
}
], - "connectorSubtype": "openapi",
- "connectorType": "api",
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "The orders service used by the fulfilment agent",
- "hasResource": true,
- "id": "3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210",
- "name": "Orders API",
- "type": "connector",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "warnings": [
- "specification_url is not reachable from the platform"
]
}
}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.
| id required | string <uuid> The resource's UUID. |
"string"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.
| id required | string <uuid> The UUID of the connector whose specification is being replaced. |
The request body.
| file required | string <binary> The specification file, sent as the multipart part named file. |
{- "data": {
- "agentCount": 2,
- "agentRegistrations": [
- {
- "agent": {
- "id": "7c2e4411-8aa0-4a55-9f0d-6b2a1e3c4d5f",
- "name": "fulfilment-agent"
}, - "error": "tool orders_create failed to register",
- "status": "ready",
- "toolCount": 7
}
], - "connectorSubtype": "openapi",
- "connectorType": "api",
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "The orders service used by the fulfilment agent",
- "hasResource": true,
- "id": "3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210",
- "name": "Orders API",
- "type": "connector",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "warnings": [
- "specification_url is not reachable from the platform"
]
}
}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.
| id required | string <uuid> Example: 3f1a9c7e-2b44-4f8a-9a1e-77c0d9e5b210 The UUID of the connector whose stored secrets are compared. |
The request body.
required | object Holds the settings to compare. Only secret settings are compared. The connector subtype sets the keys. |
{- "values": {
- "broker_password": "<REDACTED>"
}
}{- "data": {
- "secrets": {
- "app_token": {
- "matches": false
}, - "bot_token": {
- "matches": true
}
}
}
}Returns one page of deployment records, newest first, optionally only those of one entrypoint.
Token Permissions: [ deployment:_:read ] API keys can call this operation.
| 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. |
{- "data": [
- {
- "action": "deploy",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "entrypointId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190b2c5-3a7e-7d21-8f4b-6c2d9e1a5b37",
- "status": "failed",
- "type": "entrypointDeployment",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "action": "deploy",
- "entrypointId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90"
}{- "data": {
- "action": "deploy",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "entrypointId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190b2c5-3a7e-7d21-8f4b-6c2d9e1a5b37",
- "status": "failed",
- "type": "entrypointDeployment",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}Returns one deployment record, including why it failed when it did.
Token Permissions: [ deployment:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "action": "deploy",
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "entrypointId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190b2c5-3a7e-7d21-8f4b-6c2d9e1a5b37",
- "status": "failed",
- "type": "entrypointDeployment",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}Manage the entrypoints that connect people and systems to Agent Mesh, such as Slack, Teams, webhooks, and WhatsApp.
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.
| 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. |
{- "data": [
- {
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "deployed": {
- "deployedBy": "user@example.com",
- "deployedTime": "2022-03-14T15:01:34.000Z",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}, - "deploymentStatus": "deployed",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "Support Slack bot",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "slug": "support-slack-bot",
- "syncStatus": "in_sync",
- "type": "entrypoint",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}Creates an entrypoint without deploying it. Deploy it with POST /entrypointDeployments.
Token Permissions: [ entrypoint:_:create ] API keys can call this operation.
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. |
{- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "slug": "support-slack-bot",
- "values": {
- "app_token": "xapp-1-placeholder",
- "bot_token": "xoxb-0000000000-placeholder"
}
}{- "data": {
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "deployed": {
- "deployedBy": "user@example.com",
- "deployedTime": "2022-03-14T15:01:34.000Z",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}, - "deploymentStatus": "deployed",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "Support Slack bot",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "slug": "support-slack-bot",
- "syncStatus": "in_sync",
- "type": "entrypoint",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one entrypoint with its deployment and runtime status. Secret values are redacted.
Token Permissions: [ entrypoint:*:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "deployed": {
- "deployedBy": "user@example.com",
- "deployedTime": "2022-03-14T15:01:34.000Z",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}, - "deploymentStatus": "deployed",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "Support Slack bot",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "slug": "support-slack-bot",
- "syncStatus": "in_sync",
- "type": "entrypoint",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}
}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.
| id required | string <uuid> Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90 The UUID of the entrypoint to update. |
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
" |
{- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "slug": "support-slack-bot",
- "values": {
- "bot_token": "xoxb-0000000000-placeholder"
}
}{- "data": {
- "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "deployed": {
- "deployedBy": "user@example.com",
- "deployedTime": "2022-03-14T15:01:34.000Z",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "name": "Support Slack bot",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}, - "deploymentStatus": "deployed",
- "description": "Answers customer support questions in Slack.",
- "entrypointType": "slack",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "Support Slack bot",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "slug": "support-slack-bot",
- "syncStatus": "in_sync",
- "type": "entrypoint",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "app_token": "<REDACTED>",
- "bot_token": "<REDACTED>"
}
}
}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.
| id required | string <uuid> Example: 0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90 The UUID of the entrypoint whose stored secrets are compared. |
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. |
{- "values": {
- "app_token": "xapp-1-placeholder",
- "bot_token": "<REDACTED>"
}
}{- "data": {
- "secrets": {
- "app_token": {
- "matches": false
}, - "bot_token": {
- "matches": true
}
}
}
}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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Questions customers asked support last month.",
- "exampleCount": 25,
- "experimentCount": 2,
- "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "isDefault": false,
- "name": "Support tickets",
- "type": "dataset",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "description": "Questions customers asked support last month.",
- "name": "Support tickets"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Questions customers asked support last month.",
- "exampleCount": 25,
- "experimentCount": 2,
- "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "isDefault": false,
- "name": "Support tickets",
- "type": "dataset",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one dataset with its example and experiment counts.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Questions customers asked support last month.",
- "exampleCount": 25,
- "experimentCount": 2,
- "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "isDefault": false,
- "name": "Support tickets",
- "type": "dataset",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The UUID of the dataset to update. |
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. |
{- "description": "Questions customers asked support in April.",
- "name": "Support tickets, April"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Questions customers asked support last month.",
- "exampleCount": 25,
- "experimentCount": 2,
- "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "isDefault": false,
- "name": "Support tickets",
- "type": "dataset",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "data": [
- {
- "choiceScores": {
- "irrelevant": 0,
- "partly": 0.5,
- "relevant": 1
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Judges whether the answer addresses the question.",
- "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "evaluatorType": "llm_judge",
- "experimentCount": 3,
- "heuristicType": "valid_json",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "minConfidence": 0.7,
- "model": "general",
- "name": "Answer relevance",
- "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer relevant?",
- "question": {
- "criteria": [
- {
- "key": "relevant"
}, - {
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response",
- "expected_response"
], - "scoring": "chosen",
- "type": "evaluator",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| 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. |
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: |
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. |
{- "choiceScores": {
- "irrelevant": 0,
- "partly": 0.5,
- "relevant": 1
}, - "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": {
- "criteria": [
- {
- "key": "relevant"
}, - {
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response",
- "expected_response"
], - "scoring": "chosen"
}{- "data": {
- "choiceScores": {
- "irrelevant": 0,
- "partly": 0.5,
- "relevant": 1
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Judges whether the answer addresses the question.",
- "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "evaluatorType": "llm_judge",
- "experimentCount": 3,
- "heuristicType": "valid_json",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "minConfidence": 0.7,
- "model": "general",
- "name": "Answer relevance",
- "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer relevant?",
- "question": {
- "criteria": [
- {
- "key": "relevant"
}, - {
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response",
- "expected_response"
], - "scoring": "chosen",
- "type": "evaluator",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one evaluator with the number of experiments it is attached to.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "choiceScores": {
- "irrelevant": 0,
- "partly": 0.5,
- "relevant": 1
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Judges whether the answer addresses the question.",
- "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "evaluatorType": "llm_judge",
- "experimentCount": 3,
- "heuristicType": "valid_json",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "minConfidence": 0.7,
- "model": "general",
- "name": "Answer relevance",
- "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer relevant?",
- "question": {
- "criteria": [
- {
- "key": "relevant"
}, - {
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response",
- "expected_response"
], - "scoring": "chosen",
- "type": "evaluator",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The UUID of the evaluator to update. |
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. |
{- "choiceScores": {
- "irrelevant": 0,
- "relevant": 1
}, - "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": {
- "criteria": [
- {
- "description": null,
- "key": "relevant"
}, - {
- "description": null,
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response"
], - "scoring": "expected"
}{- "data": {
- "choiceScores": {
- "irrelevant": 0,
- "partly": 0.5,
- "relevant": 1
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Judges whether the answer addresses the question.",
- "escalateToEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "evaluatorType": "llm_judge",
- "experimentCount": 3,
- "heuristicType": "valid_json",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "minConfidence": 0.7,
- "model": "general",
- "name": "Answer relevance",
- "promptTemplate": "Question: {{ Prompt }} Answer: {{ Response }} Is the answer relevant?",
- "question": {
- "criteria": [
- {
- "key": "relevant"
}, - {
- "key": "irrelevant"
}
], - "instructions": "Is the answer relevant?",
- "type": "choice"
}, - "reads": [
- "prompt",
- "response",
- "expected_response"
], - "scoring": "chosen",
- "type": "evaluator",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
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.
| datasetId required | string <uuid> The UUID of the dataset. |
| 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. |
{- "data": [
- {
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "4",
- "id": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 2 + 2?",
- "sequenceNumber": 3,
- "type": "example",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| datasetId required | string <uuid> The UUID of the dataset to add the example to. |
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. |
{- "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "4",
- "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 2 + 2?",
- "sequenceNumber": 3
}{- "data": {
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "4",
- "id": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 2 + 2?",
- "sequenceNumber": 3,
- "type": "example",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}Deletes the example with its files and the run results recorded for it.
Token Permissions: [ evaluation:_:delete ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one example with the metadata of its input and expected files.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "4",
- "id": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 2 + 2?",
- "sequenceNumber": 3,
- "type": "example",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The UUID of the example to update. |
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. |
{- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "6",
- "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 3 + 3?",
- "sequenceNumber": 3
}{- "data": {
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedFacts": {
- "forbidden": [
- "escalated"
], - "required": [
- "O-1",
- "refund approved"
]
}, - "expectedPath": {
- "nodes": [
- {
- "expectation": "succeeded",
- "nodeId": "approve"
}, - {
- "expectation": "not_ran",
- "nodeId": "escalate"
}
], - "tools": [
- {
- "expectation": "called",
- "toolName": "issue_refund"
}
]
}, - "expectedResponse": "4",
- "id": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "policy.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "inputData": {
- "orderId": "O-5003",
- "rush": true
}, - "prompt": "What is 2 + 2?",
- "sequenceNumber": 3,
- "type": "example",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}Define experiments that run an agent against a dataset's examples and score its answers with evaluators.
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.
| 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. |
{- "data": [
- {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "datasetName": "Support tickets",
- "datasetUpdatedTime": "2022-03-14T15:01:34.000Z",
- "description": "Checks the support agent against last month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "isDefault": false,
- "latestRunStatus": "completed",
- "latestRunTime": "2022-03-14T15:01:34.000Z",
- "maxWorkers": 4,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, March",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "system:nightly-evals",
- "runsPerExample": 1,
- "targetAgent": "support_agent",
- "targetType": "agent",
- "targetWorkflow": "order_exception_handler",
- "type": "experiment",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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: |
| 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. |
{- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "description": "Checks the support agent against last month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "maxWorkers": 4,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, March",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "nightly-evals",
- "runsPerExample": 1,
- "targetAgent": "support_agent",
- "targetWorkflow": "order_exception_handler"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "datasetName": "Support tickets",
- "datasetUpdatedTime": "2022-03-14T15:01:34.000Z",
- "description": "Checks the support agent against last month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "isDefault": false,
- "latestRunStatus": "completed",
- "latestRunTime": "2022-03-14T15:01:34.000Z",
- "maxWorkers": 4,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, March",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "system:nightly-evals",
- "runsPerExample": 1,
- "targetAgent": "support_agent",
- "targetType": "agent",
- "targetWorkflow": "order_exception_handler",
- "type": "experiment",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one experiment with the status and start time of its latest run.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "datasetName": "Support tickets",
- "datasetUpdatedTime": "2022-03-14T15:01:34.000Z",
- "description": "Checks the support agent against last month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "isDefault": false,
- "latestRunStatus": "completed",
- "latestRunTime": "2022-03-14T15:01:34.000Z",
- "maxWorkers": 4,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, March",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "system:nightly-evals",
- "runsPerExample": 1,
- "targetAgent": "support_agent",
- "targetType": "agent",
- "targetWorkflow": "order_exception_handler",
- "type": "experiment",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The UUID of the experiment to update. |
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. |
{- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "description": "Checks the support agent against this month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "maxWorkers": 8,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, April",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "nightly-evals",
- "runsPerExample": 2,
- "targetAgent": "support_agent",
- "targetWorkflow": "order_exception_handler"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "datasetId": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "datasetName": "Support tickets",
- "datasetUpdatedTime": "2022-03-14T15:01:34.000Z",
- "description": "Checks the support agent against last month's tickets.",
- "evaluatorIds": [
- "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
], - "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "isDefault": false,
- "latestRunStatus": "completed",
- "latestRunTime": "2022-03-14T15:01:34.000Z",
- "maxWorkers": 4,
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f"
}
], - "name": "Support answers, March",
- "primaryEvaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "runAs": "system:nightly-evals",
- "runsPerExample": 1,
- "targetAgent": "support_agent",
- "targetType": "agent",
- "targetWorkflow": "order_exception_handler",
- "type": "experiment",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
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.
| runResultId required | string <uuid> The run result's UUID. |
{- "data": {
- "agentResponse": "2 + 2 is 4.",
- "durationSeconds": 3.2,
- "exampleId": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "messages": [
- {
- "capturedTime": "2022-03-14T15:01:34.000Z",
- "payload": {
- "id": "task-1",
- "jsonrpc": "2.0"
}, - "topic": "sam/a2a/v1/agent/status/support_agent"
}
], - "runId": "0190f5f1-4a2b-7c3d-8e9f-0a1b2c3d4e5f",
- "trialIndex": 0
}
}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.
| runResultId required | string <uuid> The run result's UUID. |
{- "data": {
- "events": [
- {
- "direction": "request",
- "event_type": "a2a_message",
- "task_id": "task-1"
}
]
}
}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.
| runId required | string <uuid> The run's UUID. |
| 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. |
{- "data": [
- {
- "agentResponse": "2 + 2 is 4.",
- "artifacts": [
- {
- "filename": "report.csv",
- "mimeType": "text/csv",
- "size": 2048,
- "version": 0
}
], - "cost": "0.0142000000",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "durationSeconds": 3.2,
- "errorMessage": "The agent did not answer before the deadline.",
- "exampleId": "0190f5e9-8a9b-7c0d-9e1f-2a3b4c5d6e7f",
- "expectedArtifact": {
- "filename": "report.csv",
- "mimeType": "text/csv",
- "size": 2048,
- "version": 0
}, - "expectedResponse": "4",
- "failureKind": "auth_required",
- "id": "0190f5f4-9d0e-7f1a-8b2c-3d4e5f6a7b8c",
- "inputArtifact": {
- "filename": "report.csv",
- "mimeType": "text/csv",
- "size": 2048,
- "version": 0
}, - "inputPrompt": "What is 2 + 2?",
- "resolvedModelName": "gpt-4o",
- "runId": "0190f5f1-4a2b-7c3d-8e9f-0a1b2c3d4e5f",
- "scores": [
- {
- "choice": "correct",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "details": {
- "answer": {
- "choice": "correct",
- "confidence": 0.93,
- "probabilities": [
- {
- "option": "correct",
- "probability": 0.93
}
], - "probability": 0.93,
- "score": 2,
- "scoringApplied": "chosen"
}, - "decidedBy": "decision",
- "durationMs": 850,
- "escalated": false,
- "escalationReason": "low_confidence",
- "model": "gpt-5-decisions-2026-09",
- "providerError": "rate_limited",
- "usage": {
- "decision": {
- "inputTokens": 1200,
- "outputTokens": 40
}, - "llmJudge": {
- "inputTokens": 1200,
- "outputTokens": 40
}
}
}, - "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "key": "0190f5f5-ae1f-7a2b-9c3d-4e5f6a7b8c9d",
- "passed": true,
- "reasoning": "The answer matches the expected response.",
- "score": 1
}
], - "targetAgent": "support_agent",
- "targetType": "workflow",
- "tokenBreakdown": {
- "byModel": [
- {
- "model": "claude-sonnet-5-5",
- "tokens": {
- "cachedInputTokens": 800,
- "inputTokens": 1200,
- "outputTokens": 150,
- "reasoningTokens": 40,
- "totalTokens": 1350
}
}
], - "byNode": [
- {
- "models": [
- "claude-sonnet-5-5"
], - "nodeId": "classify",
- "tokens": {
- "cachedInputTokens": 800,
- "inputTokens": 1200,
- "outputTokens": 150,
- "reasoningTokens": 40,
- "totalTokens": 1350
}
}
], - "incomplete": false,
- "traceId": "0190f5f4-9d0e-7f1a-8b2c-3d4e5f6a7b8c",
- "unattributed": {
- "cachedInputTokens": 800,
- "inputTokens": 1200,
- "outputTokens": 150,
- "reasoningTokens": 40,
- "totalTokens": 1350
}
}, - "tokenUsage": {
- "cachedInputTokens": 800,
- "inputTokens": 1200,
- "outputTokens": 150,
- "reasoningTokens": 40,
- "totalTokens": 1350
}, - "trialIndex": 0,
- "type": "runResult"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}Start an experiment, follow its runs, read each run's status and scores, and cancel a run.
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.
| 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. |
{- "data": {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "error": {
- "errorId": "0190f5f2-6c7d-7e8f-9a0b-1c2d3e4f5a6b",
- "message": "A run in this operation failed. Get the run by the error's errorId to see its status."
}, - "id": "0190f5f1-4a2b-7c3d-8e9f-0a1b2c3d4e5f",
- "operationType": "run",
- "resourceId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "status": "inProgress",
- "type": "operation"
}
}Returns one page of the experiment's runs, newest first.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| experimentId required | string <uuid> The UUID of the experiment whose runs to list. |
| 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. |
{- "data": [
- {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "configSnapshot": {
- "agent": {
- "agentType": "standard",
- "connectors": [
- {
- "connectorType": "openapi",
- "id": "0190f5e8-6b7c-7d8e-9f0a-1b2c3d4e5f6a",
- "name": "Support wiki",
- "subtype": "rest"
}
], - "description": "Answers customer support questions.",
- "inputModes": [
- "text"
], - "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "support_agent",
- "origin": "discovered",
- "outputModes": [
- "text"
], - "skills": [
- {
- "description": "Summarizes long text.",
- "id": "summarize",
- "name": "Summarize"
}
], - "systemPrompt": "You answer support questions politely.",
- "tools": [
- {
- "description": "Searches the web.",
- "key": "search_web",
- "name": "search_web"
}
], - "toolsets": [
- "web"
]
}, - "dataset": {
- "exampleCount": 10,
- "examples": [
- {
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedResponse": "Use the Forgot password link on the sign-in page.",
- "id": "0190f5e9-4d5e-7f6a-9b7c-8d9e0f1a2b3c",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "prompt": "How do I reset my password?",
- "sequenceNumber": 1
}
], - "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "name": "Support tickets"
}, - "experiment": {
- "description": "Checks the support agent against last month's tickets.",
- "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "resolvedModel": "gpt-4o-2024-08-06"
}
], - "name": "Support answers, March"
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "errorMessage": "Run exceeded maximum duration.",
- "evaluatorSnapshot": [
- {
- "choiceScores": {
- "fail": 0,
- "pass": 1
}, - "description": "Judges whether the answer addresses the question.",
- "evaluatorType": "llm_judge",
- "heuristicType": "exact_match",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "model": "general",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "Answer relevance",
- "promptTemplate": "Rate the answer: {{response}}",
- "resolvedModelName": "gpt-4o-2024-08-06"
}
], - "evaluatorStats": [
- {
- "escalated": 2,
- "escalatedPercent": 20,
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "judgeUsage": {
- "decision": {
- "inputTokens": 1200,
- "outputTokens": 40
}, - "llmJudge": {
- "inputTokens": 1200,
- "outputTokens": 40
}
}, - "meanConfidence": 0.91,
- "scored": 10,
- "withConfidence": 9
}
], - "experimentId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "id": "0190f5f3-7d8e-7f9a-8b0c-2d3e4f5a6b7c",
- "model": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "progressCurrent": 3,
- "progressTotal": 10,
- "runAs": "system:nightly-evals",
- "runGroupId": "0190f5f3-7d8e-7f9a-8b0c-1c2d3e4f5a6b",
- "runName": "Support answers, March",
- "source": "manual",
- "status": "completed",
- "summaryScores": [
- {
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "score": 0.85
}
], - "type": "run"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| experimentId required | string <uuid> The UUID of the experiment to run. |
The request body.
| runName | string Names the runs in reports. Defaults to the experiment's name. |
{- "runName": "Support answers, March"
}{- "data": {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "error": {
- "errorId": "0190f5f2-6c7d-7e8f-9a0b-1c2d3e4f5a6b",
- "message": "A run in this operation failed. Get the run by the error's errorId to see its status."
}, - "id": "0190f5f1-4a2b-7c3d-8e9f-0a1b2c3d4e5f",
- "operationType": "run",
- "resourceId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "status": "inProgress",
- "type": "operation"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "configOutdated": false,
- "createdTime": "2022-03-14T15:01:34.000Z",
- "experimentId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "id": "0190f5f3-7d8e-7f9a-8b0c-1c2d3e4f5a6b",
- "progressCurrent": 6,
- "progressTotal": 20,
- "runName": "Support answers, March",
- "runs": [
- {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "configSnapshot": {
- "agent": {
- "agentType": "standard",
- "connectors": [
- {
- "connectorType": "openapi",
- "id": "0190f5e8-6b7c-7d8e-9f0a-1b2c3d4e5f6a",
- "name": "Support wiki",
- "subtype": "rest"
}
], - "description": "Answers customer support questions.",
- "inputModes": [
- "text"
], - "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "support_agent",
- "origin": "discovered",
- "outputModes": [
- "text"
], - "skills": [
- {
- "description": "Summarizes long text.",
- "id": "summarize",
- "name": "Summarize"
}
], - "systemPrompt": "You answer support questions politely.",
- "tools": [
- {
- "description": "Searches the web.",
- "key": "search_web",
- "name": "search_web"
}
], - "toolsets": [
- "web"
]
}, - "dataset": {
- "exampleCount": 10,
- "examples": [
- {
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedResponse": "Use the Forgot password link on the sign-in page.",
- "id": "0190f5e9-4d5e-7f6a-9b7c-8d9e0f1a2b3c",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "prompt": "How do I reset my password?",
- "sequenceNumber": 1
}
], - "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "name": "Support tickets"
}, - "experiment": {
- "description": "Checks the support agent against last month's tickets.",
- "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "resolvedModel": "gpt-4o-2024-08-06"
}
], - "name": "Support answers, March"
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "errorMessage": "Run exceeded maximum duration.",
- "evaluatorSnapshot": [
- {
- "choiceScores": {
- "fail": 0,
- "pass": 1
}, - "description": "Judges whether the answer addresses the question.",
- "evaluatorType": "llm_judge",
- "heuristicType": "exact_match",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "model": "general",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "Answer relevance",
- "promptTemplate": "Rate the answer: {{response}}",
- "resolvedModelName": "gpt-4o-2024-08-06"
}
], - "evaluatorStats": [
- {
- "escalated": 2,
- "escalatedPercent": 20,
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "judgeUsage": {
- "decision": {
- "inputTokens": 1200,
- "outputTokens": 40
}, - "llmJudge": {
- "inputTokens": 1200,
- "outputTokens": 40
}
}, - "meanConfidence": 0.91,
- "scored": 10,
- "withConfidence": 9
}
], - "experimentId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "id": "0190f5f3-7d8e-7f9a-8b0c-2d3e4f5a6b7c",
- "model": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "progressCurrent": 3,
- "progressTotal": 10,
- "runAs": "system:nightly-evals",
- "runGroupId": "0190f5f3-7d8e-7f9a-8b0c-1c2d3e4f5a6b",
- "runName": "Support answers, March",
- "source": "manual",
- "status": "completed",
- "summaryScores": [
- {
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "score": 0.85
}
], - "type": "run"
}
], - "status": "completed",
- "type": "runGroup"
}
}Returns one run with its status, progress, scores, and the configuration it started with.
Token Permissions: [ evaluation:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "configSnapshot": {
- "agent": {
- "agentType": "standard",
- "connectors": [
- {
- "connectorType": "openapi",
- "id": "0190f5e8-6b7c-7d8e-9f0a-1b2c3d4e5f6a",
- "name": "Support wiki",
- "subtype": "rest"
}
], - "description": "Answers customer support questions.",
- "inputModes": [
- "text"
], - "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "support_agent",
- "origin": "discovered",
- "outputModes": [
- "text"
], - "skills": [
- {
- "description": "Summarizes long text.",
- "id": "summarize",
- "name": "Summarize"
}
], - "systemPrompt": "You answer support questions politely.",
- "tools": [
- {
- "description": "Searches the web.",
- "key": "search_web",
- "name": "search_web"
}
], - "toolsets": [
- "web"
]
}, - "dataset": {
- "exampleCount": 10,
- "examples": [
- {
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedResponse": "Use the Forgot password link on the sign-in page.",
- "id": "0190f5e9-4d5e-7f6a-9b7c-8d9e0f1a2b3c",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "prompt": "How do I reset my password?",
- "sequenceNumber": 1
}
], - "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "name": "Support tickets"
}, - "experiment": {
- "description": "Checks the support agent against last month's tickets.",
- "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "resolvedModel": "gpt-4o-2024-08-06"
}
], - "name": "Support answers, March"
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "errorMessage": "Run exceeded maximum duration.",
- "evaluatorSnapshot": [
- {
- "choiceScores": {
- "fail": 0,
- "pass": 1
}, - "description": "Judges whether the answer addresses the question.",
- "evaluatorType": "llm_judge",
- "heuristicType": "exact_match",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "model": "general",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "Answer relevance",
- "promptTemplate": "Rate the answer: {{response}}",
- "resolvedModelName": "gpt-4o-2024-08-06"
}
], - "evaluatorStats": [
- {
- "escalated": 2,
- "escalatedPercent": 20,
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "judgeUsage": {
- "decision": {
- "inputTokens": 1200,
- "outputTokens": 40
}, - "llmJudge": {
- "inputTokens": 1200,
- "outputTokens": 40
}
}, - "meanConfidence": 0.91,
- "scored": 10,
- "withConfidence": 9
}
], - "experimentId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "id": "0190f5f3-7d8e-7f9a-8b0c-2d3e4f5a6b7c",
- "model": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "progressCurrent": 3,
- "progressTotal": 10,
- "runAs": "system:nightly-evals",
- "runGroupId": "0190f5f3-7d8e-7f9a-8b0c-1c2d3e4f5a6b",
- "runName": "Support answers, March",
- "source": "manual",
- "status": "completed",
- "summaryScores": [
- {
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "score": 0.85
}
], - "type": "run"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "completedTime": "2022-03-14T15:01:34.000Z",
- "configSnapshot": {
- "agent": {
- "agentType": "standard",
- "connectors": [
- {
- "connectorType": "openapi",
- "id": "0190f5e8-6b7c-7d8e-9f0a-1b2c3d4e5f6a",
- "name": "Support wiki",
- "subtype": "rest"
}
], - "description": "Answers customer support questions.",
- "inputModes": [
- "text"
], - "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "support_agent",
- "origin": "discovered",
- "outputModes": [
- "text"
], - "skills": [
- {
- "description": "Summarizes long text.",
- "id": "summarize",
- "name": "Summarize"
}
], - "systemPrompt": "You answer support questions politely.",
- "tools": [
- {
- "description": "Searches the web.",
- "key": "search_web",
- "name": "search_web"
}
], - "toolsets": [
- "web"
]
}, - "dataset": {
- "exampleCount": 10,
- "examples": [
- {
- "expectedArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "expectedResponse": "Use the Forgot password link on the sign-in page.",
- "id": "0190f5e9-4d5e-7f6a-9b7c-8d9e0f1a2b3c",
- "inputArtifact": {
- "contentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
- "filename": "ticket.pdf",
- "mimeType": "application/pdf",
- "size": 20480,
- "version": 0
}, - "prompt": "How do I reset my password?",
- "sequenceNumber": 1
}
], - "id": "0190f5e9-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
- "name": "Support tickets"
}, - "experiment": {
- "description": "Checks the support agent against last month's tickets.",
- "id": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "models": [
- {
- "alias": "general",
- "model": "gpt-4o",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "modelConfigId": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "resolvedModel": "gpt-4o-2024-08-06"
}
], - "name": "Support answers, March"
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "errorMessage": "Run exceeded maximum duration.",
- "evaluatorSnapshot": [
- {
- "choiceScores": {
- "fail": 0,
- "pass": 1
}, - "description": "Judges whether the answer addresses the question.",
- "evaluatorType": "llm_judge",
- "heuristicType": "exact_match",
- "id": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "isDefault": false,
- "model": "general",
- "modelConfig": {
- "alias": "general",
- "description": "General-purpose model.",
- "id": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "provider": "openai"
}, - "name": "Answer relevance",
- "promptTemplate": "Rate the answer: {{response}}",
- "resolvedModelName": "gpt-4o-2024-08-06"
}
], - "evaluatorStats": [
- {
- "escalated": 2,
- "escalatedPercent": 20,
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "judgeUsage": {
- "decision": {
- "inputTokens": 1200,
- "outputTokens": 40
}, - "llmJudge": {
- "inputTokens": 1200,
- "outputTokens": 40
}
}, - "meanConfidence": 0.91,
- "scored": 10,
- "withConfidence": 9
}
], - "experimentId": "0190f5ee-1d2e-7f3a-9b4c-5d6e7f8a9b0c",
- "id": "0190f5f3-7d8e-7f9a-8b0c-2d3e4f5a6b7c",
- "model": "0190f5e7-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
- "progressCurrent": 3,
- "progressTotal": 10,
- "runAs": "system:nightly-evals",
- "runGroupId": "0190f5f3-7d8e-7f9a-8b0c-1c2d3e4f5a6b",
- "runName": "Support answers, March",
- "source": "manual",
- "status": "completed",
- "summaryScores": [
- {
- "evaluatorId": "0190f5ea-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "score": 0.85
}
], - "type": "run"
}
}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.
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.
| 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. |
{- "data": [
- {
- "alias": "support-chat",
- "authConfig": {
- "api_key": "<REDACTED>",
- "type": "apikey"
}, - "authType": "apikey",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Fast model for support replies",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "cacheRead": "0.25",
- "cacheWrite": "3.125",
- "input": "2.5",
- "output": "10"
}, - "provider": "openai",
- "type": "model",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| 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. |
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 | |
| 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. |
{- "alias": "support-chat",
- "authConfig": {
- "api_key": "<your provider key>",
- "type": "apikey"
}, - "authType": "apikey",
- "description": "Fast model for support replies",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "cacheRead": "0.25",
- "cacheWrite": "3.125",
- "input": "2.5",
- "output": "10"
}, - "provider": "openai"
}{- "data": {
- "alias": "support-chat",
- "authConfig": {
- "api_key": "<REDACTED>",
- "type": "apikey"
}, - "authType": "apikey",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Fast model for support replies",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "cacheRead": "0.25",
- "cacheWrite": "3.125",
- "input": "2.5",
- "output": "10"
}, - "provider": "openai",
- "type": "model",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "alias": "support-chat",
- "authConfig": {
- "api_key": "<REDACTED>",
- "type": "apikey"
}, - "authType": "apikey",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Fast model for support replies",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "cacheRead": "0.25",
- "cacheWrite": "3.125",
- "input": "2.5",
- "output": "10"
}, - "provider": "openai",
- "type": "model",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}Changes the fields the body includes. A secret sent as
Token Permissions: [ model_config:*:update ] API keys can call this operation.
| id required | string <uuid> The UUID of the model to update. |
| 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. |
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 | |
| 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. |
{- "alias": "support-chat",
- "authConfig": {
- "api_key": "<your provider key>"
}, - "authType": "apikey",
- "description": "Fast model for support replies",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "input": "2.5",
- "output": "10"
}, - "provider": "openai"
}{- "data": {
- "alias": "support-chat",
- "authConfig": {
- "api_key": "<REDACTED>",
- "type": "apikey"
}, - "authType": "apikey",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Fast model for support replies",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "maxInputTokens": 128000,
- "modelName": "gpt-4o",
- "modelParams": {
- "temperature": 0.2
}, - "modelType": "chat",
- "pricing": {
- "cacheRead": "0.25",
- "cacheWrite": "3.125",
- "input": "2.5",
- "output": "10"
}, - "provider": "openai",
- "type": "model",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| id required | string <uuid> The UUID of the model whose dependents to list. |
| 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. |
{- "data": [
- {
- "dependentType": "agent",
- "deploymentStatus": "deployed",
- "key": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "mayStillRun": true,
- "name": "Support agent",
- "type": "modelDependent"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
| id required | string <uuid> Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a The UUID of the model whose stored secrets are compared. |
The request body.
required | object Holds the credential fields to compare. Only secret fields are compared. The model's auth type sets the keys. |
{- "authConfig": {
- "api_key": "<REDACTED>"
}
}{- "data": {
- "secrets": {
- "api_key": {
- "matches": true
}
}
}
}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.
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}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.
{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "lookupKey": "email",
- "toolsetId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
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. |
{- "lookupKey": "upn",
- "toolsetId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}{- "data": {
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "lookupKey": "email",
- "toolsetId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
{- "data": {
- "apiVersion": "2026-11-04",
- "minClientVersion": "v2.340.2",
- "products": [
- {
- "key": "sam-gateway-go",
- "name": "Solace Agent Mesh",
- "version": "v2.455.1"
}
]
}
}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.
{- "data": {
- "appName": "Acme Assistant",
- "collectFeedback": true,
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "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.",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "welcomeMessage": "Ask me anything about your orders."
}
}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.
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. |
{- "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."
}{- "data": {
- "appName": "Acme Assistant",
- "collectFeedback": true,
- "createdBy": "jane.doe@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "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.",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "welcomeMessage": "Ask me anything about your orders."
}
}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.
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.
| 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. |
{- "data": [
- {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "assetCount": 1,
- "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d"
}, - "bundledTools": [
- {
- "artifactParams": {
- "report": {
- "filenameKey": null,
- "isList": false,
- "isOptional": true
}
}, - "configSchema": [
- {
- "key": "api_key",
- "secret": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "instructions": "Call this before quoting an order's status.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "toolName": "order-lookup__find_order"
}
], - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Look up and explain customer orders.",
- "discoveryStatus": "ready",
- "hasAssets": false,
- "hasReferences": true,
- "hasTools": true,
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "label": "SAM documentation",
- "name": "order-lookup",
- "origin": "custom",
- "referenceCount": 2,
- "resourceCount": 3,
- "tags": [
- "orders",
- "support"
], - "toolsets": [
- "order_tools"
], - "type": "skill",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "assetCount": 1,
- "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d"
}, - "bundledTools": [
- {
- "artifactParams": {
- "report": {
- "filenameKey": null,
- "isList": false,
- "isOptional": true
}
}, - "configSchema": [
- {
- "key": "api_key",
- "secret": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "instructions": "Call this before quoting an order's status.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "toolName": "order-lookup__find_order"
}
], - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Look up and explain customer orders.",
- "discoveryStatus": "ready",
- "hasAssets": false,
- "hasReferences": true,
- "hasTools": true,
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "label": "SAM documentation",
- "name": "order-lookup",
- "origin": "custom",
- "referenceCount": 2,
- "resourceCount": 3,
- "tags": [
- "orders",
- "support"
], - "toolsets": [
- "order_tools"
], - "type": "skill",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one skill, by its UUID or, for a built-in skill, its name.
Token Permissions: [ skill:*:read ] API keys can call this operation.
| 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. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "assetCount": 1,
- "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d"
}, - "bundledTools": [
- {
- "artifactParams": {
- "report": {
- "filenameKey": null,
- "isList": false,
- "isOptional": true
}
}, - "configSchema": [
- {
- "key": "api_key",
- "secret": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "instructions": "Call this before quoting an order's status.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "toolName": "order-lookup__find_order"
}
], - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Look up and explain customer orders.",
- "discoveryStatus": "ready",
- "hasAssets": false,
- "hasReferences": true,
- "hasTools": true,
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "label": "SAM documentation",
- "name": "order-lookup",
- "origin": "custom",
- "referenceCount": 2,
- "resourceCount": 3,
- "tags": [
- "orders",
- "support"
], - "toolsets": [
- "order_tools"
], - "type": "skill",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
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. |
{- "description": "Look up and explain customer orders.",
- "name": "order-lookup"
}{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "assetCount": 1,
- "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d"
}, - "bundledTools": [
- {
- "artifactParams": {
- "report": {
- "filenameKey": null,
- "isList": false,
- "isOptional": true
}
}, - "configSchema": [
- {
- "key": "api_key",
- "secret": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "instructions": "Call this before quoting an order's status.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "toolName": "order-lookup__find_order"
}
], - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Look up and explain customer orders.",
- "discoveryStatus": "ready",
- "hasAssets": false,
- "hasReferences": true,
- "hasTools": true,
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "label": "SAM documentation",
- "name": "order-lookup",
- "origin": "custom",
- "referenceCount": 2,
- "resourceCount": 3,
- "tags": [
- "orders",
- "support"
], - "toolsets": [
- "order_tools"
], - "type": "skill",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}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.
| 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. |
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. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "assetCount": 1,
- "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d"
}, - "bundledTools": [
- {
- "artifactParams": {
- "report": {
- "filenameKey": null,
- "isList": false,
- "isOptional": true
}
}, - "configSchema": [
- {
- "key": "api_key",
- "secret": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "instructions": "Call this before quoting an order's status.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "toolName": "order-lookup__find_order"
}
], - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "description": "Look up and explain customer orders.",
- "discoveryStatus": "ready",
- "hasAssets": false,
- "hasReferences": true,
- "hasTools": true,
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "label": "SAM documentation",
- "name": "order-lookup",
- "origin": "custom",
- "referenceCount": 2,
- "resourceCount": 3,
- "tags": [
- "orders",
- "support"
], - "toolsets": [
- "order_tools"
], - "type": "skill",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "data": {
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "find_order": {
- "api_key": "<REDACTED>",
- "region": "us-east-1"
}
}
}
}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.
{- "data": {
- "arch": "amd64",
- "os": "linux",
- "pythonVersion": "3.12",
- "source": "str_init"
}
}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.
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. |
{- "filename": "order_tools.zip",
- "toolsetId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "totalSize": 9437184
}{- "data": {
- "chunkSize": 4194304,
- "createdTime": "2022-03-14T15:01:34.000Z",
- "expiresTime": "2022-03-14T15:01:34.000Z",
- "filename": "order_tools.zip",
- "id": "0190c7d8-4e2b-7f6a-9b1c-5d3e7f9a1b2c",
- "receivedBytes": 4194304,
- "receivedChunks": [
- 0
], - "toolsetId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "totalSize": 9437184,
- "type": "toolsetUpload"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "chunkSize": 4194304,
- "createdTime": "2022-03-14T15:01:34.000Z",
- "expiresTime": "2022-03-14T15:01:34.000Z",
- "filename": "order_tools.zip",
- "id": "0190c7d8-4e2b-7f6a-9b1c-5d3e7f9a1b2c",
- "receivedBytes": 4194304,
- "receivedChunks": [
- 0
], - "toolsetId": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "totalSize": 9437184,
- "type": "toolsetUpload"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
The bytes, sent as the request body.
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}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.
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.
| 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. |
{- "data": [
- {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "description": "Look up and update customer orders.",
- "name": "order_tools"
}{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one toolset, by its UUID or, for a built-in toolset, its id.
Token Permissions: [ toolset:*:read ] API keys can call this operation.
| 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. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
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. |
{- "description": "Look up and update customer orders.",
- "name": "order_tools"
}{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}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.
| 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. |
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. |
{- "data": {
- "agents": [
- {
- "description": "Answers customer questions.",
- "id": "0190f5e6-3c4d-7a5b-8c6d-9e0f1a2b3c4d",
- "name": "Support agent"
}
], - "aliases": [
- "web_tools"
], - "bundle": {
- "contentHash": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d",
- "filename": "order_tools.zip",
- "sizeBytes": 48213
}, - "capabilities": {
- "profileProvider": true
}, - "configSummary": {
- "requiredCoveredByDefaults": [
- "region"
], - "requiredFields": [
- "region",
- "api_key"
], - "requiresAgentConfig": true
}, - "createdBy": "user@example.com",
- "createdTime": "2022-03-14T15:01:34.000Z",
- "default": false,
- "description": "Look up and update customer orders.",
- "discoveryErrors": [ ],
- "discoveryStatus": "ready",
- "id": "0190b2c4-6f1a-7c3e-9d52-3a1f5b7e8c90",
- "name": "order_tools",
- "origin": "custom",
- "runtime": "python",
- "tools": [
- {
- "configSchema": [
- {
- "key": "region",
- "required": true,
- "type": "string"
}
], - "description": "Find an order by its number.",
- "parameters": {
- "properties": {
- "orderNumber": {
- "type": "string"
}
}, - "type": "object"
}, - "sandboxProfile": "default",
- "timeoutSeconds": 30,
- "toolName": "lookup_order"
}
], - "type": "toolset",
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z"
}
}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.
| 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. |
{- "data": {
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "lookup_order": {
- "api_key": "<REDACTED>",
- "region": "us-east-1"
}
}
}
}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.
| 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. |
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 " |
{- "values": {
- "lookup_order": {
- "region": "eu-west-1"
}
}
}{- "data": {
- "updatedBy": "user@example.com",
- "updatedTime": "2022-03-14T15:01:34.000Z",
- "values": {
- "lookup_order": {
- "api_key": "<REDACTED>",
- "region": "us-east-1"
}
}
}
}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.
| 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. |
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. |
{- "values": {
- "api_key": "<REDACTED>"
}
}{- "data": {
- "secrets": {
- "app_token": {
- "matches": false
}, - "bot_token": {
- "matches": true
}
}
}
}Returns one page of workflow deployments, failed ones included.
Token Permissions: [ deployment:_:read ] API keys can call this operation.
| 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. |
{- "data": [
- {
- "action": "deploy",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5eb-4d5e-7f6a-8b7c-9d0e1f2a3b4c",
- "status": "success",
- "type": "workflowDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "workflowId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "action": "deploy",
- "deploymentId": "0190f5eb-1e2f-7a3b-9c4d-5e6f7a8b9c0d",
- "testMode": false,
- "workflowId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}{- "data": {
- "action": "deploy",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5eb-4d5e-7f6a-8b7c-9d0e1f2a3b4c",
- "status": "success",
- "type": "workflowDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "workflowId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}
}Returns one deployment of a workflow, with why it failed when it did.
Token Permissions: [ deployment:_:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "action": "deploy",
- "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "failure": {
- "errorId": "0190b2c5-3a7f-7a10-b2c4-5d6e7f809a1b",
- "message": "The entrypoint runtime did not complete the change. Try again, and contact your administrator with the errorId if it fails again.",
- "reason": "runtime_error"
}, - "id": "0190f5eb-4d5e-7f6a-8b7c-9d0e1f2a3b4c",
- "status": "success",
- "type": "workflowDeployment",
- "updatedTime": "2026-01-03T10:15:30.000Z",
- "workflowId": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a"
}
}Returns one page of workflows with their deployment and runtime status.
Token Permissions: [ workflow_builder:*:read ] API keys can call this operation.
| 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. |
{- "data": [
- {
- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deploymentStatus": "deployed",
- "description": "Routes each new order to the team that fulfils it.",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "name": "Order triage",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "type": "workflow",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
], - "meta": {
- "pagination": {
- "count": 42,
- "nextPage": 2,
- "pageNumber": 1,
- "pageSize": 20,
- "totalPages": 3
}
}
}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.
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. |
{- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "description": "Routes each new order to the team that fulfils it.",
- "name": "Order triage"
}{- "data": {
- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deploymentStatus": "deployed",
- "description": "Routes each new order to the team that fulfils it.",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "name": "Order triage",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "type": "workflow",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> The resource's UUID. |
{- "errorId": "6f1b8c1e-2c7a-4d0e-9a53-1d7f4c2b9e10",
- "message": "Request validation failed",
- "validationDetails": {
- "name": [
- "must not be empty"
]
}
}Returns one workflow with its deployment and runtime status.
Token Permissions: [ workflow_builder:*:read ] API keys can call this operation.
| id required | string <uuid> The resource's UUID. |
{- "data": {
- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deploymentStatus": "deployed",
- "description": "Routes each new order to the team that fulfils it.",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "name": "Order triage",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "type": "workflow",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}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.
| id required | string <uuid> Example: 0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a The UUID of the workflow to replace. |
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. |
{- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "description": "Routes each new order to the team that fulfils it.",
- "name": "Order triage"
}{- "data": {
- "appConfig": {
- "agent_type": "workflow",
- "workflow": {
- "nodes": [
- {
- "agent_name": "agent_0190f5e4_8b2c_7c3e_9a1d_2f4b6c8d0e1f",
- "id": "start",
- "name": "start",
- "type": "agent"
}
], - "output_mapping": {
- "result": "{{start.output}}"
}
}
}, - "createdBy": "jane.doe@example.com",
- "createdTime": "2026-01-02T03:04:05.678Z",
- "deploymentStatus": "deployed",
- "description": "Routes each new order to the team that fulfils it.",
- "id": "0190f5ea-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
- "name": "Order triage",
- "runtimeStatus": {
- "problems": [
- {
- "detail": "The entrypoint is unable to receive inbound webhooks. Retrying automatically.",
- "key": "ingress",
- "severity": "degraded",
- "sinceTime": "2026-01-02T03:04:05.678Z"
}
], - "status": "degraded"
}, - "type": "workflow",
- "updatedBy": "jane.doe@example.com",
- "updatedTime": "2026-01-03T10:15:30.000Z"
}
}