Jasper Products API

openapi: 3.2.0
info:
  title: Jasper Products API
  description: Jasper API
  version: '1.0'
  contact: {}
servers:
- url: https://api.jasper.ai
tags:
- name: Products
  description: ''
paths:
  /v1/products:
    post:
      description: Create a Product. Provide `attributes` to set values directly (including the product name via the `Name` attribute, and images via the `Images` attribute). To attach images, first create each one with `POST /v1/context-sources`, then reference the returned IDs in the `Images` attribute value. The sources a Product was generated from are managed in the web app, not through this API.
      operationId: createProduct
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequestDto'
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSingleResponseDto'
        '400':
          description: Bad request. May be missing required inputs or may have badly formatted inputs.
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '500':
          description: Internal server error. Unable to create product.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Create a Product
      tags:
      - Products
    get:
      description: Retrieve Products in your workspace.
      operationId: getAllProducts
      parameters:
      - name: page
        required: false
        in: query
        description: The page number to return (1-based).
        schema:
          default: 1
          example: 1
          type: number
      - name: size
        required: false
        in: query
        description: The number of products to return per page.
        schema:
          maximum: 100
          default: 10
          example: 10
          type: number
      - name: searchTerm
        required: false
        in: query
        description: Case-insensitive search over product name and category names.
        schema:
          example: enterprise
          type: string
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponseDto'
        '400':
          description: Bad request. May be missing required inputs or may have badly formatted inputs.
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '500':
          description: Internal server error. Unable to get products.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Retrieve Products
      tags:
      - Products
  /v1/products/attributes:
    get:
      description: Retrieve the attributes in your Product Schema.
      operationId: getProductAttributes
      parameters: []
      responses:
        '200':
          description: List of product attributes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductAttributesResponseDto'
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '500':
          description: Internal server error. Unable to get product attributes.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Retrieve Product attributes
      tags:
      - Products
  /v1/products/{productId}:
    get:
      description: Retrieve a specific Product in your workspace by ID.
      operationId: getProductById
      parameters:
      - name: productId
        required: true
        in: path
        description: The Product's unique ID (`prd_`, or legacy `itm_`). Both are accepted.
        schema:
          example: prd_073D2D49094A4AED991A47B614522579
          type: string
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSingleResponseDto'
        '400':
          description: Bad request. May be missing required inputs or may have badly formatted inputs.
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '404':
          description: Not found. The product does not exist in your workspace.
        '500':
          description: Internal server error. Unable to get product.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Retrieve Product by ID
      tags:
      - Products
    patch:
      description: 'Update a Product in your workspace. Only the attributes you include are changed, so omit an attribute to leave it alone. Note that a `CONTEXT_SOURCE_LIST` attribute such as `Images` is replaced wholesale by the value you send: include the sources you want to keep, and send `[]` to remove all of them.'
      operationId: updateProduct
      parameters:
      - name: productId
        required: true
        in: path
        description: The Product's unique ID (`prd_`, or legacy `itm_`). Both are accepted.
        schema:
          example: prd_073D2D49094A4AED991A47B614522579
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProductRequestDto'
      responses:
        '200':
          description: Product updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSingleResponseDto'
        '400':
          description: Bad request. May be missing required inputs or may have badly formatted inputs.
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '404':
          description: Not found. The product does not exist in your workspace.
        '500':
          description: Internal server error. Unable to update product.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Update Product by ID
      tags:
      - Products
    delete:
      description: Delete a specific Product in your workspace by ID.
      operationId: deleteProduct
      parameters:
      - name: productId
        required: true
        in: path
        description: The Product's unique ID (`prd_`, or legacy `itm_`). Both are accepted.
        schema:
          example: prd_073D2D49094A4AED991A47B614522579
          type: string
      responses:
        '200':
          description: Product deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDeleteResponseDto'
        '400':
          description: Bad request. May be missing required inputs or may have badly formatted inputs.
        '401':
          description: Unauthorized access to the workspace.
        '403':
          description: Product IQ is not enabled for this workspace.
        '404':
          description: Not found. The product does not exist in your workspace.
        '500':
          description: Internal server error. Unable to delete product.
      security:
      - X-API-Key: []
      - oauth2:
        - user
      summary: Delete Product by ID
      tags:
      - Products
components:
  schemas:
    ProductAttributeValueInput:
      type: object
      properties:
        id:
          type: string
          description: The attribute ID (from `GET /products/attributes`).
          example: atr_535B1EC15F5F41EAB1B400E9ED4077B6
        value:
          description: 'The value to set. Its shape is inferred from the attribute''s type: string (text), number, boolean, ISO-8601 date string, an option label — or an array of them — (enum / multi-select), an object (key-value), or an array of values for a list-mode attribute. To set categories, use the `Categories` attribute with an array of category names.


            For a `CONTEXT_SOURCE_LIST` attribute (such as the universal `Images`), send an array of source IDs — `["csc_…"]` — returned by `POST /v1/context-sources`. This is the same shape a read returns, so the value from a `GET` can be sent back as-is. The array replaces the whole set, so include the sources you want to keep and omit the ones to remove; send `[]` to remove all. Array order is preserved. Only `FILE` sources (uploaded files) can be attached, and the attribute may narrow that further — `Images` takes PNG and JPEG.'
          oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: array
            items:
              type: string
          - type: object
          - type: array
            items:
              type: object
          example: A longer product overview…
      required:
      - id
      - value
    ProductAttributeData:
      type: object
      properties:
        id:
          type: string
          description: The unique attribute ID.
          example: atr_535B1EC15F5F41EAB1B400E9ED4077B6
        name:
          type: string
          description: The attribute name.
          example: Overview
        description:
          type: object
          description: Optional attribute description.
          nullable: true
        type:
          type: string
          description: 'The normalized core value type. A list-mode attribute (e.g. a multi-select, or a "list of numbers") reports its element type here plus `list: true` — `ARRAY` / `MULTI_SELECT` are never reported directly.'
          example: TEXT_LONG
          enum:
          - TEXT_SHORT
          - TEXT_LONG
          - NUMBER
          - DATE
          - BOOLEAN
          - ENUM
          - KEY_VALUE
          - JSON
          - CONTEXT_SOURCE_LIST
        isList:
          type: boolean
          description: Whether the attribute holds a list of values (send/receive an array) rather than a single value.
          example: false
        options:
          description: Selectable options — present only for `ENUM` attributes (single- and multi-select).
          type: array
          items:
            $ref: '#/components/schemas/ProductAttributeOptionData'
        keys:
          description: Predefined keys — present only for `KEY_VALUE` attributes. An empty array means keys are free-form (the extraction model infers them).
          example:
          - weight
          - dimensions
          type: array
          items:
            type: string
      required:
      - id
      - name
      - type
      - isList
    ProductSingleResponseDto:
      type: object
      properties:
        requestId:
          type: string
          example: bce766ea-a4ef-48e5-9da1-d9602bfecf2d
        resource:
          type: string
          example: products
        data:
          $ref: '#/components/schemas/ProductData'
      required:
      - requestId
      - resource
      - data
    UpdateProductRequestDto:
      type: object
      properties:
        accessLevel:
          type: string
          enum:
          - PRIVATE
          - PUBLIC
          description: Update who can access the product.
        attributes:
          description: Attribute values to set or replace. Omit an attribute to leave it unchanged — that is how you update one attribute without disturbing the others. Categories are updated here too, via the `Categories` attribute (an array of category names; pass an empty array to clear all categories). Categories must already exist in the schema editor; unknown names are rejected. Images are updated via the `Images` attribute, whose value is the full set of sources to keep (see `value` below).
          type: array
          items:
            $ref: '#/components/schemas/ProductAttributeValueInput'
    ProductPaginationDto:
      type: object
      properties:
        totalRecords:
          type: number
          description: Total number of matching records.
          example: 42
        page:
          type: number
          description: The current page number (1-based).
          example: 1
        pageSize:
          type: number
          description: The number of records per page.
          example: 10
        next:
          type: object
          description: URL for the next page, or null on the last page.
          nullable: true
        prev:
          type: object
          description: URL for the previous page, or null on the first page.
          nullable: true
      required:
      - totalRecords
      - page
      - pageSize
    ProductResponseDto:
      type: object
      properties:
        requestId:
          type: string
          example: bce766ea-a4ef-48e5-9da1-d9602bfecf2d
        resource:
          type: string
          example: products
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProductData'
        pagination:
          $ref: '#/components/schemas/ProductPaginationDto'
      required:
      - requestId
      - resource
      - data
    ProductData:
      type: object
      properties:
        id:
          type: string
          description: The unique product ID (`prd_`, or legacy `itm_`).
          example: prd_073D2D49094A4AED991A47B614522579
        processingState:
          type: string
          description: Processing state of the product.
          enum:
          - inProgress
          - complete
          - error
          example: complete
        accessLevel:
          type: string
          description: Who can access the product.
          enum:
          - PRIVATE
          - PUBLIC
          example: PRIVATE
        contextSourceIds:
          description: The IDs of the sources the product itself was generated from, which are managed in the web app and not settable via this API. Empty when none are attached. Expand one with `GET /v1/context-sources/{sourceId}`. This is separate from the sources held by a `CONTEXT_SOURCE_LIST` attribute such as `Images`, which appear under `attributes` and can be set through this API.
          example:
          - csc_073D2D49094A4AED991A47B614522579
          type: array
          items:
            type: string
        attributes:
          description: The product's attribute values, including the product name (the `Name` attribute). Categories are included here as the `Categories` attribute (an array of category names).
          type: array
          items:
            $ref: '#/components/schemas/ProductAttributeValueData'
        createdAt:
          type: string
          example: '2026-06-30T15:38:00.474Z'
        updatedAt:
          type: string
          example: '2026-06-30T15:38:00.474Z'
      required:
      - id
      - processingState
      - accessLevel
      - contextSourceIds
      - attributes
      - createdAt
      - updatedAt
    CreateProductRequestDto:
      type: object
      properties:
        accessLevel:
          type: string
          enum:
          - PRIVATE
          - PUBLIC
          default: PRIVATE
          description: Who can access the product. Defaults to `PRIVATE`.
        attributes:
          description: Attribute values to set on the new product. Set the product name here too, via the `Name` attribute (there is no top-level name field). Categories are set here as well, via the `Categories` attribute (its value is an array of category names, which must already exist in the schema editor). Images are set here too, via the `Images` attribute — create each one with `POST /v1/context-sources` first, then reference the returned IDs.
          type: array
          items:
            $ref: '#/components/schemas/ProductAttributeValueInput'
    ProductAttributesResponseDto:
      type: object
      properties:
        requestId:
          type: string
          example: bce766ea-a4ef-48e5-9da1-d9602bfecf2d
        resource:
          type: string
          example: products
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProductAttributeData'
      required:
      - requestId
      - resource
      - data
    ProductAttributeValueData:
      type: object
      properties:
        id:
          type: string
          description: The attribute ID.
          example: atr_535B1EC15F5F41EAB1B400E9ED4077B6
        name:
          type: string
          description: The attribute name.
          example: Overview
        type:
          type: string
          description: The attribute's normalized core type (matches the `type` from `GET /products/attributes`), or null when unresolved. List-mode attributes report their core type here and return an array `value`.
          enum:
          - TEXT_SHORT
          - TEXT_LONG
          - NUMBER
          - DATE
          - BOOLEAN
          - ENUM
          - KEY_VALUE
          - JSON
          - CONTEXT_SOURCE_LIST
          nullable: true
          example: TEXT_LONG
        isList:
          type: boolean
          description: Whether the attribute holds a list of values (matches `GET /products/attributes`). When true, `value` is an array.
          example: false
        value:
          description: 'The attribute value, typed to match `type`: a string (`TEXT_SHORT`/`TEXT_LONG`/`DATE`, and the option label for `ENUM`), a number (`NUMBER`), a boolean (`BOOLEAN`), an object (`KEY_VALUE`/`JSON`), an array of source IDs (`CONTEXT_SOURCE_LIST`, e.g. `Images` — expand one with `GET /v1/context-sources/{sourceId}`), or — for list-mode attributes — an array of the above (e.g. option labels for a multi-select). Null when the attribute is unset.'
          nullable: true
          oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: array
            items:
              type: string
          - type: object
          - type: array
            items:
              type: object
          example: A longer product overview…
      required:
      - id
      - name
      - isList
    ProductDeleteResponseDto:
      type: object
      properties:
        requestId:
          type: string
          example: bce766ea-a4ef-48e5-9da1-d9602bfecf2d
        resource:
          type: string
          example: products
        deleted:
          type: boolean
          example: true
      required:
      - requestId
      - resource
      - deleted
    ProductAttributeOptionData:
      type: object
      properties:
        value:
          type: string
          description: The option label. Set enum / multi-select values (and categories) by this label.
          example: Enterprise
      required:
      - value
  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.
x-provenance:
  method: searched
  source: https://developers.jasper.ai/reference
  harvested: '2026-10-23'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.jasper.ai/reference/cleanup.md
  - https://developers.jasper.ai/reference/command-2.md
  - https://developers.jasper.ai/reference/completetemplate-1.md
  - https://developers.jasper.ai/reference/createanalysis.md
  - https://developers.jasper.ai/reference/createattachment.md
  - https://developers.jasper.ai/reference/createcontextsource.md
  - https://developers.jasper.ai/reference/createdocument.md
  - https://developers.jasper.ai/reference/createproduct.md
  - https://developers.jasper.ai/reference/createproject.md
  - https://developers.jasper.ai/reference/createtone.md
  - https://developers.jasper.ai/reference/decompose-1.md
  - https://developers.jasper.ai/reference/deleteanalysis.md
  - https://developers.jasper.ai/reference/deletedocumentbyid.md
  - https://developers.jasper.ai/reference/deleteknowledgedocument.md
  - https://developers.jasper.ai/reference/deleteproduct.md
  - https://developers.jasper.ai/reference/deleteproject.md
  - https://developers.jasper.ai/reference/deletetone.md
  - https://developers.jasper.ai/reference/getallaudiences.md
  - https://developers.jasper.ai/reference/getalldocuments.md
  - https://developers.jasper.ai/reference/getallproducts.md
  - https://developers.jasper.ai/reference/getalltemplates-1.md
  - https://developers.jasper.ai/reference/getalltones.md
  - https://developers.jasper.ai/reference/getallusers.md
  - https://developers.jasper.ai/reference/getanalysis.md
  - https://developers.jasper.ai/reference/getaudiencebyid.md
  - https://developers.jasper.ai/reference/getcontextsourcebyid.md
  - https://developers.jasper.ai/reference/getdocumentbyid.md
  - https://developers.jasper.ai/reference/getknowledgedocument.md
  - https://developers.jasper.ai/reference/getknowledgedocuments.md
  - https://developers.jasper.ai/reference/getproductattributes.md
  - https://developers.jasper.ai/reference/getproductbyid.md
  - https://developers.jasper.ai/reference/getprojectbyid.md
  - https://developers.jasper.ai/reference/getprojects.md
  - https://developers.jasper.ai/reference/getrun.md
  - https://developers.jasper.ai/reference/getrunclaims.md
  - https://developers.jasper.ai/reference/getrunrecommendations.md
  - https://developers.jasper.ai/reference/getstyle.md
  - https://developers.jasper.ai/reference/getstylebyid.md
  - https://developers.jasper.ai/reference/gettaskbyid.md
  - https://developers.jasper.ai/reference/gettemplate-1.md
  - https://developers.jasper.ai/reference/gettone.md
  - https://developers.jasper.ai/reference/gettrends.md
  - https://developers.jasper.ai/reference/getuser.md
  - https://developers.jasper.ai/reference/listanalyses.md
  - https://developers.jasper.ai/reference/listanalysissummaries.md
  - https://developers.jasper.ai/reference/listruns.md
  - https://developers.jasper.ai/reference/listtasks.md
  - https://developers.jasper.ai/reference/packshotcompositing.md
  - https://developers.jasper.ai/reference/removebackground.md
  - https://developers.jasper.ai/reference/removetext.md
  - https://developers.jasper.ai/reference/renderimagetemplate.md
  - https://developers.jasper.ai/reference/replacebackground.md
  - https://developers.jasper.ai/reference/runtask.md
  - https://developers.jasper.ai/reference/runtaskstream.md
  - https://developers.jasper.ai/reference/searchknowledge.md
  - https://developers.jasper.ai/reference/uncrop.md
  - https://developers.jasper.ai/reference/updateanalysis.md
  - https://developers.jasper.ai/reference/updatedocument.md
  - https://developers.jasper.ai/reference/updateknowledgedocument.md
  - https://developers.jasper.ai/reference/updateproduct.md
  - https://developers.jasper.ai/reference/updateproject.md
  - https://developers.jasper.ai/reference/updatetone.md
  - https://developers.jasper.ai/reference/uploadknowledgedocument.md
  - https://developers.jasper.ai/reference/upscale.md
  - https://developers.jasper.ai/reference/usage-1.md
  merge:
    pages: 65
    deduped: 240
    conflicts_kept_first: 0