--- title: "Create agent" url: "https://developers.bynder.com/apis/agents/versions/f5aecf98-613e-4ae8-b26a-ec2cdf804b2c/operations/createAgent" --- > Full API specification: https://developers.bynder.com/apis/agents/versions/f5aecf98-613e-4ae8-b26a-ec2cdf804b2c.md # Create agent `POST` `/api/1/agent/agents` Operation ID: `createAgent` Creates a new agent with the given name, prompt, and capabilities. Capabilities are set at creation time and cannot be changed afterwards. ### Prompt and agent properties guide. > 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. `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. All IDs (metaproperties, options, assets) must be valid UUIDs (version 4). Responses can include a read-only `targetFields` list inside `agentProperties`. The server fills it in from the prompt or from `targetMetapropertyId`; do not send it. #### ENRICHMENT_AGENT * `prompt.text`: free text. Use `${...}` placeholders to name the fields the agent reads or suggests. Placeholders are case-sensitive. * `${title}`: the asset title. * `${description}`: the asset description. * `${tags}`: the asset tags. * `${metaproperty:}`: a metaproperty, identified by its ID. The ID must be an existing metaproperty of the account. * `${asset:}`: a reference asset. * `agentProperties`: no properties are accepted. Send `{"ENRICHMENT_AGENT": {}}`. Example: ```json { "name": "Describe and tag assets", "description": "Suggests a title, description, tags and metaproperty values", "capabilities": ["ENRICHMENT_AGENT"], "prompt": { "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}." }, "agentProperties": { "ENRICHMENT_AGENT": {} } } ``` #### GOVERNANCE_AGENT > Only one Governance Agent type is allowed per account. * `prompt`: not used. * `agentProperties`: no properties are accepted. Send `{"GOVERNANCE_AGENT": {}}`. Example: ```json { "name": "Governance", "description": "Governance checks on assets", "capabilities": ["GOVERNANCE_AGENT"], "agentProperties": { "GOVERNANCE_AGENT": {} } } ``` #### BRAND_COMPLIANCE_AGENT * `prompt.text`: a JSON array of rules, sent as a string. Each rule is `{"id", "category", "text"}`. Rule text can reference `${asset:}`. * `agentProperties.BRAND_COMPLIANCE_AGENT.targetMetapropertyId`: the ID of the metaproperty the compliance result is written to. Example: ```json { "name": "Logo compliance", "description": "Checks logo, colour and typography rules", "capabilities": ["BRAND_COMPLIANCE_AGENT"], "prompt": { "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\"}]" }, "agentProperties": { "BRAND_COMPLIANCE_AGENT": { "targetMetapropertyId": "a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a" } } } ``` #### TRANSFORMATION_AGENT * `prompt`: not used. The text instructions go in `editWithPromptProperties.prompt` and in the background prompt (see below). * `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: * `removeBackgroundProperties`: * `shadow`: `SOFT`, `HARD`, `FLOATING`, `AUTO_WITH_OVERRIDES`, or `null` for no shadow. * `shadowOverrides`: only allowed when `shadow` is `AUTO_WITH_OVERRIDES`. All fields are optional: * `subjectPose`: `flatlay` or `upright`. * `softness`: a number from 0 to 1. * `intensity`: a number from 0 to 1. * `spread`: a number from 0 to 90. * `direction`: `behind`, `behindLeft`, `left`, `frontLeft`, `front`, `frontRight`, `right` or `behindRight`. * `replaceBackgroundProperties`: `type` is required (`COLOR`, `IMAGE` or `PROMPT`). Also send exactly one object, the one that matches `type`: * `color`: `hexCode` is required (`#RRGGBB` or `#RGB`). `shadow` and `shadowOverrides` are optional and work as in `removeBackgroundProperties`. * `image`: `assetId` is required (the asset used as the new background). `prompt` is optional. * `prompt`: `prompt` is required (a text describing the new background). * `resizeProperties`: `width` and `height`, as integers. * `editWithPromptProperties`: * `prompt`: required. * `aspectRatio`: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` or `21:9`. * `quality`: `auto`, `1K`, `2K` or `4K`. * `referenceAssetIds`: a list of asset IDs used as references. * `customNamingProperties`: `name`, the name to apply. * `metaproperties`: `ids` (metaproperty IDs) and `copyEnabled`. * `metapropertyValues`: a list of `{id, value}`, where `id` is the metaproperty ID. `value` has exactly one of: * `optionIds`: a non-empty list of option IDs. * `text`: a non-blank text, up to 2499 characters. * `date`: a date as `YYYY-MM-DD`. Example: ```json { "name": "Social media version", "description": "Blue background, resized, with a flower added", "capabilities": ["TRANSFORMATION_AGENT"], "agentProperties": { "TRANSFORMATION_AGENT": { "removeBackground": false, "replaceBackground": true, "replaceBackgroundProperties": { "type": "COLOR", "color": { "hexCode": "#0097ff", "shadow": "SOFT" } }, "resize": true, "resizeProperties": { "width": 1080, "height": 1920 }, "editWithPrompt": true, "editWithPromptProperties": { "prompt": "Add a flower", "aspectRatio": "9:16" }, "customNaming": false, "metaproperties": { "ids": ["a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a"], "copyEnabled": true }, "metapropertyValues": [ { "id": "7d2c4e90-3b1a-4c6f-9e58-0a1b2c3d4e5f", "value": { "optionIds": ["2e6a1c88-9f03-4d7b-8c15-b4a7e0d93f61"] } }, { "id": "c91e7f35-8a24-4b0d-a3f6-5e8d1b7c9a20", "value": { "date": "2026-11-04" } } ] } } } ``` ## Request body (required) Content types: `application/json` ## Responses - `201` - Agent created - `400` - The request body failed validation - `401` - Missing or invalid bearer token - `403` - Caller lacks the required permission for this operation - `429` - Caller exceeded its configured request rate - `5XX` - Gateway or a downstream service failed to process the request ## OpenAPI definition ````yaml openapi: 3.0.3 info: title: AI Agents version: "1.0" servers: - url: https://{your-bynder-domain}/ paths: /api/1/agent/agents: post: tags: - Agents summary: Create agent operationId: createAgent description: >- Creates a new agent with the given name, prompt, and capabilities. Capabilities are set at creation time and cannot be changed afterwards. ### Prompt and agent properties guide. > 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. `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. All IDs (metaproperties, options, assets) must be valid UUIDs (version 4). Responses can include a read-only `targetFields` list inside `agentProperties`. The server fills it in from the prompt or from `targetMetapropertyId`; do not send it. #### ENRICHMENT_AGENT * `prompt.text`: free text. Use `${...}` placeholders to name the fields the agent reads or suggests. Placeholders are case-sensitive. * `${title}`: the asset title. * `${description}`: the asset description. * `${tags}`: the asset tags. * `${metaproperty:}`: a metaproperty, identified by its ID. The ID must be an existing metaproperty of the account. * `${asset:}`: a reference asset. * `agentProperties`: no properties are accepted. Send `{"ENRICHMENT_AGENT": {}}`. Example: ```json { "name": "Describe and tag assets", "description": "Suggests a title, description, tags and metaproperty values", "capabilities": ["ENRICHMENT_AGENT"], "prompt": { "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}." }, "agentProperties": { "ENRICHMENT_AGENT": {} } } ``` #### GOVERNANCE_AGENT > Only one Governance Agent type is allowed per account. * `prompt`: not used. * `agentProperties`: no properties are accepted. Send `{"GOVERNANCE_AGENT": {}}`. Example: ```json { "name": "Governance", "description": "Governance checks on assets", "capabilities": ["GOVERNANCE_AGENT"], "agentProperties": { "GOVERNANCE_AGENT": {} } } ``` #### BRAND_COMPLIANCE_AGENT * `prompt.text`: a JSON array of rules, sent as a string. Each rule is `{"id", "category", "text"}`. Rule text can reference `${asset:}`. * `agentProperties.BRAND_COMPLIANCE_AGENT.targetMetapropertyId`: the ID of the metaproperty the compliance result is written to. Example: ```json { "name": "Logo compliance", "description": "Checks logo, colour and typography rules", "capabilities": ["BRAND_COMPLIANCE_AGENT"], "prompt": { "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\"}]" }, "agentProperties": { "BRAND_COMPLIANCE_AGENT": { "targetMetapropertyId": "a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a" } } } ``` #### TRANSFORMATION_AGENT * `prompt`: not used. The text instructions go in `editWithPromptProperties.prompt` and in the background prompt (see below). * `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: * `removeBackgroundProperties`: * `shadow`: `SOFT`, `HARD`, `FLOATING`, `AUTO_WITH_OVERRIDES`, or `null` for no shadow. * `shadowOverrides`: only allowed when `shadow` is `AUTO_WITH_OVERRIDES`. All fields are optional: * `subjectPose`: `flatlay` or `upright`. * `softness`: a number from 0 to 1. * `intensity`: a number from 0 to 1. * `spread`: a number from 0 to 90. * `direction`: `behind`, `behindLeft`, `left`, `frontLeft`, `front`, `frontRight`, `right` or `behindRight`. * `replaceBackgroundProperties`: `type` is required (`COLOR`, `IMAGE` or `PROMPT`). Also send exactly one object, the one that matches `type`: * `color`: `hexCode` is required (`#RRGGBB` or `#RGB`). `shadow` and `shadowOverrides` are optional and work as in `removeBackgroundProperties`. * `image`: `assetId` is required (the asset used as the new background). `prompt` is optional. * `prompt`: `prompt` is required (a text describing the new background). * `resizeProperties`: `width` and `height`, as integers. * `editWithPromptProperties`: * `prompt`: required. * `aspectRatio`: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` or `21:9`. * `quality`: `auto`, `1K`, `2K` or `4K`. * `referenceAssetIds`: a list of asset IDs used as references. * `customNamingProperties`: `name`, the name to apply. * `metaproperties`: `ids` (metaproperty IDs) and `copyEnabled`. * `metapropertyValues`: a list of `{id, value}`, where `id` is the metaproperty ID. `value` has exactly one of: * `optionIds`: a non-empty list of option IDs. * `text`: a non-blank text, up to 2499 characters. * `date`: a date as `YYYY-MM-DD`. Example: ```json { "name": "Social media version", "description": "Blue background, resized, with a flower added", "capabilities": ["TRANSFORMATION_AGENT"], "agentProperties": { "TRANSFORMATION_AGENT": { "removeBackground": false, "replaceBackground": true, "replaceBackgroundProperties": { "type": "COLOR", "color": { "hexCode": "#0097ff", "shadow": "SOFT" } }, "resize": true, "resizeProperties": { "width": 1080, "height": 1920 }, "editWithPrompt": true, "editWithPromptProperties": { "prompt": "Add a flower", "aspectRatio": "9:16" }, "customNaming": false, "metaproperties": { "ids": ["a8f3b214-c7e4-49d1-b5a2-7e91f0c83d6a"], "copyEnabled": true }, "metapropertyValues": [ { "id": "7d2c4e90-3b1a-4c6f-9e58-0a1b2c3d4e5f", "value": { "optionIds": ["2e6a1c88-9f03-4d7b-8c15-b4a7e0d93f61"] } }, { "id": "c91e7f35-8a24-4b0d-a3f6-5e8d1b7c9a20", "value": { "date": "2026-11-04" } } ] } } } ``` 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" security: - bearerAuth: [] components: schemas: 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 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 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 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 ErrorResponse: type: object properties: code: type: string message: type: string 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" 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" securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````