DevTune Connection and usage API

The project a credential is bound to, its scopes and features, usage, and code-mode receipts.

GitHub OpenAPI

Operations 6

GET /projects/{projectId}/code-mode/executions/{executionId} Get code-mode operation receipts #
GET /connection Discover the authorized project #
GET /projects/{projectId}/connection Get the connection context #
DELETE /projects/{projectId}/connection/key Revoke the calling API key #
POST /projects/{projectId}/connection/key/rotate Rotate the calling API key #
GET /projects/{projectId}/usage Get project status and usage #

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-connection-and-usage-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-connection-and-usage-api-openapi.yml Raw ↑
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.