---
updatedAt: 2026-04-21T01:30:12.000Z
agentTools:
  projectIndex: https://developers.jasper.ai/llms.txt
---

# Run command

Run a command to generate an AI Output

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "paths": {
    "/v1/command": {
      "post": {
        "description": "Run a command to generate an AI Output",
        "operationId": "command",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommandDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The command ran successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. May be missing required inputs or may have badly formatted inputs or options."
          },
          "500": {
            "description": "Internal server error. Unable to run command."
          }
        },
        "security": [
          {
            "X-API-Key": []
          },
          {
            "oauth2": [
              "user"
            ]
          }
        ],
        "summary": "Run command",
        "tags": [
          "Command"
        ]
      }
    }
  },
  "info": {
    "title": "Jasper API",
    "description": "Jasper API",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "Command",
      "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"
        ]
      },
      "CommandInputs": {
        "type": "object",
        "properties": {
          "command": {
            "type": "string",
            "description": "Your command for Jasper",
            "example": "Write a haiku about rabbits"
          },
          "context": {
            "type": "string",
            "description": "Do you have any background information for Jasper?",
            "example": "All rabbits eat kale"
          },
          "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 generating content. 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 generating content. 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"
            }
          },
          "styleId": {
            "type": "string",
            "description": "The style to use when generating a command",
            "example": "sty_2ee766eaa4ef48e59da1d9602bfecf2d"
          },
          "toneId": {
            "type": "string",
            "description": "Tone to use when generating a command",
            "example": "ton_2ee766eaa4ef48e59da1d9602bfecf2d"
          },
          "audienceId": {
            "type": "string",
            "description": "The Audience to use when generating a command",
            "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"
            ]
          }
        },
        "required": [
          "command"
        ]
      },
      "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
            ]
          }
        }
      },
      "CommandOptions": {
        "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
          },
          "completionType": {
            "type": "string",
            "description": "How would you like Jasper to optimize your output? With quality, Jasper will take more time to generate the highest quality output possible. With performance, Jasper will prioritize generating outputs faster.",
            "enum": [
              "performance",
              "quality"
            ],
            "default": "performance"
          }
        }
      },
      "CommandDto": {
        "type": "object",
        "properties": {
          "inputs": {
            "description": "Inputs for generating a command",
            "allOf": [
              {
                "$ref": "#/components/schemas/CommandInputs"
              }
            ]
          },
          "options": {
            "description": "Options for generating a command",
            "allOf": [
              {
                "$ref": "#/components/schemas/CommandOptions"
              }
            ]
          }
        },
        "required": [
          "inputs"
        ]
      },
      "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"
          }
        }
      },
      "CommandResponseDto": {
        "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
  }
}
```