AI Agents

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"}.

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:<metaproperty_id>}: a metaproperty, identified by its ID. The ID must be an existing metaproperty of the account.
  • ${asset:<asset_id>}: a reference asset.
• agentProperties: no properties are accepted. Send {"ENRICHMENT_AGENT": {}}.

Example:

{
  "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:

{
  "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:<asset_id>}.
• agentProperties.BRAND_COMPLIANCE_AGENT.targetMetapropertyId: the ID of the metaproperty the compliance result is written to.

Example:

{
  "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:

{
  "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" }
        }
      ]
    }
  }
}

Returns a single agent by id.

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.

Deletes an agent by id.