Sign in

v1

latestOpenAPI 3.1.02026-07-265094114.0 KB
Tasks

Run an agent task

Execute an agent task by ID to generate AI output. Provide the necessary context items and configuration in the request body.

post/v1/tasks/{id}/run

Path parameters

idstring required
Example:agt_0190f3a1b2c34d5e6f7a8b9c0d1e2f3a

The external ID (agt_…) or internal UUID of the agent task to run

Request body

versionnumber

Agent task version (optional, defaults to latest)

toLanguagestring

Target output language for the completion (optional, defaults to EN-US)

knowledgeIdsstring[]

Array of knowledge IDs to use as context to power the agent

attachmentIdsstring[]

Array of temporary attachment IDs (prefixed tmp_) to use as ad-hoc context for this run. Create attachments up front via POST /v1/attachments and pass the returned IDs here. Temporary attachments are intended for short-lived context (the same attachment can be referenced across retries of the same run) and are not durable — use knowledgeIds for content that should persist in your workspace.

toneIdstring

Tone ID for the brand voice of the agent's output

audienceIdstring

The primary audience ID used to customize the agent's output for a target audience.

additionalAudienceIdsstring[]

Additional audience IDs to customize the agent's output for multiple target audiences in a single run, included alongside the primary audienceId.

styleGuideIdstring

Style Guide ID to apply writing rules to the agent's output

toolsstring[]

Array of tools to enable for agent task execution. Can include WEB_SEARCH and/or KNOWLEDGE_SEARCH

Example request

{
  "contextItems": [
    {
      "id": "70346737-878b-4329-a4d6-9a054efef508",
      "value": [
        "Registration reminder email",
        "Confirmation email"
      ]
    },
    {
      "name": "Greeting",
      "question": "Who is the person that you want me to greet in the registration reminder email?",
      "answer": "John Doe"
    }
  ],
  "version": 1,
  "toLanguage": "EN-US",
  "knowledgeIds": [
    "kno_123",
    "kno_456"
  ],
  "attachmentIds": [
    "tmp_2ee766eaa4ef48e59da1d9602bfecf2d"
  ],
  "toneId": "ton_2ee766eaa4ef48e59da1d9602bfecf2d",
  "audienceId": "aud_123",
  "additionalAudienceIds": [
    "aud_456",
    "aud_789"
  ],
  "styleGuideId": "sty_123",
  "tools": [
    "WEB_SEARCH",
    "KNOWLEDGE_SEARCH"
  ]
}

Response

Successfully executed agent task and generated output

requestIdstring
resourcestring

Example response

{
  "requestId": "bce766ea-a4ef-48e5-9da1-d9602bfecf2d",
  "resource": "tasks",
  "data": {
    "output": [
      {
        "type": "TEXT",
        "value": "This is the generated content from the agent..."
      }
    ],
    "metadata": {
      "credits": {
        "cost": 40
      },
      "translation": {
        "tmsMatches": [
          {
            "sourceSegment": "Click Save to continue.",
            "matches": [
              {
                "target": "Klicken Sie auf Speichern, um fortzufahren.",
                "score": 1
              }
            ]
          }
        ]
      }
    }
  }
}