--- updatedAt: 2026-04-21T01:30:12.000Z agentTools: projectIndex: https://developers.jasper.ai/llms.txt --- # Run template Run a default template or custom template by ID to generate an AI output. See our guide on Using Templates for tips on getting started. # OpenAPI definition ```json { "openapi": "3.1.0", "paths": { "/v1/templates/{templateId}/run": { "post": { "description": "Run a default template or custom template by ID to generate an AI output. See our guide on Using Templates for tips on getting started.", "operationId": "completeTemplate", "parameters": [ { "name": "templateId", "required": true, "in": "path", "description": "The template's unique ID", "schema": { "example": "skl_501CFB66C00F47ECA277BF4ECC99DD21", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteTemplateRequest" } } } }, "responses": { "200": { "description": "Generate outputs for a specific template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteTemplateResponse" } } } }, "400": { "description": "Bad Request. May need to check that the request body corresponds with the input schema for the template you are trying to complete." }, "404": { "description": "Not found. May be due to an incorrect URL path." }, "500": { "description": "Internal server error. Unable to generate outputs for specified template." } }, "security": [ { "X-API-Key": [] }, { "oauth2": [ "user" ] } ], "summary": "Run template", "tags": [ "Templates" ] } } }, "info": { "title": "Jasper API", "description": "Jasper API", "version": "1.0", "contact": {} }, "tags": [ { "name": "Templates", "description": "" } ], "servers": [ { "url": "https://api.jasper.ai" } ], "components": { "securitySchemes": { "X-API-Key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Workspace authentication using API key tokens in the X-API-Key header." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.jasper.ai/oauth2/authorize", "tokenUrl": "https://api.jasper.ai/oauth2/token", "refreshUrl": "https://api.jasper.ai/oauth2/token", "scopes": { "user:read": "Read user information", "user": "Read and write user information" } } }, "description": "User-level authentication using OAuth bearer tokens in the Authorization header." } }, "schemas": { "ProductInputDto": { "type": "object", "properties": { "productId": { "type": "string", "description": "The ID of the Product IQ product to attach as context (`prd_`, or legacy `itm_`).", "example": "prd_073D2D49094A4AED991A47B614522579" }, "attributeIds": { "description": "Optional attribute IDs to limit which of the product's attributes are included. Omit to include all attributes. The product name is always included. Discover attribute IDs via `GET /v1/products/attributes`.", "example": [ "atr_535B1EC15F5F41EAB1B400E9ED4077B6" ], "type": "array", "items": { "type": "string" } } }, "required": [ "productId" ] }, "AudienceIdsDto": { "type": "object", "properties": { "primary": { "type": "string", "description": "Primary audience ID.", "example": "aud_2ee766eaa4ef48e59da1d9602bfecf2d" }, "secondary": { "description": "Secondary audience IDs included alongside the primary audience. At most 24.", "example": [ "aud_7c1f0b9d2e4a4f6b8d3c5a1e9f0b2c4d" ], "type": "array", "items": { "type": "string" } } }, "required": [ "primary", "secondary" ] }, "WebScraperOptions": { "type": "object", "properties": { "urls": { "description": "An optional list of URLs for Jasper to scrape during generation to use as context. Max of 3 per request. If nothing is provided, Jasper will automatically detect URLs in the request inputs to use as context for the generation.", "example": [ "https://en.wikipedia.org/wiki/Rabbit", "https://en.wikipedia.org/wiki/Lagomorpha" ], "type": "array", "items": { "type": "string" } } } }, "WebSearchOptions": { "type": "object", "properties": { "siteBlockList": { "description": "An optional list of domains for Jasper to omit from the search results. For example, providing mycompetor.com will filter out results returned with that domain and it’s subdomains, such as blog.mycompetitor.com. If nothing is provided, all search results will be used for the generation.", "example": [ "https://en.wikipedia.org" ], "type": "array", "items": { "type": "string" } }, "searchQuery": { "type": "string", "description": "A query to override the default behavior for how Jasper searches the web. If nothing is provided, Jasper will automatically define an appropriate query based on the inputs supplied.", "example": "Recent bear attacks in Alaska" }, "maxResults": { "type": "number", "description": "The number of search results to use for additional context when generating a response", "enum": [ 1, 2, 3, 4, 5 ] } } }, "GeneratedText": { "type": "object", "properties": { "text": { "type": "string", "example": "\n\nFurry friends so sweet,\nNibbling on fresh kale leaves,\nSoft hops fill the breeze." }, "id": { "type": "string", "example": "txt_bce766eaa4ef48e59da1d9602bfecf2d" } } }, "CompleteTemplateInputs": { "type": "object", "properties": { "knowledgeIds": { "description": "A list of knowledge items to use when generating content. Up to 3 knowledge items are allowed.", "example": "[kno_bce766eaa4ef48e59da1d9602bfecf2d, kno_61cb0d23f2cd4cc2b4e6fd25057dfc1a]", "type": "array", "items": { "type": "string" } }, "attachmentIds": { "description": "A list of temporary attachment IDs (prefixed `tmp_`) to use as ad-hoc context when running the template. Create each attachment up front via `POST /v1/attachments` and pass the returned IDs here. Up to 3 attachments are allowed. Temporary attachments are not durable — use `knowledgeIds` for content that should persist in your workspace.", "example": [ "tmp_2ee766eaa4ef48e59da1d9602bfecf2d" ], "type": "array", "items": { "type": "string" } }, "products": { "description": "A list of Products to use as context when running the template. Reference each Product by ID, optionally narrowing which of its attributes are included. Discover Products with `GET /v1/products`.", "type": "array", "items": { "$ref": "#/components/schemas/ProductInputDto" } }, "toneId": { "type": "string", "description": "Tone to use when running the template", "example": "ton_2ee766eaa4ef48e59da1d9602bfecf2d" }, "styleId": { "type": "string", "description": "Style to use when running the template", "example": "sty_2ee766eaa4ef48e59da1d9602bfecf2d" }, "audienceId": { "type": "string", "description": "Audience to use when running the template", "example": "aud_2ee766eaa4ef48e59da1d9602bfecf2d" }, "audienceIds": { "description": "Structured audience selection with a primary audience and optional secondary audiences. When both `audienceId` and `audienceIds` are sent, `audienceIds` wins.", "allOf": [ { "$ref": "#/components/schemas/AudienceIdsDto" } ] }, "retrievalAddOn": { "type": "string", "description": "The add-on to use to further enhance your generation with information that lives outside of Jasper. You can further customize the behavior of the add-on with the associated parameter in the options portion of your request body.", "enum": [ "webScraper", "webSearch" ] } } }, "RequestOptionsDto": { "type": "object", "properties": { "outputCount": { "type": "number", "description": "Number of outputs to generate.", "example": 3, "default": 1 }, "outputLanguage": { "type": "string", "description": "The language in which outputs should be returned.", "default": "English", "example": "English", "enum": [ "English", "French", "Spanish", "Italian", "Portuguese", "German" ] }, "inputLanguage": { "type": "string", "description": "The language in which inputs will be given.", "default": "English", "example": "English", "enum": [ "English", "French", "Spanish", "Italian", "Portuguese", "German" ] }, "languageFormality": { "type": "string", "description": "The formality of the outputs, for the languages where formality applies.", "default": "default", "example": "default", "enum": [ "default", "more", "less" ] }, "webScraper": { "description": "Optional parameters for further customizing the behavior of the webScraper add-on.", "allOf": [ { "$ref": "#/components/schemas/WebScraperOptions" } ] }, "webSearch": { "description": "Optional parameters for further customizing the behavior of the webSearch add-on.", "allOf": [ { "$ref": "#/components/schemas/WebSearchOptions" } ] }, "fallbackToWorkspaceDefaultIq": { "type": "boolean", "description": "When true, any Jasper IQ your request leaves unspecified falls back to your workspace default for that type (style guide, brand voice, and audience). IQ you pass explicitly always wins, and a type with no workspace default stays unset. Defaults to false, so requests that omit this option behave exactly as before.", "default": false } } }, "CompleteTemplateRequest": { "type": "object", "properties": { "inputs": { "description": "A template's inputs. The required inputs for the given template should match it's inputKey values, which are available in the response from a GET request to templates. In addition, a tone can be optionally applied to any template.", "example": { "productName": "Snazzy Snooze Machine", "productDescription": "Hits snooze on your alarm for you", "tone": "Clever, Witty", "knowledgeIds": [ "kno_bce766eaa4ef48e59da1d9602bfecf2d", "kno_61cb0d23f2cd4cc2b4e6fd25057dfc1a" ], "attachmentIds": [ "tmp_2ee766eaa4ef48e59da1d9602bfecf2d" ], "products": [ { "productId": "prd_073D2D49094A4AED991A47B614522579" } ], "styleId": "sty_2ee766eaa4ef48e59da1d9602bfecf2d", "audienceId": "aud_2ee766eaa4ef48e59da1d9602bfecf2d", "toneId": "ton_2ee766eaa4ef48e59d9602bfecf2d", "retrievalAddOn": "webScraper" }, "additionalProperties": { "oneOf": [ { "type": "string" } ] }, "allOf": [ { "$ref": "#/components/schemas/CompleteTemplateInputs" } ] }, "options": { "description": "The schema of a template's allowed inputs.", "allOf": [ { "$ref": "#/components/schemas/RequestOptionsDto" } ] } }, "required": [ "inputs" ] }, "CompleteTemplateResponse": { "type": "object", "properties": { "requestId": { "type": "string", "example": "bce766ea-a4ef-48e5-9da1-d9602bfecf2d" }, "resource": { "type": "string", "example": "content" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedText" } } } } } }, "x-readme": { "metrics-enabled": false } } ```