DevTune Positioning API
How well AI answers match your positioning statements.
Operations 3
GET
/projects/{projectId}/positioning/statements/{statementId}/answers
List positioning match answers
#
How well AI answers match your positioning statements.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/devtune:devtune-positioning-api"
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.
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: 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.