Run an agent task

post

https://api.jasper.ai/v1/tasks/{id}/run

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

Path Params

string

required

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

Body Params

contextItems

array

required

Array of context items - can include both predefined context items (with id and value) and custom context items (with name, question, and answer)

contextItems*

version

number

Agent task version (optional, defaults to latest)

toLanguage

string

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

knowledgeIds

array of strings

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

knowledgeIds

attachmentIds

array of strings

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.

attachmentIds

toneId

string

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

audienceId

string

Audience ID for to customize the agent's output for your a target audience

styleGuideId

string

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

tools

array of strings

Defaults to []

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

tools

Allowed:

Responses

400

Bad Request. The request body may be missing required fields or contain invalid data. Check the agent task input schema.

404

Agent task not found. The specified app ID may not exist.

500

Internal server error. Unable to run agent task.

200Successfully executed agent task and generated output