LLM Pulse Store Integrations API

The endpoints behind the LLM Pulse app for Shopify: match a store to its project, push the orders AI assistants referred to the store and read them back, and turn catalog products into buyer prompts to track. They need an API key (Scale plan or above) and are not available to accounts with a white-label portal or an embed, which receive ERR_INTEGRATION_UNAVAILABLE (403).

GitHub OpenAPI

Operations 7

GET /store_connection Match a store to a project #
GET /ai_orders Read AI-referred store orders #
PUT /ai_orders Replace AI-referred store orders for a window #
GET /catalog_prompt_suggestions List catalog prompt suggestions #
POST /catalog_prompt_suggestions Suggest buyer prompts from catalog products #
POST /catalog_prompt_suggestions/accept Accept catalog prompt suggestions #
POST /catalog_prompt_suggestions/reject Reject catalog prompt suggestions #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/llmpulse-ai:llmpulse-ai-store-integrations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

llmpulse-ai-store-integrations-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: LLM Pulse Store Integrations API
  description: 'REST API for the LLM Pulse AI visibility platform. Track brand mentions, citations, sentiment, and Share of Voice across AI-generated answers (ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, and optional add-on models). Includes the MCP (Model Context Protocol) endpoint for AI clients. MCP is available on every plan and during eligible trials via OAuth 2.1, with Bearer-token API keys also accepted for headless integrations on the Scale plan or above. Full machine-readable reference at https://llmpulse.ai/api-docs/llms-full.txt. An API key can be limited to one or several projects when it is created, and the set never changes. Such a key sees only those projects: any other project id, domain or name answers ERR_PROJECT_NOT_FOUND exactly like a project that does not exist, listings return only those projects'' rows, and operations on the whole account (creating or deleting a project, the project draft wizard) answer ERR_KEY_PROJECT_SCOPED. Operations carry vendor extensions: x-plan is the plan or entitlement the endpoint requires beyond an API key (growth, scale or reputation_access), x-write marks endpoints that need a read and write key, x-mcp-tool names the MCP tool that returns the same data, x-mcp-plan gives that tool''s plan where it differs, and x-rest-only explains an endpoint with no MCP tool. Parameters are read strictly, on REST and MCP alike: a value outside a documented enum, a boolean other than true, false, 1 or 0, an id or count that is not a plain positive number (12abc, 1.0 or 0), an id of a record the project does not have, or a from later than to answers 422 ERR_INVALID_PARAM naming the parameter, never an ignored filter. A listed value, in a query or a request body, matches in any letter case and is read in its documented spelling (granularity=Week reads as week, aggregation_type=BYPAGE as byPage, event_type=Mention.Created as mention.created). page and per_page keep their own rule: a value that is not a number reads as absent and an out-of-range one is clamped.'
  version: 1.97.0
  contact:
    name: LLM Pulse Support
    url: https://llmpulse.ai
    email: info@llmpulse.ai
  license:
    name: Proprietary
    url: https://llmpulse.ai/terms
servers:
- url: https://api.llmpulse.ai/api/v1
  description: Production API
security:
- BearerAuth: []
tags:
- name: Store Integrations
  description: 'The endpoints behind the LLM Pulse app for Shopify: match a store to its project, push the orders AI assistants referred to the store and read them back, and turn catalog products into buyer prompts to track. They need an API key (Scale plan or above) and are not available to accounts with a white-label portal or an embed, which receive ERR_INTEGRATION_UNAVAILABLE (403).'
paths:
  /store_connection:
    get:
      tags:
      - Store Integrations
      summary: Match a store to a project
      x-llms-description: 'Store app setup: whether the account may use a store integration and which project a store domain maps to, plus candidate projects. Not available to white-label or embed accounts.'
      operationId: getStoreConnection
      x-rest-only: Called by the store app (Shopify) to read its own connection, not by agents.
      description: 'Tells a store app whether the API key''s account can use it and which project the store belongs to: the live project whose domain equals the store domain, else one whose domain is a parent or a subdomain of it, else null. candidates lists every live project of the account so the app can offer a picker. Pitch projects are never matched or listed, since a store is a data connection a pitch project does not take. Takes no project_id. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
      parameters:
      - name: platform
        in: query
        required: true
        schema:
          type: string
          enum:
          - shopify
        description: Store platform
      - name: domain
        in: query
        required: true
        schema:
          type: string
        description: Store domain, with or without scheme, e.g. acme-store.com
      responses:
        '200':
          description: Eligibility, the matching project and the candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreConnectionResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /ai_orders:
    get:
      tags:
      - Store Integrations
      summary: Read AI-referred store orders
      x-llms-description: 'AI-referred store orders and revenue for a project: totals, per AI assistant and a daily series (default last 90 days).'
      operationId: listAiOrders
      x-mcp-tool: get_ai_orders
      x-mcp-plan: growth
      description: 'Reads back the AI-referred orders a store app pushed for a project: totals, one row per AI assistant and a daily series of the days with orders. Revenue values are decimal strings in currency. Team members need read access to AI Traffic. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: platform
        in: query
        schema:
          type: string
          enum:
          - shopify
          default: shopify
        description: Store platform
      - name: from
        in: query
        schema:
          type: string
          format: date
        description: First day (YYYY-MM-DD). Defaults to 89 days before to
      - name: to
        in: query
        schema:
          type: string
          format: date
        description: Last day (YYYY-MM-DD). Defaults to today; the window is at most 400 days
      responses:
        '200':
          description: Totals, per-assistant rows and the daily series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiOrdersResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      tags:
      - Store Integrations
      summary: Replace AI-referred store orders for a window
      x-llms-description: Replace the daily AI-referred orders and revenue a store app reports for a window; raw referrers are classified and non-AI ones ignored.
      operationId: replaceAiOrders
      x-rest-only: Called by the store app (Shopify) to push AI-referred orders; agents read them with get_ai_orders.
      x-write: true
      description: 'Replaces the daily AI-referred orders and revenue of the from..to window. Send the raw referring host or utm_source of each order''s first visit as referrer: LLM Pulse classifies it and ignores anything that is not an AI assistant. Entries for the same day and assistant are summed. Every stored row of that project and platform inside the window is replaced, so pushing the same window again converges instead of counting twice. Rows are kept per project and platform, not per store, so one store reports per project. A pitch project takes no store data: pushing orders to one returns ERR_INVALID_PARAM. Requires a `read_write` scope API key and, for team members, update access to AI Traffic. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiOrdersUpdateRequest'
      responses:
        '200':
          description: Rows stored and entries ignored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiOrdersUpdateResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /catalog_prompt_suggestions:
    get:
      tags:
      - Store Integrations
      summary: List catalog prompt suggestions
      x-llms-description: List buyer prompts suggested from a store catalog, filterable by status and product.
      operationId: listCatalogPromptSuggestions
      x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
      description: Lists the buyer prompts suggested from a store catalog, oldest first, with their status and the product each one came from. Team members need read access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - accepted
          - rejected
        description: Only suggestions in this status
      - name: product_external_id
        in: query
        schema:
          type: string
        description: Only suggestions for this store product id
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 50
          maximum: 100
          minimum: 1
      responses:
        '200':
          description: Paginated suggestions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogPromptSuggestionsResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Store Integrations
      summary: Suggest buyer prompts from catalog products
      x-llms-description: Generate buyer prompt suggestions for up to 20 store catalog products (shares the hourly suggestion allowance).
      operationId: createCatalogPromptSuggestions
      x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
      x-write: true
      description: Writes buyer prompts for up to 20 catalog products and saves them as pending suggestions in the project's Suggested prompts queue, with the product recorded on each. Generation draws on the hourly prompt-suggestion allowance the app also uses (ERR_QUOTA_EXCEEDED once it is used up); a failed generation returns ERR_GENERATION_FAILED (502) and can be retried. Requires a `read_write` scope API key and, for team members, create access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogPromptSuggestionsCreateRequest'
      responses:
        '201':
          description: The suggestions saved for these products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogPromptSuggestionsCreateResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '502':
          $ref: '#/components/responses/GenerationFailed'
  /catalog_prompt_suggestions/accept:
    post:
      tags:
      - Store Integrations
      summary: Accept catalog prompt suggestions
      x-llms-description: Track pending catalog suggestions as prompts, each tagged with a collection named after its product.
      operationId: acceptCatalogPromptSuggestions
      x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
      x-write: true
      description: 'Starts tracking pending suggestions: each one becomes a prompt, tagged with a collection named after its product. Suggestions that are no longer pending come back in skipped. All accepted suggestions must share one country and language. When the new prompts would exceed the plan, the call returns ERR_LIMIT_REACHED and accepts nothing. The prompts of a launched pitch project are fixed, so accepting a suggestion returns ERR_INVALID_PARAM with error.meta.reason pitch_prompts_frozen. Requires a `read_write` scope API key and, for team members, create access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogPromptSuggestionIdsRequest'
      responses:
        '200':
          description: Accepted and skipped suggestions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogPromptSuggestionsAcceptResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /catalog_prompt_suggestions/reject:
    post:
      tags:
      - Store Integrations
      summary: Reject catalog prompt suggestions
      x-llms-description: Mark pending catalog suggestions as rejected.
      operationId: rejectCatalogPromptSuggestions
      x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
      x-write: true
      description: Marks pending suggestions as rejected; suggestions that are no longer pending stay as they are. Requires a `read_write` scope API key and, for team members, update access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogPromptSuggestionIdsRequest'
      responses:
        '200':
          description: How many suggestions were rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogPromptSuggestionsRejectResponse'
        '403':
          $ref: '#/components/responses/IntegrationUnavailable'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    CatalogPromptSuggestionsRejectResponse:
      type: object
      required:
      - project_id
      - rejected
      - request_id
      properties:
        project_id:
          type: integer
        rejected:
          type: integer
        request_id:
          type: string
    CatalogPromptSuggestionsResponse:
      type: object
      required:
      - project_id
      - page
      - per_page
      - total
      - data
      - request_id
      properties:
        project_id:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/CatalogPromptSuggestion'
        request_id:
          type: string
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - ERR_MISSING_AUTH
              - ERR_INVALID_API_KEY
              - ERR_REVOKED_API_KEY
              - ERR_INSUFFICIENT_SCOPE
              - ERR_INSUFFICIENT_PERMISSION
              - ERR_KEY_PROJECT_SCOPED
              - ERR_PLAN_REQUIRED
              - ERR_INTEGRATION_UNAVAILABLE
              - ERR_GENERATION_FAILED
              - ERR_ACCOUNT_INACTIVE
              - ERR_DRAFT_NOT_FOUND
              - ERR_DRAFT_STATE
              - ERR_PROJECT_NOT_FOUND
              - ERR_NOT_FOUND
              - ERR_SEARCH_CONSOLE_NOT_CONNECTED
              - ERR_SEARCH_CONSOLE_ACCESS_REVOKED
              - ERR_SEARCH_CONSOLE_UPSTREAM
              - ERR_CMS_NOT_CONNECTED
              - ERR_CMS_ACCESS_REVOKED
              - ERR_CMS_REJECTED
              - ERR_CMS_UPSTREAM
              - ERR_AI_TRAFFIC_NOT_CONNECTED
              - ERR_WEB_ANALYTICS_NOT_CONNECTED
              - ERR_WEB_ANALYTICS_INVALID_QUERY
              - ERR_WEB_ANALYTICS_ACCESS_REVOKED
              - ERR_WEB_ANALYTICS_UPSTREAM
              - ERR_AGENT_TRAFFIC_NOT_CONNECTED
              - ERR_INVALID_PARAM
              - ERR_INVALID_RANGE
              - ERR_LIMIT_REACHED
              - ERR_QUOTA_EXCEEDED
              - ERR_STALE_CONTENT
              - ERR_RATE_LIMITED
            message:
              type: string
            meta:
              type: object
              description: Extra detail for some codes. A not-connected or access-revoked error from the Search Console, AI traffic, web analytics or agent traffic endpoints carries connect_url, the in-app page where the user connects or reconnects the source. A prompt write refused because a launched pitch project's prompts are fixed carries reason pitch_prompts_frozen.
        request_id:
          type: string
    CatalogPromptSuggestionsCreateResponse:
      type: object
      required:
      - project_id
      - created
      - skipped
      - data
      - request_id
      properties:
        project_id:
          type: integer
        created:
          type: integer
        skipped:
          type: integer
          description: Generated prompts not saved because the project already holds them as a suggestion (from any source or product, in any status).
        data:
          type: array
          items:
            $ref: '#/components/schemas/CatalogPromptSuggestion'
        request_id:
          type: string
    AiOrdersUpdateRequest:
      type: object
      required:
      - project_id
      - platform
      - currency
      - from
      - to
      - days
      properties:
        project_id:
          type: integer
        platform:
          type: string
          enum:
          - shopify
        currency:
          type: string
          description: ISO 4217 code, e.g. EUR
        from:
          type: string
          format: date
          description: First day of the window this push replaces
        to:
          type: string
          format: date
          description: Last day of the window; at most 400 days after from
        days:
          type: array
          maxItems: 400
          items:
            type: object
            required:
            - day
            - referrer
            - orders
            - revenue
            properties:
              day:
                type: string
                format: date
                description: Must fall inside from..to
              referrer:
                type: string
                description: Raw referring host or utm_source of the order's first visit, e.g. chatgpt.com. Entries that are not an AI assistant are ignored
              orders:
                type: integer
                minimum: 0
              revenue:
                type: string
                description: Non-negative decimal amount in currency, e.g. 120.50. A JSON number is accepted too
    CatalogProduct:
      type: object
      required:
      - external_id
      - title
      properties:
        external_id:
          type: string
          description: The store's product id, e.g. gid://shopify/Product/1
        title:
          type: string
        handle:
          type: string
        product_type:
          type: string
        vendor:
          type: string
        tags:
          type: array
          maxItems: 20
          items:
            type: string
        collections:
          type: array
          maxItems: 20
          items:
            type: string
        url:
          type: string
    CatalogPromptSuggestionIdsRequest:
      type: object
      required:
      - project_id
      - ids
      properties:
        project_id:
          type: integer
        ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: integer
    CatalogPromptSuggestionsCreateRequest:
      type: object
      required:
      - project_id
      - platform
      - products
      properties:
        project_id:
          type: integer
        platform:
          type: string
          enum:
          - shopify
        country_code:
          type: string
          description: Defaults to the project country
        language_code:
          type: string
          description: Defaults to the project language
        products:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/CatalogProduct'
    CatalogPromptSuggestionsAcceptResponse:
      type: object
      required:
      - project_id
      - accepted
      - skipped
      - prompts_available
      - request_id
      properties:
        project_id:
          type: integer
        accepted:
          type: array
          items:
            type: object
            required:
            - suggestion_id
            - prompt_id
            - collection_id
            properties:
              suggestion_id:
                type: integer
              prompt_id:
                type: integer
              collection_id:
                type:
                - integer
                - 'null'
                description: The collection named after the product; null when the product has no title or the team member cannot create tags
        skipped:
          type: array
          items:
            type: object
            required:
            - suggestion_id
            - reason
            properties:
              suggestion_id:
                type: integer
              reason:
                type: string
                description: accepted or rejected (the suggestion was no longer pending), or pending_deletion
        prompts_available:
          type:
          - integer
          - 'null'
          description: Prompt slots left on the plan; null when unlimited
        request_id:
          type: string
    StoreConnectionResponse:
      type: object
      required:
      - platform
      - domain
      - project
      - ambiguous
      - candidates
      - account
      - request_id
      properties:
        platform:
          type: string
          description: The store platform, e.g. shopify
        domain:
          type: string
          description: 'The store domain as compared: lowercase, without scheme, www or path'
        project:
          type:
          - object
          - 'null'
          description: 'The live project the store maps to: its domain equals the store''s, or is a parent or subdomain of it. Null when no project matches'
          required:
          - id
          - name
          - domain
          properties:
            id:
              type: integer
            name:
              type: string
            domain:
              type: string
            country_code:
              type:
              - string
              - 'null'
            language_code:
              type:
              - string
              - 'null'
        ambiguous:
          type: boolean
          description: True when several live projects match the store domain (for example one project per market). project is then null and the app asks the key holder to pick from candidates.
        candidates:
          type: array
          description: Every live project of the account, for a project picker
          items:
            type: object
            required:
            - id
            - name
            - domain
            properties:
              id:
                type: integer
              name:
                type: string
              domain:
                type: string
                description: Empty when the project has no website URL
        account:
          type: object
          properties:
            plan:
              type:
              - string
              - 'null'
              description: Internal plan key of the account, e.g. scale or scaleplus; null for a key limited to some projects
        request_id:
          type: string
    CatalogPromptSuggestion:
      type: object
      required:
      - id
      - prompt
      - status
      - source
      - country_code
      - language_code
      - product
      - prompt_id
      - accepted_at
      - created_at
      properties:
        id:
          type: integer
        prompt:
          type: string
        status:
          type: string
          description: pending, accepted or rejected
        source:
          type: string
          description: Always catalog
        country_code:
          type:
          - string
          - 'null'
        language_code:
          type:
          - string
          - 'null'
        product:
          type: object
          description: The catalog product the suggestion was written for
          properties:
            external_id:
              type:
              - string
              - 'null'
              description: The store's product id, e.g. gid://shopify/Product/1
            handle:
              type:
              - string
              - 'null'
            title:
              type:
              - string
              - 'null'
        prompt_id:
          type:
          - integer
          - 'null'
          description: The tracked prompt an accepted suggestion became; null until accepted
        accepted_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the suggestion was accepted; null until then
        created_at:
          type: string
          format: date-time
    AiOrdersUpdateResponse:
      type: object
      required:
      - project_id
      - platform
      - stored
      - ignored
      - request_id
      properties:
        project_id:
          type: integer
        platform:
          type: string
        stored:
          type: integer
          description: Rows stored, one per day and AI assistant
        ignored:
          type: integer
          description: Entries whose referrer is not an AI assistant
        request_id:
          type: string
    AiOrdersResponse:
      type: object
      required:
      - project_id
      - platform
      - currency
      - from
      - to
      - totals
      - by_source
      - series
      - request_id
      properties:
        project_id:
          type: integer
        platform:
          type: string
        currency:
          type:
          - string
          - 'null'
          description: ISO 4217 code of the most recent stored day; null when the window holds no stored order
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        totals:
          type: object
          required:
          - orders
          - revenue
          properties:
            orders:
              type: integer
            revenue:
              type: string
              description: Decimal amount with two decimals, e.g. 1834.20
        by_source:
          type: array
          description: One row per AI assistant, highest revenue first
          items:
            type: object
            required:
            - source
            - name
            - orders
            - revenue
            properties:
              source:
                type: string
                description: AI assistant slug, e.g. chatgpt or perplexity
              name:
                type: string
                description: Display name, e.g. ChatGPT
              orders:
                type: integer
              revenue:
                type: string
        series:
          type: array
          description: Days that have stored orders, oldest first
          items:
            type: object
            required:
            - day
            - orders
            - revenue
            properties:
              day:
                type: string
                format: date
              orders:
                type: integer
              revenue:
                type: string
        request_id:
          type: string
  responses:
    UnprocessableEntity:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INVALID_PARAM
              message: invalid metrics
            request_id: abc-123
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_PROJECT_NOT_FOUND
              message: project_not_found
            request_id: abc-123
    GenerationFailed:
      description: The AI generation failed; retry the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_GENERATION_FAILED
              message: suggestions could not be generated, try again
            request_id: abc-123
    IntegrationUnavailable:
      description: The account has a white-label portal or an embed, so store integrations are not available (ERR_INTEGRATION_UNAVAILABLE). Writes with a read-only key answer ERR_INSUFFICIENT_SCOPE, and a team member without the permission ERR_INSUFFICIENT_PERMISSION, with the same status
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INTEGRATION_UNAVAILABLE
              message: Store integrations are not available for white-label or embed accounts
            request_id: abc-123
  parameters:
    ProjectId:
      name: project_id
      in: query
      required: true
      schema:
        type: integer
      description: Project ID
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Keys are managed at https://llmpulse.ai/app/api_keys (Scale plan or above). Used for the REST API and as a headless option for /mcp. A key can be limited to one or several projects when it is created; the set cannot be changed later.
    OAuth2:
      type: oauth2
      description: OAuth 2.1 with PKCE-S256 and Dynamic Client Registration. Accepted on /mcp only, available on every plan and during eligible trials. Discovery metadata at /.well-known/oauth-authorization-server.
      flows:
        authorizationCode:
          authorizationUrl: https://api.llmpulse.ai/oauth/authorize
          tokenUrl: https://api.llmpulse.ai/oauth/token
          scopes:
            mcp:read: Read data via MCP tools
            mcp:write: Create resources via MCP write tools