Using Agents

The /tasks endpoint exposes marketing tasks that Jasper Agents can perform on your behalf. Each Agent task is designed to accomplish a specific marketing job-to-be-done, such as conducting competitive research, creating a blog post, or planning a social campaign.

Unlike commands, Agent tasks are optimized for specific jobs-to-be-done. They are embedded with best practices, tools, and model settings specific to the task. They also are defined with structured inputs, called Context Items. Context Items represent the information the agent needs to perform the task optimally. This makes them ideal for creating reliable, repeatable outcomes and integration into applications where you want to offer a more guided experienced for end-users.

Integrating Agent tasks

The Agent task workflow follows three steps:

Discover - Retrieve available tasks Agents can perform
Configure - Use the Context Items from the response to build your request body
Execute - Run the Agent to execute the task (either synchronously or via streaming)

Discovering Agent tasks

List all available Agent tasks

Retrieve all available Agent tasks for your workspace:

curl --location '<https://api.jasper.ai/v1/tasks>' \\
--header 'x-api-key: YOUR_API_KEY'

Query parameters

Parameter	Type	Default	Description
`size`	number	100	Number of Agent tasks to return per page (1-100)
`page`	number	1	Page number (1-indexed)
`scope`	string	-	Filter by scope: `PUBLIC` (Jasper-published) or `WORKSPACE` (custom workspace agents)
`searchTerm`	string	-	Search term to filter tasks by name, description, categories, or tags. Performs partial case-insensitive matching.
`includeContextItems`	boolean	false	Include context items (input fields) for each Agent task
`includeCategories`	boolean	false	Include categories for each Agent task

Example with query parameters:

curl --location '<https://api.jasper.ai/v1/tasks?scope=PUBLIC&includeContextItems=true&size=25>' \\
--header 'x-api-key: YOUR_API_KEY'

Get a specific Agent task

Retrieve details about a specific Agent task by its ID. This is the recommended approach when you know which Agent task you want to use:

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5>' \\
--header 'x-api-key: YOUR_API_KEY'

Response:

{
    "requestId": "e6f7ebab-7f89-44a8-823f-014d9b5be117",
    "resource": "tasks",
    "data": {
        "id": "94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5",
        "name": "Blog Post",
        "description": "Write long-form content that provides value, drives traffic, and enhances SEO",
        "contextItems": [
            {
                "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
                "name": "Outline",
                "type": "TEXTAREA",
                "question": "What is the outline of your post?",
                "tooltip": null,
                "required": false
            },
            {
                "id": "80023f9a-5104-4cf8-8981-378f614272aa",
                "name": "Blog length",
                "type": "SELECT",
                "question": "How long would you like the blog post to be?",
                "options": [
                    "Short (under 800 words)",
                    "Medium (800-1500 words)",
                    "Long (over 1500 words)"
                ],
                "tooltip": null,
                "required": false
            },
            {
                "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
                "name": "Topic",
                "type": "INPUT",
                "question": "What is the topic of your post?",
                "tooltip": null,
                "required": false
            }
        ],
        "version": 9,
        "scope": "PUBLIC",
        "updatedAt": "2025-12-18T23:57:07.342Z",
        "createdAt": "2024-01-25T01:13:04.577Z",
        "longDescription": "#### Overview\\nCreate an insightful blog post designed to captivate your target audience...",
        "publishedAt": "2024-06-11T07:31:06.494Z",
        "categories": []
    }
}

Understanding context items

The contextItems array in the Agent task response defines the inputs you need to provide when running the Agent task. Each Context Item contains:

Field	Description
`id`	Unique identifier for the context item. Use this in your run request.
`name`	Human-readable name of the input field
`type`	Input type: `INPUT`, `TEXTAREA`, `SELECT`, `MULTISELECT`, or `KNOWLEDGE`
`question`	The question or prompt to display to users
`options`	For `SELECT` and `MULTISELECT` types, the available options to choose from
`required`	Whether this input is required
`tooltip`	Optional help text for the input

Context item types & value formats

Each context item type expects a specific value format when running a Agent task:

INPUT

Value format: string

{
    "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
    "value": "Jasper AI"
}

TEXTAREA

Value format: string

{
    "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
    "value": "1. Introduction\\n2. Main points\\n3. Conclusion"
}

SELECT

Value format: string (must match one of the provided options)

{
    "id": "80023f9a-5104-4cf8-8981-378f614272aa",
    "value": "Medium (800-1500 words)"
}

MULTISELECT

Value format: array of strings (each must match one of the provided options)

{
    "id": "7a3b2c1d-4e5f-6789-abcd-ef0123456789",
    "value": ["Option A", "Option B", "Option C"]
}

KNOWLEDGE

Value format: array

Option 1: Array of Knowledge IDs:

{
    "id": "6b8d4641-4255-479d-adf0-ef003227fad5",
    "value": ["kno_1", "kno_2"]
}

Option 2: Array of objects with optional extraction prompt:

{
    "id": "6b8d4641-4255-479d-adf0-ef003227fad5",
    "value": [
        {
            "knowledgeId": "kno_1",
            "knowledgeExtractionPrompt": "Extract only the product specifications"
        },
        {
            "knowledgeId": "kno_2"
        }
    ]
}

Field	Required	Description
`knowledgeId`	Yes	The Knowledge item ID
`knowledgeExtractionPrompt`	No	Custom prompt to control how information is retrieved from the Knowledge item. Use this for more control over what content is extracted.

Building dynamic UIs

Use the type field to determine which UI component to render: text inputs for INPUT, text areas for TEXTAREA, dropdowns or radio buttons for SELECT, multi-select components for MULTISELECT, and knowledge pickers for KNOWLEDGE. The question field provides the label, and options provides the available choices for selection types.

Custom context items

In addition to the predefined context items, you can pass custom context items to provide additional context for the generation. Custom context items use name, question, and answer instead of id and value:

{
    "contextItems": [
        {
            "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
            "value": "Your outline here"
        },
        {
            "name": "Target Reader",
            "question": "Who is the primary audience for this blog post?",
            "answer": "Marketing managers at B2B SaaS companies"
        }
    ]
}

This allows you to inject additional context that isn't part of the Agent task's predefined inputs, giving you flexibility to customize the generation based on your specific needs.

Running Agent tasks

There are two ways to execute a Agent task:

Synchronous - Wait for the complete response
Streaming - Receive the output progressively via Server-Sent Events (SSE)

Synchronous execution

Use the /run endpoint to execute a Agent task and receive the complete output in a single response:

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5/run>' \\
--header 'x-api-key: YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--data '{
    "contextItems": [
        {
            "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
            "value": "1. About Jasper\\n2. AI for Marketers\\n3. Jasper IQ Layer\\n4. Get started today"
        },
        {
            "id": "80023f9a-5104-4cf8-8981-378f614272aa",
            "value": "Medium (800-1500 words)"
        },
        {
            "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
            "value": "Jasper AI"
        }
    ]
}'

Response:

{
    "requestId": "5aa60a9f-5c9c-4307-8543-38cbd2648863",
    "resource": "tasks",
    "data": {
        "output": [
            {
                "type": "TEXT",
                "value": "# Meet Jasper: The AI Copilot Built for Enterprise Marketing Teams\\n\\nMarketing teams face a relentless challenge..."
            }
        ]
    }
}

Streaming execution

Use the /run/stream endpoint to receive content as it's generated. This provides a better user experience for longer content by showing progress in real-time:

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5/run/stream>' \\
--header 'x-api-key: YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--header 'Accept: text/event-stream' \\
--data '{
    "contextItems": [
        {
            "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
            "value": "1. About Jasper\\n2. AI for Marketers\\n3. Jasper IQ Layer\\n4. Get started today"
        },
        {
            "id": "80023f9a-5104-4cf8-8981-378f614272aa",
            "value": "Medium (800-1500 words)"
        },
        {
            "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
            "value": "Jasper AI"
        }
    ]
}'

Streamed response (SSE):

The streaming endpoint returns events in the following format:

event: message
id: 1
data: {"step":{"id":"8f4f5bc7-729e-498d-b946-f6995ad66e71","status":"loading","label":"Thinking","description":"**Drafting the Jasper Post**\\n\\nI'm starting to flesh out the \\"About Jasper\\" section..."}}

event: message
id: 9
data: {"step":{"id":"8f4f5bc7-729e-498d-b946-f6995ad66e71","status":"completed","label":"Thought for 19 seconds"}}

event: message
id: 10
data: {"step":{"id":"2a2c1305-6cb9-453c-b700-578b6c464b9a","status":"loading","label":"Generating content"}}

event: message
id: 11
data: {"id":"b285e8c1-7b15-4da8-bfba-e9ccbf3b7361","content":"# Unleash Enterprise Growth with Jasper AI: The Marketing Copilot\\n\\nEvery marketing team faces the same relentless challenge: the demand for high","role":"JASPER","usage":null,"skillId":"365178e6-8123-4e24-936a-771def6982ce","contentId":"b285e8c1-7b15-4da8-bfba-e9ccbf3b7361"}

event: message
id: 12
data: {"id":"b285e8c1-7b15-4da8-bfba-e9ccbf3b7361","content":"-quality content far outpaces the time available to create it...","role":"JASPER",...}

Customization parameters

In addition to the contextItems, you can further customize Agent task outputs with these optional parameters:

Jasper IQ

Parameter	Type	Description
`toneId`	string	Apply a voice to customize outputs to your brand's unique personality
`audienceId`	string	Adjust the content for a specific audience persona
`styleGuideId`	string	Apply style guide rules to ensure brand consistency
`knowledgeIds`	array	Ground the agent in your company's proprietary information

Localization

Parameter	Type	Description
`toLanguage`	string	Generate content in a specific language (e.g., "EN-US", "ES", "FR")

Versioning

Parameter	Type	Description
`version`	number	Run a specific version of the Agent task. Defaults to published version.

Example with optional parameters:

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5/run>' \\
--header 'x-api-key: YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--data '{
    "contextItems": [
        {
            "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
            "value": "1. About Jasper\\n2. AI for Marketers\\n3. Jasper IQ Layer\\n4. Get started today"
        },
        {
            "id": "80023f9a-5104-4cf8-8981-378f614272aa",
            "value": "Medium (800-1500 words)"
        },
        {
            "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
            "value": "Jasper AI"
        }
    ],
    "toneId": "ton_abc123",
    "audienceId": "aud_xyz789",
    "styleGuideId": "sty_def456",
    "knowledgeIds": ["kno_123", "kno_456"],
    "toLanguage": "EN-US"
}'

Example: Blog Post Agent Task

Step 1: Get the Agent Task Details

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5>' \\
--header 'x-api-key: YOUR_API_KEY'

From the response, note the contextItems:

Outline (id: adea448e-57c5-4bc2-8033-3d27c82692a0) - TEXTAREA
Blog length (id: 80023f9a-5104-4cf8-8981-378f614272aa) - SELECT with options
Topic (id: aefc16e6-f4a4-4915-83bf-0c73e146ae93) - INPUT

Step 2: Run the Agent Task

curl --location '<https://api.jasper.ai/v1/tasks/94e0c6ab-94a7-4dd5-a6e4-43574a5e14d5/run>' \\
--header 'x-api-key: YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--data '{
    "contextItems": [
        {
            "id": "adea448e-57c5-4bc2-8033-3d27c82692a0",
            "value": "1. Introduction to content marketing\\n2. Why AI is transforming content creation\\n3. Best practices for AI-assisted writing\\n4. Conclusion and next steps"
        },
        {
            "id": "80023f9a-5104-4cf8-8981-378f614272aa",
            "value": "Medium (800-1500 words)"
        },
        {
            "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93",
            "value": "AI-Powered Content Marketing"
        }
    ]
}'