---
title: "AI Agents"
url: "https://developers.bynder.com/apis/agents/versions/f5aecf98-613e-4ae8-b26a-ec2cdf804b2c"
---

# AI Agents

OpenAPI specification document.

````json
{"openapi":"3.0.3","info":{"title":"AI Agents","description":"Public entry point for the AI Agents domain. Routes inbound requests to the backend service that owns each operation and applies cross-cutting concerns (authentication, rate limiting, observability) once, at the gateway, rather than per backend service.","version":"1.0","x-bynder-visibility":"mixed","x-bynder-domain":"agents","x-bynder-repo":"agents-api-gateway-svc"},"servers":[{"url":"https://{your-bynder-domain}/"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Agents","description":"Create, list, update, and delete agent definitions."},{"name":"Previews","description":"Try an agent's prompt, capability, and properties against a single asset before saving it as an agent."},{"name":"Executions","description":"Run agents and query the resulting agent and asset executions status."},{"name":"Enrichment","description":"Review the metadata suggestions produced by the Enrichment agent for the assets of an agent execution."}],"paths":{"/api/1/agent/agents":{"x-bynder-visibility":"public","get":{"tags":["Agents"],"summary":"List agents","operationId":"listAgents","description":"Lists agents definitions using UUID-cursor pagination. `start` (forward, exclusive of the cursor row) and `before` (backward, inclusive) are mutually exclusive — sending both is a `400` with `{\"pagination\": \"only one of 'before' or 'start' is allowed, not both\"}`.","parameters":[{"name":"start","in":"query","description":"Forward cursor, exclusive of the cursor row.","schema":{"type":"string","format":"uuid"}},{"name":"before","in":"query","description":"Backward cursor, inclusive of the cursor row.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","format":"int32","default":20,"minimum":1,"maximum":100}},{"name":"sort","in":"query","schema":{"type":"string","default":"-createdAt"}},{"name":"searchTerm","in":"query","schema":{"type":"string"}},{"name":"capabilities","in":"query","schema":{"type":"array","items":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]}}},{"name":"statuses","in":"query","schema":{"type":"array","items":{"type":"string","enum":["ACTIVE","INACTIVE","DRAFT"]}}},{"name":"autoApply","in":"query","schema":{"type":"array","items":{"type":"boolean"}}},{"name":"agentIds","in":"query","schema":{"type":"array","items":{"type":"string","format":"uuid"}}}],"responses":{"200":{"description":"Cursor-paginated list of agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedAgents"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Agents"],"summary":"Create agent","operationId":"createAgent","description":"Creates a new agent with the given name, prompt, and capabilities.\nCapabilities are set at creation time and cannot be changed\nafterwards.\n\n### Prompt and agent properties guide.\n\n> For complex agent configuration we recommend using the Manage AI Agents section of the portal and if require get it as base for any custom implementation.\n\n`prompt` and `agentProperties` depend on the agent's capability. `agentProperties` is an object keyed by capability name, for example `{\"ENRICHMENT_AGENT\": {}}`. It must contain at least one capability key; send the key for each capability in `capabilities`, even when it is empty. Unknown properties are rejected at every level. A capability can only be used if it is enabled for the account.\n\nAll IDs (metaproperties, options, assets) must be valid UUIDs (version 4).\n\nResponses can include a read-only `targetFields` list inside `agentProperties`. The server fills it in from the prompt or from `targetMetapropertyId`; do not send it.\n\n#### ENRICHMENT_AGENT\n\n* `prompt.text`: free text. Use `${...}` placeholders to name the fields the agent reads or suggests. Placeholders are case-sensitive.\n  * `${title}`: the asset title.\n  * `${description}`: the asset description.\n  * `${tags}`: the asset tags.\n  * `${metaproperty:<metaproperty_id>}`: a metaproperty, identified by its ID. The ID must be an existing metaproperty of the account.\n  * `${asset:<asset_id>}`: a reference asset.\n* `agentProperties`: no properties are accepted. Send `{\"ENRICHMENT_AGENT\": {}}`.\n\nExample:\n\n```json\n{\n  \"name\": \"Describe and tag assets\",\n  \"description\": \"Suggests a title, description, tags and metaproperty values\",\n  \"capabilities\": [\"ENRICHMENT_AGENT\"],\n  \"prompt\": {\n    \"text\": \"Write a ${title} of up to 60 characters, a ${description} of two sentences and relevant ${tags}. Store the image orientation (landscape, portrait or square) in ${metaproperty:a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a} and the main subject in ${metaproperty:7d2c4e90-3b1a-4c6f-9e58-0a1b2c3d4e5f}. Follow the style of ${asset:5b3e9a62-1c7d-4f08-8a4e-2d9c6f1b7e30}.\"\n  },\n  \"agentProperties\": { \"ENRICHMENT_AGENT\": {} }\n}\n```\n\n#### GOVERNANCE_AGENT\n\n> Only one Governance Agent type is allowed per account.\n\n* `prompt`: not used.\n* `agentProperties`: no properties are accepted. Send `{\"GOVERNANCE_AGENT\": {}}`.\n\nExample:\n\n```json\n{\n  \"name\": \"Governance\",\n  \"description\": \"Governance checks on assets\",\n  \"capabilities\": [\"GOVERNANCE_AGENT\"],\n  \"agentProperties\": { \"GOVERNANCE_AGENT\": {} }\n}\n```\n\n#### BRAND_COMPLIANCE_AGENT\n\n* `prompt.text`: a JSON array of rules, sent as a string. Each rule is `{\"id\", \"category\", \"text\"}`. Rule text can reference `${asset:<asset_id>}`.\n* `agentProperties.BRAND_COMPLIANCE_AGENT.targetMetapropertyId`: the ID of the metaproperty the compliance result is written to.\n\nExample:\n\n```json\n{\n  \"name\": \"Logo compliance\",\n  \"description\": \"Checks logo, colour and typography rules\",\n  \"capabilities\": [\"BRAND_COMPLIANCE_AGENT\"],\n  \"prompt\": {\n    \"text\": \"[{\\\"id\\\":\\\"LO-01\\\",\\\"category\\\":\\\"Logo\\\",\\\"text\\\":\\\"The logo must be blue\\\"},{\\\"id\\\":\\\"LO-02\\\",\\\"category\\\":\\\"Logo\\\",\\\"text\\\":\\\"The logo must match ${asset:5b3e9a62-1c7d-4f08-8a4e-2d9c6f1b7e30}\\\"},{\\\"id\\\":\\\"CO-01\\\",\\\"category\\\":\\\"Colors\\\",\\\"text\\\":\\\"The color red must not be present\\\"},{\\\"id\\\":\\\"TY-01\\\",\\\"category\\\":\\\"Typography\\\",\\\"text\\\":\\\"Headlines must be in sentence case\\\"}]\"\n  },\n  \"agentProperties\": {\n    \"BRAND_COMPLIANCE_AGENT\": {\n      \"targetMetapropertyId\": \"a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a\"\n    }\n  }\n}\n```\n\n#### TRANSFORMATION_AGENT\n\n* `prompt`: not used. The text instructions go in `editWithPromptProperties.prompt` and in the background prompt (see below).\n* `agentProperties.TRANSFORMATION_AGENT`: `removeBackground`, `replaceBackground`, `resize`, `customNaming` and `editWithPrompt` are required booleans. Each flag turns a feature on, and its optional `...Properties` object holds the settings:\n  * `removeBackgroundProperties`:\n    * `shadow`: `SOFT`, `HARD`, `FLOATING`, `AUTO_WITH_OVERRIDES`, or `null` for no shadow.\n    * `shadowOverrides`: only allowed when `shadow` is `AUTO_WITH_OVERRIDES`. All fields are optional:\n      * `subjectPose`: `flatlay` or `upright`.\n      * `softness`: a number from 0 to 1.\n      * `intensity`: a number from 0 to 1.\n      * `spread`: a number from 0 to 90.\n      * `direction`: `behind`, `behindLeft`, `left`, `frontLeft`, `front`, `frontRight`, `right` or `behindRight`.\n  * `replaceBackgroundProperties`: `type` is required (`COLOR`, `IMAGE` or `PROMPT`). Also send exactly one object, the one that matches `type`:\n    * `color`: `hexCode` is required (`#RRGGBB` or `#RGB`). `shadow` and `shadowOverrides` are optional and work as in `removeBackgroundProperties`.\n    * `image`: `assetId` is required (the asset used as the new background). `prompt` is optional.\n    * `prompt`: `prompt` is required (a text describing the new background).\n  * `resizeProperties`: `width` and `height`, as integers.\n  * `editWithPromptProperties`:\n    * `prompt`: required.\n    * `aspectRatio`: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` or `21:9`.\n    * `quality`: `auto`, `1K`, `2K` or `4K`.\n    * `referenceAssetIds`: a list of asset IDs used as references.\n  * `customNamingProperties`: `name`, the name to apply.\n  * `metaproperties`: `ids` (metaproperty IDs) and `copyEnabled`.\n  * `metapropertyValues`: a list of `{id, value}`, where `id` is the metaproperty ID. `value` has exactly one of:\n    * `optionIds`: a non-empty list of option IDs.\n    * `text`: a non-blank text, up to 2499 characters.\n    * `date`: a date as `YYYY-MM-DD`.\n\nExample:\n\n```json\n{\n  \"name\": \"Social media version\",\n  \"description\": \"Blue background, resized, with a flower added\",\n  \"capabilities\": [\"TRANSFORMATION_AGENT\"],\n  \"agentProperties\": {\n    \"TRANSFORMATION_AGENT\": {\n      \"removeBackground\": false,\n      \"replaceBackground\": true,\n      \"replaceBackgroundProperties\": {\n        \"type\": \"COLOR\",\n        \"color\": { \"hexCode\": \"#0097ff\", \"shadow\": \"SOFT\" }\n      },\n      \"resize\": true,\n      \"resizeProperties\": { \"width\": 1080, \"height\": 1920 },\n      \"editWithPrompt\": true,\n      \"editWithPromptProperties\": { \"prompt\": \"Add a flower\", \"aspectRatio\": \"9:16\" },\n      \"customNaming\": false,\n      \"metaproperties\": {\n        \"ids\": [\"a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a\"],\n        \"copyEnabled\": true\n      },\n      \"metapropertyValues\": [\n        {\n          \"id\": \"7d2c4e90-3b1a-4c6f-9e58-0a1b2c3d4e5f\",\n          \"value\": { \"optionIds\": [\"2e6a1c88-9f03-4d7b-8c15-b4a7e0d93f61\"] }\n        },\n        {\n          \"id\": \"c91e7f35-8a24-4b0d-a3f6-5e8d1b7c9a20\",\n          \"value\": { \"date\": \"2026-11-04\" }\n        }\n      ]\n    }\n  }\n}\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateRequest"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/agents/{id}":{"x-bynder-visibility":"public","get":{"tags":["Agents"],"summary":"Get agent","operationId":"getAgent","description":"Returns a single agent by id.","parameters":[{"$ref":"#/components/parameters/AgentId"}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}},"patch":{"tags":["Agents"],"summary":"Edit agent","operationId":"editAgent","description":"Partially updates an agent. Only the fields provided in the request body are changed; capabilities cannot be modified after creation. For the `prompt` and `agentProperties` configuration of each capability, see the description of `POST /api/1/agent/agents`.","parameters":[{"$ref":"#/components/parameters/AgentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdateRequest"}}}},"responses":{"200":{"description":"Updated agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Agents"],"summary":"Delete agent","operationId":"deleteAgent","description":"Deletes an agent by id.","parameters":[{"$ref":"#/components/parameters/AgentId"}],"responses":{"204":{"description":"Agent deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/executions":{"x-bynder-visibility":"public","get":{"tags":["Executions"],"summary":"List agent executions","operationId":"listAgentExecutions","description":"Returns a paginated list of agent executions, filtered by the query parameters below.","parameters":[{"name":"agentIds","in":"query","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"statuses","in":"query","schema":{"type":"array","items":{"type":"string","enum":["RUNNING","ACTION_REQUIRED","COMPLETED"]}}},{"name":"capabilities","in":"query","schema":{"type":"array","items":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]}}},{"name":"userIds","in":"query","description":"Filter to executions run by one of these users.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"automationRuleIds","in":"query","description":"Filter to executions run by one of these automation rules.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"ranByAutomationOnly","in":"query","description":"When true, returns only executions triggered by an automation rule.","schema":{"type":"boolean"}},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"workspaceBatchId","in":"query","description":"Returns only the executions started for this workspace upload batch.","schema":{"type":"string","format":"uuid"}},{"name":"assetId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"start","in":"query","description":"Cursor from the previous page's nextPage. Omit for the first page.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","schema":{"type":"string","default":"-modifiedAt"}}],"responses":{"200":{"description":"Paginated list of agent executions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedExecutions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Executions"],"summary":"Run agent","operationId":"runAgentExecution","description":"Runs one or more agents on assets. Send one item per agent, each with the asset list to process. The request is accepted as a whole: agents that could not be started are listed in `error` in the response, with the reason, and the ones that did start are listed in `success`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionRequest"}}}},"responses":{"202":{"description":"Execution(s) accepted for processing. The response lists the executions that were created, the requests that failed, and a summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionResult"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/executions/{id}":{"x-bynder-visibility":"public","get":{"tags":["Executions"],"summary":"Get agent execution","operationId":"getAgentExecution","description":"Returns a single agent execution by id.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"responses":{"200":{"description":"Agent execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Execution"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/executions/{id}/cancel":{"x-bynder-visibility":"public","post":{"tags":["Executions"],"summary":"Cancel agent execution","operationId":"cancelAgentExecution","description":"Cancels an agent execution that have not finished yet.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"responses":{"204":{"description":"Cancellation processed (or nothing to cancel)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/executions/{id}/asset-executions":{"x-bynder-visibility":"public","get":{"tags":["Executions"],"summary":"List asset executions for an agent execution","operationId":"listAssetExecutions","description":"Returns the per-asset executions belonging to an agent execution, paginated.","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"name":"statuses","in":"query","description":"Only return asset executions with these statuses.","schema":{"type":"array","items":{"type":"string","enum":["SCHEDULED","RUNNING","FAILED","COMPLETED","ACCEPTED","AUTO_APPLIED","DISCARDED","CANCELED","REVERTED"]}}},{"name":"start","in":"query","description":"Cursor from the previous page's nextPage. Omit for the first page.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","schema":{"type":"string","default":"-modifiedAt"}}],"responses":{"200":{"description":"Paginated list of asset executions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAssetExecutions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/executions/{id}/asset-executions/{assetExecutionId}":{"x-bynder-visibility":"public","get":{"tags":["Executions"],"summary":"Get a single asset execution","operationId":"getAssetExecution","description":"Returns a single asset execution belonging to an agent execution.","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/AssetExecutionId"}],"responses":{"200":{"description":"Asset execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetExecution"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/enrichment/executions/{id}/accept":{"x-bynder-visibility":"public","post":{"tags":["Enrichment"],"summary":"Accept enrichment agent results","operationId":"acceptEnrichmentAgentResults","description":"Accepts the agent-produced suggestions for one or more asset executions under an agent execution, applying them to the asset(s). Leaving assetExecutionIds empty accepts every asset execution under this agent execution that has suggestions.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSuggestionsRequest"}}}},"responses":{"202":{"description":"Accept command published; applied asynchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/enrichment/executions/{id}/discard":{"x-bynder-visibility":"public","post":{"tags":["Enrichment"],"summary":"Discard enrichment agent results","operationId":"discardEnrichmentAgentResults","description":"Discards the agent-produced suggestions for one or more asset executions under an agent execution, without applying them. Leaving assetExecutionIds empty discards every asset execution under this agent execution that has suggestions.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSuggestionsRequest"}}}},"responses":{"202":{"description":"Discard command published; applied asynchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/enrichment/executions/{id}/revert":{"x-bynder-visibility":"public","post":{"tags":["Enrichment"],"summary":"Undo an enrichment accept/discard decision","operationId":"revertEnrichmentAgentResults","description":"Reverts a previous accept or discard decision for one or more asset executions under an agent execution, restoring their suggestions to the pending state.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSuggestionsRequest"}}}},"responses":{"202":{"description":"Revert command published; applied asynchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}},"/api/1/agent/enrichment/executions/{id}/edit":{"x-bynder-visibility":"public","patch":{"tags":["Enrichment"],"summary":"Edit enrichment suggestion values","operationId":"editEnrichmentSuggestions","description":"Edits specific suggestion values under an agent execution before they are accepted. Suggestions that do not belong to this agent execution are reported in skippedIds.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditSuggestionsRequest"}}}},"responses":{"202":{"description":"Edit command published; applied asynchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}},"delete":{"tags":["Enrichment"],"summary":"Undo inline edits of enrichment suggestions","operationId":"undoEnrichmentSuggestionEdits","description":"Undoes earlier inline edits, restoring the given suggestions to their original values. Same resource as PATCH: PATCH applies an edit, DELETE removes it. Suggestions that do not belong to this agent execution are reported in skippedIds.","parameters":[{"$ref":"#/components/parameters/ExecutionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoEditSuggestionsRequest"}}}},"responses":{"202":{"description":"Undo-edit command published; applied asynchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AgentId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ExecutionId":{"name":"id","in":"path","required":true,"description":"Id of the agent execution","schema":{"type":"string","format":"uuid"}},"AssetExecutionId":{"name":"assetExecutionId","in":"path","required":true,"description":"Id of the asset execution, scoped to its parent agent execution","schema":{"type":"string","format":"uuid"}}},"responses":{"ValidationError":{"description":"The request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Caller lacks the required permission for this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Caller exceeded its configured request rate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Gateway or a downstream service failed to process the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"Agent":{"type":"object","description":"An agent.","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"description":{"type":"string"},"prompt":{"$ref":"#/components/schemas/Prompt"},"createdAt":{"type":"string","format":"date-time"},"modifiedAt":{"type":"string","format":"date-time"},"accountId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","DRAFT"]},"autoApply":{"type":"boolean"},"autoApplyUserId":{"type":"string","format":"uuid","nullable":true},"agents":{"type":"array","description":"The capabilities of the agent.","items":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]}},"agentProperties":{"type":"object","additionalProperties":true},"createdBy":{"type":"string","format":"uuid"}}},"AgentCreateRequest":{"type":"object","description":"The agent to create. `capabilities` defines what the agent can do and cannot be changed afterwards.","required":["name","description","capabilities","agentProperties"],"properties":{"autoApply":{"type":"boolean"},"name":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":130},"capabilities":{"type":"array","minItems":1,"items":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]}},"agentProperties":{"type":"object","additionalProperties":true},"prompt":{"$ref":"#/components/schemas/PromptInput"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","DRAFT"]}}},"AgentUpdateRequest":{"type":"object","description":"Request body for a partial update. All fields are optional. Capabilities cannot be changed after the agent is created.","properties":{"autoApply":{"type":"boolean"},"name":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":130},"status":{"type":"string","enum":["ACTIVE","INACTIVE","DRAFT"]},"prompt":{"$ref":"#/components/schemas/PromptInput"},"agentProperties":{"type":"object","additionalProperties":true}}},"CursorPaginatedAgents":{"type":"object","description":"A page of agents. `metadata.nextPage` and `metadata.prevPage` are query strings to add to the same request URL, or `null` when there is no such page.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"metadata":{"type":"object","properties":{"prevPage":{"type":"string","nullable":true},"nextPage":{"type":"string","nullable":true}}}}},"ExecutionFilterOptions":{"type":"object","required":["filterName","values"],"properties":{"filterName":{"type":"string","enum":["agent","ranBy"]},"values":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"Only present for the `ranBy` filter.","enum":["USER","AUTOMATION_RULE"]}}}}}},"PaginatedAgents":{"type":"object","description":"A page of agents.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"metadata":{"type":"object","properties":{"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"prevPage":{"type":"string","nullable":true},"nextPage":{"type":"string","nullable":true}}}}},"Prompt":{"type":"object","description":"An agent prompt.","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"text":{"type":"string"},"version":{"type":"integer","format":"int32","readOnly":true},"isActive":{"type":"boolean","readOnly":true},"createdAt":{"type":"string","format":"date-time"},"modifiedAt":{"type":"string","format":"date-time"}}},"PromptInput":{"type":"object","description":"The prompt to set on an agent when you create or edit it. Unlike the read-only `Prompt` in responses, `id` and `version` are optional here.","required":["text"],"properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","format":"int32"},"text":{"type":"string","maxLength":10000}}},"AgentPreview":{"type":"object","description":"An agent preview.","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"agentId":{"type":"string","format":"uuid","nullable":true},"promptId":{"type":"string","format":"uuid"},"promptText":{"type":"string"},"promptVersion":{"type":"integer","format":"int32"},"agentCapability":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]},"agentProperties":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}},"AgentPreviewCreateRequest":{"type":"object","description":"Request body for creating an agent preview, which lets you try a prompt, capability, and properties before saving an agent. To run an existing preview against an asset, use ExecutionPreviewRequest.","required":["promptText","agentCapability","agentProperties"],"properties":{"promptText":{"type":"string"},"agentCapability":{"type":"string","enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]},"agentProperties":{"type":"object","additionalProperties":true},"agentId":{"type":"string","format":"uuid"}}},"ExecutionRequest":{"type":"array","description":"An array of per-agent run requests, not a single object. Each item must include its own `agentId`.","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ExecutionRequestItem"}},"ExecutionRequestItem":{"type":"object","description":"A request to run one agent.","required":["agentId","assetIds"],"properties":{"agentId":{"type":"string","format":"uuid"},"assetIds":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"string","format":"uuid"}},"agentExecutionName":{"type":"string","maxLength":256},"workspaceBatchId":{"type":"string","format":"uuid","nullable":true}}},"ExecutionPreviewRequest":{"type":"object","description":"Runs an existing preview (see AgentPreviewCreateRequest) against a single asset. Note the singular `assetId`, unlike the plural `assetIds` in ExecutionRequestItem.","required":["previewId","assetId"],"properties":{"previewId":{"type":"string","format":"uuid"},"assetId":{"type":"string","format":"uuid"}}},"Execution":{"type":"object","description":"An agent execution.","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["RUNNING","ACTION_REQUIRED","COMPLETED"]},"agentId":{"type":"string","format":"uuid","nullable":true},"agentName":{"type":"string"},"assetCount":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"modifiedAt":{"type":"string","format":"date-time"},"assetStatusCounts":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Number of asset executions per status."},"ranBy":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["USER","AUTOMATION_RULE"]},"id":{"type":"string"},"name":{"type":"string"}},"description":"Who started the execution: a user or an automation rule."},"accountId":{"type":"string","format":"uuid"},"workspaceBatchId":{"type":"string","format":"uuid","nullable":true},"agentCapability":{"type":"string","nullable":true,"enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]}}},"PaginatedExecutions":{"type":"object","description":"A page of executions. `metadata.nextPage` is a query string to add to the same request URL, or `null` on the last page.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Execution"}},"metadata":{"type":"object","properties":{"nextPage":{"type":"string","nullable":true}}}}},"AssetExecution":{"type":"object","description":"The execution of an agent on a single asset, including capability-specific `results` (for example, suggestions for the enrichment capability).","properties":{"id":{"type":"string","format":"uuid"},"agentExecutionId":{"type":"string","format":"uuid"},"assetId":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The status of the asset execution.","enum":["SCHEDULED","RUNNING","FAILED","COMPLETED","ACCEPTED","AUTO_APPLIED","DISCARDED","CANCELED","REVERTED"]},"createdAt":{"type":"string","format":"date-time"},"results":{"type":"object","additionalProperties":true},"assetName":{"type":"string","nullable":true},"draft":{"type":"boolean"},"removed":{"type":"boolean"},"errorCode":{"type":"string","nullable":true},"agentType":{"type":"string","nullable":true,"enum":["ENRICHMENT_AGENT","TRANSFORMATION_AGENT","BRAND_COMPLIANCE_AGENT","GOVERNANCE_AGENT","PATH_GENERATOR_AGENT"]},"thumbnail":{"type":"object","nullable":true,"properties":{"small":{"type":"string"},"large":{"type":"string"}}}}},"PaginatedAssetExecutions":{"type":"object","description":"A page of asset executions. `metadata.nextPage` is a query string to add to the same request URL, or `null` on the last page.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AssetExecution"}},"metadata":{"type":"object","properties":{"nextPage":{"type":"string","nullable":true}}}}},"ReviewSuggestionsRequest":{"type":"object","description":"Accept/discard/revert request. The agent execution comes from the {id} path segment. Empty or absent assetExecutionIds acts on every asset execution under this agent execution that has suggestions.","properties":{"assetExecutionIds":{"type":"array","items":{"type":"string","format":"uuid"}}}},"EditSuggestionsRequest":{"type":"object","description":"Edit request. The agent execution comes from the {id} path segment.","required":["inlineChanges"],"properties":{"inlineChanges":{"type":"array","minItems":1,"items":{"type":"object","required":["suggestionId"],"properties":{"suggestionId":{"type":"string","format":"uuid"},"newValue":{"type":"string"}}}}}},"UndoEditSuggestionsRequest":{"type":"object","description":"Undo-edit request. The agent execution comes from the {id} path segment.","required":["suggestionIds"],"properties":{"suggestionIds":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid"}}}},"CommandAcceptedResponse":{"type":"object","properties":{"correlationId":{"type":"string","format":"uuid"},"skippedIds":{"type":"array","description":"Requested ids not owned by this account and so not processed. The rest of the request still went through.","items":{"type":"string","format":"uuid"}}}},"ExecutionResult":{"type":"object","properties":{"success":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"agentExecutionId":{"type":"string","format":"uuid"},"capabilities":{"type":"array","items":{"type":"string"}}}},"description":"The executions that were created."},"error":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string","nullable":true},"capabilities":{"type":"array","nullable":true,"items":{"type":"string"}},"errorType":{"type":"string"}}},"description":"The run requests that failed."},"executionSummary":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Counts of run requests by outcome."}},"description":"The outcome of a run request."}}}}
````