DevTune Positioning API

How well AI answers match your positioning statements.

GitHub OpenAPI

Operations 3

GET /projects/{projectId}/positioning Get positioning match #
GET /projects/{projectId}/positioning/statements List positioning statements #
GET /projects/{projectId}/positioning/statements/{statementId}/answers List positioning match answers #

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/devtune:devtune-positioning-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

devtune-positioning-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: DevTune Positioning API
  version: 2.0.0
  description: API for programmatic access to your AI visibility data, webhook subscriptions, and automation workflows. Use this API to integrate DevTune data into CI/CD pipelines, BI tools, AI agents, and operational systems.
servers:
- url: https://devtune.ai/api/v2
  description: Production
security:
- bearerAuth: []
tags:
- name: Positioning
  description: How well AI answers match your positioning statements.
paths:
  /projects/{projectId}/positioning:
    get:
      summary: Get positioning match
      description: Returns positioning counts, resolved brand names, daily counts and share_of_statement. Share is the primary brand count divided by brand_counts plus another_product, excluding several and nobody. Below ten named-product assignments the share is null. Each statement also carries prior_status and, when that is comparable, the previous window’s totals, for a change against the window of the same length before it. prior_status is comparable when both windows measured the current competitor set and the previous one was scored on every day, platform and intent it had eligible answers for; otherwise it is competitor_changed or incomplete and prior is null. Competitor changes and the series start date identify the comparison period. Requires the `positioning.read` scope.
      operationId: getPositioning
      x-devtune-required-scope: positioning.read
      parameters:
      - name: projectId
        in: path
        required: true
        description: The project the credential is bound to. Read it from GET /connection.
        schema:
          type: string
          format: uuid
      - name: window
        in: query
        schema:
          type: integer
          enum:
          - 30
          - 90
          default: 30
      - name: platform
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: intent
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 100
      responses:
        '200':
          description: Positioning
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PositioningData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - data
                - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      tags:
      - Positioning
  /projects/{projectId}/positioning/statements:
    get:
      summary: List positioning statements
      description: Returns id, kind, statement, relevant_intents, status and created_at for active and archived positioning statements. Requires the `positioning.read` scope.
      operationId: listPositioningStatements
      x-devtune-required-scope: positioning.read
      parameters:
      - name: projectId
        in: path
        required: true
        description: The project the credential is bound to. Read it from GET /connection.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Positioning
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PositioningStatementListData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - data
                - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      tags:
      - Positioning
  /projects/{projectId}/positioning/statements/{statementId}/answers:
    get:
      summary: List positioning match answers
      description: 'Lists the AI answers behind one positioning match cell, newest first: accepted verdicts for the statement and assignee over the same window, filters and current competitor set as getPositioning, so the number of answers equals that cell. A statement that is a fact, proposed, dismissed or not in this project returns 404. Verdicts carry no quote; read the answer itself for the wording. Pass pagination.nextCursor as cursor while pagination.hasMore. A page of exactly 100 rows reports more even when it is the last, so the following page can be empty. Requires the `positioning.read` scope.'
      operationId: listPositioningAnswers
      x-devtune-required-scope: positioning.read
      parameters:
      - name: projectId
        in: path
        required: true
        description: The project the credential is bound to. Read it from GET /connection.
        schema:
          type: string
          format: uuid
      - name: statementId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: assignee
        in: query
        required: true
        description: 'Who the cell credits: a brand id, or another_product, several or nobody.'
        schema:
          type: string
      - name: window
        in: query
        schema:
          type: integer
          enum:
          - 30
          - 90
          default: 30
      - name: platform
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: intent
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: cursor
        in: query
        description: nextCursor from the previous page, verbatim.
        schema:
          type: string
          maxLength: 200
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        description: The same setting as limit. Send either; both with different values returns 400.
      responses:
        '200':
          description: Positioning answers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PositioningAnswersData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - data
                - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      tags:
      - Positioning
components:
  responses:
    BadRequestError:
      description: 'The request is invalid: a parameter or body field is missing, has the wrong type or is out of range, or a cursor doesn''t match this list. The message says which; reason, where present, is listed in the endpoint''s description. Fix the request before retrying, and restart a list without its cursor. See [Errors](/api-reference/errors).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: 'The request has no valid credential: the Authorization header is missing or malformed, or the API key or OAuth token is invalid, expired or revoked. Send `Authorization: Bearer <API key>` with an active key, or sign in again to get a new OAuth token. See [Errors](/api-reference/errors).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: The resource doesn't exist in this project, was deleted, or the credential can't see it. Check the IDs in the path, and that the projectId is the project the credential is bound to. See [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: 'The credential is valid but can''t make this request. The message says which cause applies: the key or sign-in lacks the scope this endpoint requires (named in the message), it belongs to another project, the plan doesn''t include API access or this feature, the project is paused (a paused project keeps only read scopes and setup.write), or the member a write acts as no longer has the role it needs. Read `GET /projects/{projectId}/connection` for the credential''s current scopes and features, then use a key that has the scope, sign in again and approve it, or upgrade the plan. See [Errors](/api-reference/errors).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceededError:
      description: 'Too many requests from this credential in the current window. The request was refused before it took effect, so it is safe to retry: wait the seconds in Retry-After, then send it again. Endpoints that start agent runs have a stricter limit. See [Rate limits](/api-reference/rate-limits).'
      headers:
        Retry-After:
          description: Seconds to wait before retrying a 429 or retryable 503 response.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PositioningMatchCell:
      type: object
      description: Which brands AI answers give one positioning statement to, over the window or one day.
      properties:
        statement_id:
          type: string
          format: uuid
        statement:
          type: string
          description: 'The positioning statement: the customer''s own wording, or a DevTune suggestion the customer approved.'
        kind:
          type: string
          enum:
          - positioning
        status:
          type: string
          enum:
          - active
          - archived
          description: active while answers are checked against the statement; archived when it is no longer checked and keeps its history.
        series_started_on:
          type: string
          format: date
          description: The first day in the window with results for the statement under the current competitor set. The window’s first day when there are none.
        eligible:
          type: integer
          minimum: 0
          description: Successful AI answers that mention a tracked brand, from prompts with an intent the statement covers, under the filters. On statement totals, only days, platforms and intents with answers scored under the current competitor set count.
        scored:
          type: integer
          minimum: 0
          description: Answers checked against the statement, abstained ones included.
        abstained:
          type: integer
          minimum: 0
          description: Of scored, answers the check was not confident enough to show.
        brand_counts:
          type: object
          description: Shown answers that give the statement to each tracked brand, keyed by brand id.
          additionalProperties:
            type: integer
            minimum: 0
        another_product:
          type: integer
          minimum: 0
          description: Shown answers that give the statement to a product DevTune does not track.
        several:
          type: integer
          minimum: 0
          description: Shown answers that give the statement to several products.
        nobody:
          type: integer
          minimum: 0
          description: Shown answers that give the statement to no product.
        brands:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type:
                - string
                - 'null'
                description: The brand name. Null when the brand has been removed.
            required:
            - id
            - name
          description: The brands in brand_counts, with their names.
        share_of_statement:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
          description: Primary brand count divided by brand_counts plus another_product. Null below ten assignments or when the primary brand is unavailable.
        day:
          type: string
          format: date
          description: Present on daily cells.
        prior_status:
          type: string
          enum:
          - comparable
          - competitor_changed
          - incomplete
          description: 'On statement totals only: whether the previous window of the same length compares with this one. competitor_changed: either window has answers scored against another competitor set. incomplete: the previous window has a day, platform and intent with eligible answers and none scored, or no eligible answers at all.'
        prior:
          type:
          - object
          - 'null'
          description: 'On statement totals only: the previous window’s totals for the current competitor set, under the same filters. Null unless prior_status is comparable, so a change is never computed against a different set or a partly scored window.'
          properties:
            scored:
              type: integer
              minimum: 0
              description: Answers checked against the statement.
            brand_counts:
              type: object
              description: Shown answers that give the statement to each tracked brand, keyed by brand id.
              additionalProperties:
                type: integer
                minimum: 0
            another_product:
              type: integer
              minimum: 0
              description: Shown answers that give the statement to a product DevTune does not track.
            several:
              type: integer
              minimum: 0
              description: Shown answers that give the statement to several products.
            nobody:
              type: integer
              minimum: 0
              description: Shown answers that give the statement to no product.
            share_of_statement:
              type:
              - number
              - 'null'
              minimum: 0
              maximum: 1
              description: The primary brand’s share in the previous window, computed as share_of_statement is. Null below ten assignments.
          required:
          - scored
          - brand_counts
          - another_product
          - several
          - nobody
          - share_of_statement
      required:
      - statement_id
      - statement
      - kind
      - status
      - series_started_on
      - eligible
      - scored
      - abstained
      - brand_counts
      - another_product
      - several
      - nobody
      - brands
      - share_of_statement
    PositioningAnswersData:
      type: object
      required:
      - window
      - statementId
      - assignee
      - answers
      - nextCursor
      - pagination
      properties:
        pagination:
          $ref: '#/components/schemas/ListPagination'
        window:
          type: integer
          enum:
          - 30
          - 90
        statementId:
          type: string
          format: uuid
        assignee:
          type: string
          description: A brand id, or another_product, several or nobody, as requested.
        answers:
          type: array
          description: The shown answers that gave the statement to assignee.
          items:
            type: object
            required:
            - executionId
            - promptId
            - prompt
            - promptDeleted
            - platform
            - intent
            - date
            - confidence
            properties:
              executionId:
                type: string
                format: uuid
              promptId:
                type:
                - string
                - 'null'
                format: uuid
                description: The tracked prompt the answer came from.
              prompt:
                type:
                - string
                - 'null'
                description: The prompt text. Null when the prompt is no longer recorded.
              promptDeleted:
                type: boolean
                description: The prompt has since been removed.
              platform:
                type: string
              intent:
                type: string
                description: The prompt’s intent, such as pricing_commercial.
              date:
                type: string
                format: date
                description: The run day of the answer.
              confidence:
                type: number
                minimum: 0
                maximum: 1
                description: How sure the check was of the verdict, from 0 to 1.
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass verbatim as cursor for the next page, with the other parameters unchanged. Null on the last page.
    Meta:
      type: object
      description: Sent beside data on every successful response that returns data.
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the response was produced.
        projectId:
          type: string
          format: uuid
    PositioningStatement:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - positioning
        statement:
          type: string
          description: 'The positioning statement: the customer''s own wording, or a DevTune suggestion the customer approved.'
        relevant_intents:
          type:
          - array
          - 'null'
          description: The prompt intents whose answers are checked against the statement, such as comparison_evaluation. Null when every intent is.
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - archived
          description: active while answers are checked against the statement; archived when it is no longer checked and keeps its history.
        created_at:
          type: string
          format: date-time
      required:
      - id
      - kind
      - statement
      - relevant_intents
      - status
      - created_at
    ListPagination:
      type: object
      properties:
        hasMore:
          type: boolean
          description: More rows follow this page.
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as cursor to read the next page. Null on the last page.
      required:
      - hasMore
      - nextCursor
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code, such as bad_request, unauthorized, forbidden, not_found, conflict, payment_required, rate_limit_exceeded or internal_error. Some endpoints return their own codes, listed in their descriptions.
        message:
          type: string
          description: What went wrong, for a person to read. Do not parse it; use error and reason.
        reason:
          type: string
          description: Why the request was refused, for an error with more than one cause, such as a refused content-draft start.
        details:
          type: object
          additionalProperties: true
          description: Machine-readable facts about the failure or refusal, such as retryable or shortfall_credits.
          properties:
            retryable:
              type: boolean
              description: 'Read this field before retrying. Present on every 5xx and 429 response: true when another attempt may succeed, false for a permanent refusal even on a 5xx. Other refusals may also provide this field.'
            retryAfterSeconds:
              type: integer
              minimum: 1
              description: Seconds to wait when retryable is true on a 429 or 503 response, also sent in Retry-After. Uses the provider retry time or limiter reset when available; otherwise 60 seconds for 429 and GitHub throttles or 30 seconds for other 503 responses. GitHub secondary limits wait at least 60 seconds.
        status:
          type: integer
          description: The HTTP status code, repeated in the body.
      required:
      - error
      - message
      - status
    PositioningMatchDailyCell:
      allOf:
      - $ref: '#/components/schemas/PositioningMatchCell'
      - type: object
        properties:
          competitor_set_id:
            type: string
            format: uuid
            description: Competitor set used for this trend point. The zero UUID means no competitor set was recorded.
          is_current_set:
            type: boolean
            description: Whether this trend point uses the current competitor set.
        required:
        - day
        - competitor_set_id
        - is_current_set
    PositioningStatementListData:
      type: object
      properties:
        competitors:
          type: array
          maxItems: 5
          description: Effective ordered positioning competitors, including those with no matches. Uses the saved choice, or the first five configured competitors when no eligible choice remains.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
            required:
            - id
            - name
        statements:
          type: array
          description: The project’s active and archived positioning statements.
          items:
            $ref: '#/components/schemas/PositioningStatement'
      required:
      - statements
      - competitors
    PositioningData:
      type: object
      properties:
        current_set_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Current competitor set covered by the totals, or null when no set is recorded.
        window:
          type: object
          description: The run days the totals cover.
          properties:
            days:
              type: integer
              enum:
              - 30
              - 90
            from:
              type: string
              format: date
              description: First day of the window.
            to:
              type: string
              format: date
              description: Last day of the window, included.
          required:
          - days
          - from
          - to
        prior_window:
          type: object
          description: The window of the same length that ends the day before window.from. Each statement’s prior_status says whether it compares.
          properties:
            from:
              type: string
              format: date
              description: First day of the previous window.
            to:
              type: string
              format: date
              description: Last day of the previous window, included.
          required:
          - from
          - to
        series_started_on:
          type: string
          format: date
          description: The first day in the window with results under the current competitor set. window.from when there are none.
        competitor_changes:
          type: array
          description: Days in the window when the competitor set changed. Results across a change do not compare.
          items:
            type: string
            format: date
        statements:
          type: array
          description: One total for each active or archived statement with results in the window, under the filters. A statement with none is left out.
          items:
            $ref: '#/components/schemas/PositioningMatchCell'
        daily:
          type: array
          description: Each trend point identifies its competitor set. A day can contain multiple points for the same statement. Keep sets separate and show a break when competitors change, rather than a jump.
          items:
            $ref: '#/components/schemas/PositioningMatchDailyCell'
      required:
      - current_set_id
      - window
      - series_started_on
      - competitor_changes
      - statements
      - daily
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the window resets
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in current window
      schema:
        type: integer
  securitySchemes:
    oauthBearer:
      type: http
      scheme: bearer
      description: Project-granted OAuth access token from the authorization server advertised at /.well-known/oauth-protected-resource/api/v2. Uses the same browser consent and current project permissions as MCP. Only operations explicitly listing oauthBearer accept these tokens.
    agentBearer:
      type: http
      scheme: bearer
      description: Access token from an unclaimed agent registration (dtk_agent_ prefix), holding only setup.draft. Register at /agent/identity and exchange the identity assertion at /oauth2/token, as /auth.md describes. Only operations listing agentBearer accept it. Once a person claims the registration, its tokens act as the claimed API key under bearerAuth instead.
    bearerAuth:
      type: http
      scheme: bearer
      description: API key with dtk_live_ prefix. Obtain it from API Keys in the account sidebar. New keys start with all supported scopes selected for the chosen project, and you can narrow them to specific read/write scopes as needed.