--- updatedAt: 2026-09-17T13:47:36.000Z agentTools: projectIndex: https://developers.jasper.ai/llms.txt --- # Using Agents This guide describes how to offload marketing tasks via API to Jasper 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: 1. **Discover** - Retrieve available tasks Agents can perform 2. **Configure** - Use the Context Items from the response to build your request body 3. **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: ```bash curl --location '' \\ --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:** ```bash curl --location '' \\ --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: ```bash curl --location '' \\ --header 'x-api-key: YOUR_API_KEY' ``` **Response:** ```json { "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` ```json { "id": "aefc16e6-f4a4-4915-83bf-0c73e146ae93", "value": "Jasper AI" } ``` ### TEXTAREA **Value format:** `string` ```json { "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`) ```json { "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`) ```json { "id": "7a3b2c1d-4e5f-6789-abcd-ef0123456789", "value": ["Option A", "Option B", "Option C"] } ``` ### KNOWLEDGE **Value format:** `array` **Option 1:** Array of Knowledge IDs: ```json { "id": "6b8d4641-4255-479d-adf0-ef003227fad5", "value": ["kno_1", "kno_2"] } ``` **Option 2:** Array of objects with optional extraction prompt: ```json { "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`: ```json { "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: 1. **Synchronous** - Wait for the complete response 2. **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: ```bash curl --location '' \\ --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" } ], "fallbackToWorkspaceDefaultIq": true }' ``` Set `fallbackToWorkspaceDefaultIq` to `true` to opt in. Requests that omit it continue to behave as they did before. **Response:** ```json { "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: ```bash curl --location '' \\ --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" } ], "fallbackToWorkspaceDefaultIq": true }' ``` **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 | | `fallbackToWorkspaceDefaultIq` | boolean | Defaults to `false`. When `true`, any unspecified Style Guide, Brand Voice, or Audience uses the workspace default for that IQ type. | An IQ item you pass explicitly always takes precedence over the workspace default. Fallback applies independently for each supported IQ type. For example, you can pass a Style Guide and use the workspace-default Brand Voice and Audience. Knowledge and Product IQ are not included because they do not have workspace defaults. ### 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:** ```bash curl --location '' \\ --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 ```bash curl --location '' \\ --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 ```bash curl --location '' \\ --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" } ] }' ```