DevTune Connection and usage API
The project a credential is bound to, its scopes and features, usage, and code-mode receipts.
The project a credential is bound to, its scopes and features, usage, and code-mode receipts.
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-connection-and-usage-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 Connection and usage 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: Connection and usage
description: The project a credential is bound to, its scopes and features, usage, and code-mode receipts.
paths:
/projects/{projectId}/code-mode/executions/{executionId}:
get:
summary: Get code-mode operation receipts
description: Returns execution status and bounded operation receipts for this same API key and project. Receipts exclude code, arguments and result data. A running or uncertain operation may have committed; never automatically repeat it. Executions are retained with the project. No other credential, including another key in the same account, can read the receipt. Requires the `project.read` scope.
operationId: getCodeModeExecution
x-devtune-required-scope: project.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: executionId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Execution receipt
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
executionId:
type: string
format: uuid
status:
type: string
enum:
- in_progress
- finished
description: in_progress while the execution runs, finished once it has ended.
outcome:
type: string
enum:
- pending
- succeeded
- failed
description: pending while in progress; succeeded or failed once finished.
error:
type: string
description: Public error code when the finished execution failed.
startedAt:
type: string
format: date-time
finishedAt:
type:
- string
- 'null'
format: date-time
description: When the execution ended. Null while it is in progress.
retryable:
type: boolean
const: false
description: 'Always false: never repeat an execution automatically.'
operations:
type: array
maxItems: 13
description: Each DevTune call the code made, in the order it made them.
items:
type: object
properties:
sequence:
type: integer
description: The call’s position in the execution, from 0.
name:
type: string
description: The tool the call used.
write:
type: boolean
description: True when the call can change project data.
argumentsHash:
type: string
description: A SHA-256 hash of the call’s arguments, to tell calls apart; for a webhook creation, of the argument names only. The arguments are not kept.
resourceId:
type: string
format: uuid
description: The record the call read, created or changed, when it names one.
status:
type: string
enum:
- running
- succeeded
- rejected
- uncertain
description: 'running: not finished. succeeded: done. rejected: refused. uncertain: it may have taken effect; check before repeating it.'
startedAt:
type: string
format: date-time
finishedAt:
type: string
format: date-time
description: When the call ended. Absent while it is running.
error:
type: string
description: The public error code of a rejected or uncertain call.
required:
- sequence
- name
- write
- argumentsHash
- status
- startedAt
required:
- outcome
- executionId
- status
- startedAt
- finishedAt
- retryable
- operations
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'
'500':
$ref: '#/components/responses/ServerError'
tags:
- Connection and usage
/connection:
get:
summary: Discover the authorized project
description: Returns the same connection context as the project-bound route, using the project already selected during OAuth consent or bound to the API key. Never lists other projects. Never cached. Requires the `project.read` scope.
operationId: getAuthorizedConnection
security:
- bearerAuth: []
- oauthBearer: []
x-devtune-required-scope: project.read
responses:
'200':
description: Connection context
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ConnectionContextData'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
'500':
$ref: '#/components/responses/ServerError'
tags:
- Connection and usage
/projects/{projectId}/connection:
get:
summary: Get the connection context
description: Returns the project this API key or OAuth grant is bound to, its own domains, the scopes the credential holds now and which account features are on. A paused project keeps only read scopes and setup.write, which can resume it. An operation needs its scope and, where it has one, its feature; neither bypasses humanApproved, credits or the operation's own checks. Never cached. Every API key holds project.read without selecting it. Requires the `project.read` scope.
operationId: getConnectionContext
security:
- bearerAuth: []
- oauthBearer: []
x-devtune-required-scope: project.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: Connection context
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ConnectionContextData'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
'500':
$ref: '#/components/responses/ServerError'
tags:
- Connection and usage
/projects/{projectId}/connection/key:
delete:
summary: Revoke the calling API key
description: Revokes the calling API key. Every later request with it gets 401. Needs only project.read, which every API key holds, and acts on no other key. Works while the project is paused. A claimed agent's dtk_agent_ token revokes the key its claim created, so the token stops working and the agent must register again. An OAuth access token gets 403 with reason not_an_api_key; disconnect it from its client. With Hide revoked off, Settings > API keys shows it as Revoked, without naming who revoked it. Takes no body. Requires the `project.read` scope.
operationId: revokeApiKey
security:
- bearerAuth: []
x-devtune-required-scope: project.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: The revoked key
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/RevokedApiKey'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Connection and usage
/projects/{projectId}/connection/key/rotate:
post:
summary: Rotate the calling API key
description: 'Replaces the calling API key''s secret and returns the new secret once. The key keeps its id, name, scopes, expiry and rate limit window; only the secret changes. Requests already in flight during the rotation count against the old secret. The old secret stops working in the same step: if the response is lost, no working secret is left and a person must create a new key in Settings > API keys. Needs only project.read, which every API key holds, and acts on no other key. The rotation is made as the person who created the key, so it is refused with 403 and reason creator_cannot_create when they no longer have permission to manage API keys for the account, the key has no recorded creator, or their DevTune account is suspended. A claimed agent''s dtk_agent_ token gets 403 with reason agent_token, and an OAuth access token 403 with reason not_an_api_key. If the key is revoked, rotated, deleted or expires while this request runs, it returns 409 with reason key_unavailable; a key that''s already revoked or expired gets 401. A refusal changes nothing. Takes no body. Requires the `project.read` scope.'
operationId: rotateApiKey
security:
- bearerAuth: []
x-devtune-required-scope: project.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: The new key
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/RotatedApiKey'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'409':
$ref: '#/components/responses/ConflictError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Connection and usage
/projects/{projectId}/usage:
get:
summary: Get project status and usage
description: 'Returns whether the project is paused and its usage: active prompts, credits spent this credit period, AI Traffic events this UTC month and tracked pages. Each figure carries its own period. Also returns when the project and its team account are scheduled to be deleted for inactivity. Every API key holds project.read without selecting it. Requires the `project.read` scope.'
operationId: getProjectUsage
x-devtune-required-scope: project.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: Project status and usage
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectUsageData'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Connection and usage
components:
responses:
ServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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'
ConflictError:
description: The request conflicts with the resource's current state. The message, and reason where present, say what conflicts; the endpoint's description lists its reasons. Read the resource again, then change the request. When the body has retryable true, send the same request again. 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'
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'
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'
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
schemas:
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
RevokedApiKey:
type: object
additionalProperties: false
required:
- keyId
- revoked
properties:
keyId:
type: string
format: uuid
revoked:
type: boolean
const: true
ConnectionContextData:
type: object
required:
- project
- credential
- scopes
- features
- checkedAt
properties:
project:
type: object
required:
- id
- name
- paused
- domains
description: The project the credential is bound to.
properties:
id:
type: string
format: uuid
name:
type: string
paused:
type: boolean
description: A paused project gives credentials read access only until it is resumed in the app.
domains:
type: array
maxItems: 500
description: The project's own domains, ordered by domain. Competitor domains are not included.
items:
type: object
required:
- domain
- type
properties:
domain:
type: string
description: Canonical host, with a path when the property lives under one.
type:
type: string
enum:
- docs
- api-ref
- blog
- github
- package
- tutorial
- changelog
- community
- forum
- qna
- social
- review
- examples
- media
- home
- other
description: The kind of site the domain serves, such as docs or blog.
credential:
type: object
required:
- type
description: The credential that made the request.
properties:
type:
type: string
enum:
- api_key
- oauth
- demo
description: api_key for an API key, oauth for an OAuth connection, demo for the public demo token.
scopes:
type: array
items:
type: string
description: Scopes the credential may call now, sorted. A paused project keeps only read scopes and setup.write, which can resume it; an OAuth connection keeps only what both its approved grant and the user's current team permissions allow.
features:
type: object
description: Account features that gate operations independently of scopes. A scope whose feature is off still refuses.
required:
- attributeMatch
- agentPicks
- contentDrafts
- contentPullRequests
- mcpCodeMode
- mcpCodeModeWrites
properties:
attributeMatch:
type: boolean
description: Positioning and Accuracy reads.
agentPicks:
type: boolean
description: Agent Picks reads and settings.
contentDrafts:
type: boolean
description: Action draft reads and starts. Some Agent Picks actions can be drafted without it.
contentPullRequests:
type: boolean
description: Content sources and draft pull requests.
mcpCodeMode:
type: boolean
description: MCP code mode and its execution receipts. True for every account; false for the demo token.
mcpCodeModeWrites:
type: boolean
description: 'Approved project writes in MCP code mode. True for every account, and each write still needs its scope, an executionId and humanApproved: true; false for the demo token.'
checkedAt:
type: string
format: date-time
description: When access was read.
demo:
type: object
required:
- verticals
description: 'Only for the demo token: the public vertical projects it can read. Choose one by projectId or slug in the path, or with ?project= on the MCP endpoint; without one, the first is used.'
properties:
verticals:
type: array
items:
type: object
required:
- projectId
- slug
- name
- category
properties:
projectId:
type: string
format: uuid
slug:
type: string
description: The project slug, such as vertical-observability-monitoring.
name:
type: string
category:
type: string
description: The category the vertical tracks.
RotatedApiKey:
type: object
additionalProperties: false
required:
- key
- keyId
- keyPrefix
- expiresAt
properties:
key:
type: string
description: The new secret, returned only in this response. The old secret already stopped working, so store this before anything else.
keyId:
type: string
format: uuid
description: The key id, unchanged by rotation.
keyPrefix:
type: string
description: The start of the new secret, as Settings > API keys shows it.
expiresAt:
type: string
format: date-time
nullable: true
description: When the key expires, unchanged by rotation; null if it never does.
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
ProjectUsageData:
type: object
required:
- projectId
- paused
- prompts
- credits
- aiTrafficEvents
- trackedPages
- deletion
properties:
projectId:
type: string
format: uuid
paused:
type: boolean
description: A paused project starts no probes, agents, crawls, audits or data syncs and drops new AI Traffic. Credentials keep read access only until it is resumed in the app. Its prompts and project slot do not count against the account while paused.
prompts:
type: object
required:
- active
properties:
active:
type: integer
minimum: 0
credits:
type: object
required:
- used
- periodStart
- periodEnd
description: Credits spent in the account credit period, including credits held by running work until it settles.
properties:
used:
type: number
minimum: 0
periodStart:
type: string
format: date
description: First day of the credit period.
periodEnd:
type: string
format: date
description: Exclusive end of the period.
aiTrafficEvents:
type: object
required:
- count
- periodStart
- periodEnd
description: 'AI Traffic events this UTC calendar month: AI crawler, assistant and answer-fetch requests, plus visits from AI answers. Other human visits are not counted. Across projects this can differ slightly from the account’s usage meter, which counts events as they arrive.'
properties:
count:
type: integer
minimum: 0
periodStart:
type: string
format: date
description: First day of the month.
periodEnd:
type: string
format: date
description: Exclusive end of the period.
trackedPages:
type:
- object
- 'null'
required:
- used
- limit
description: Tracked pages against the page limit. Null until the first page-tracking status is computed.
properties:
used:
type: integer
minimum: 0
limit:
type: integer
minimum: 0
description: The most pages the project can track on its plan.
deletion:
type: object
required:
- projectDeletesAt
- accountDeletesAt
description: When inactive data is scheduled to be deleted. A paused project is deleted six months after it was paused; a team account is deleted after its plan or trial ends, with its projects. Both are null when nothing is scheduled. Resuming the project or resubscribing cancels the deletion.
properties:
projectDeletesAt:
type:
- string
- 'null'
format: date-time
description: When this project will be deleted, or null if it is not scheduled.
accountDeletesAt:
type:
- string
- 'null'
format: date-time
description: When the team account and all its projects will be deleted, or null if it is not scheduled.
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.