DevTune Agent registration API

Setup drafts for an unclaimed agent registration.

GitHub OpenAPI

Operations 4

GET /agent/setup-draft Get the agent setup draft #
PUT /agent/setup-draft Replace the agent setup draft #
GET /agent/catalogue/agent-picks Get the Agent Picks catalogue for a draft #
GET /agent/catalogue/platforms Get the AI platform catalogue for a draft #

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-agent-registration-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-agent-registration-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: DevTune Agent registration 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: Agent registration
  description: Setup drafts for an unclaimed agent registration.
paths:
  /agent/setup-draft:
    get:
      summary: Get the agent setup draft
      description: Reads the setup draft of the unclaimed agent registration the token belongs to. A claimed or expired registration has none (404 registration_unavailable). Takes an agent access token, not an API key. Takes no query parameters. Requires the `setup.draft` scope.
      operationId: getAgentSetupDraft
      x-devtune-required-scope: setup.draft
      security:
      - agentBearer: []
      responses:
        '200':
          description: The draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentSetupDraftState'
                  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:
      - Agent registration
    put:
      summary: Replace the agent setup draft
      description: 'Replaces the draft whole. It validates as the post-claim API would: the Agent Picks setup and job as saveAgentPicksSetup and saveAgentPicksJob accept them, with ids in the published catalogue. A refused draft is 400 invalid_draft naming the first problem. Takes an agent access token, not an API key. Requires the `setup.draft` scope.'
      operationId: saveAgentSetupDraft
      x-devtune-required-scope: setup.draft
      security:
      - agentBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentSetupDraft'
      responses:
        '200':
          description: The saved draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentSetupDraftState'
                  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:
      - Agent registration
  /agent/catalogue/agent-picks:
    get:
      summary: Get the Agent Picks catalogue for a draft
      description: Lists the published categories with their active tools, the test apps agents start in and the agents with their models that a draft’s Agent Picks section may name. Which agents a plan includes is known only after the claim. Takes an agent access token, not an API key. Takes no query parameters. Requires the `setup.draft` scope.
      operationId: getPublicAgentPicksCatalogue
      x-devtune-required-scope: setup.draft
      security:
      - agentBearer: []
      responses:
        '200':
          description: The catalogue
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentPicksPublicCatalogue'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - data
                - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      tags:
      - Agent registration
  /agent/catalogue/platforms:
    get:
      summary: Get the AI platform catalogue for a draft
      description: Lists the AI platforms DevTune probes, in display order. Which ones a plan includes is known only after the claim. Takes an agent access token, not an API key. Takes no query parameters. Requires the `setup.draft` scope.
      operationId: getPublicSearchPlatformCatalogue
      x-devtune-required-scope: setup.draft
      security:
      - agentBearer: []
      responses:
        '200':
          description: The platforms
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SearchPlatformPublicCatalogue'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - data
                - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      tags:
      - Agent registration
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:
    AgentSetupDraftState:
      type: object
      additionalProperties: false
      required:
      - draft
      - updated_at
      - expires_at
      properties:
        draft:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/AgentSetupDraft'
          description: null until a draft is saved.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the draft was last saved. Null until one is.
        expires_at:
          type: string
          format: date-time
          description: When the unclaimed registration expires. The next hourly cleanup deletes it with its draft and claim attempts.
    SetupAgentPicksCatalogue:
      type: object
      additionalProperties: false
      required:
      - categories
      - environments
      - agents
      - max_competitor_tool_keys
      - max_agent_models
      properties:
        categories:
          type: array
          description: Published categories, by name. Their ids are the category_id saveAgentPicksSetup and the source_category_id saveAgentPicksJob accept.
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - slug
            - name
            - tools
            properties:
              id:
                type: string
                format: uuid
              slug:
                type: string
                description: The category slug; setup selectors accept it.
              name:
                type: string
              tools:
                type: array
                description: 'The category’s active tools, by display name: the tool_key and competitor_tool_keys a setup in this category may name.'
                items:
                  type: object
                  additionalProperties: false
                  required:
                  - tool_key
                  - display_name
                  - brand_domain
                  properties:
                    tool_key:
                      type: string
                      description: The key setups and results use for the tool.
                    display_name:
                      type: string
                    brand_domain:
                      type:
                      - string
                      - 'null'
                      description: The tool’s own website domain. Null when none is recorded.
        environments:
          type: array
          description: 'The test apps agents start in that the setup wizard offers for environment_ids, by name. One with category_ids is valid only with those categories. A retired test app is not listed: a new setup cannot add it, and a setup that already holds it keeps it.'
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            - framework
            - default_selected
            - prompt_prefix
            - starts_with
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              framework:
                type:
                - string
                - 'null'
                description: null for the empty folder.
              default_selected:
                type: boolean
                description: 'Whether a new setup includes the test app. false for a test app offered unticked, such as one with hosting or requirements: include its id in environment_ids to test it.'
              prompt_prefix:
                type:
                - string
                - 'null'
                description: What agents are told before every request in this test app, such as a requirement the team has. Null when they are told nothing extra.
              starts_with:
                type:
                - string
                - 'null'
                description: The host whose own deploy setup the project starts with, by name. Null for a plain starter.
              category_ids:
                type: array
                items:
                  type: string
                  format: uuid
                description: 'Present only for a test app that runs in some categories: the published categories it may be saved with. Absent means every category.'
        agents:
          type: array
          description: The agents a setup may test, each with the models agent_models accepts for it.
          items:
            type: object
            additionalProperties: false
            required:
            - agent
            - name
            - included_in_plan
            - models
            properties:
              agent:
                type: string
                description: The agent key, such as claude_code.
              name:
                type: string
              included_in_plan:
                type: boolean
                description: 'false when the account’s Agent Picks plan does not include the agent: saving it is refused with 403 agent_not_in_plan.'
              models:
                type: array
                description: The model ids agent_models accepts for the agent.
                items:
                  type: string
        max_competitor_tool_keys:
          type: integer
          minimum: 1
          description: The most competitor_tool_keys a setup may save.
        max_agent_models:
          type: integer
          minimum: 1
          description: The most agent_models entries a setup may save.
    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
    AgentSetupDraft:
      type: object
      additionalProperties: false
      required:
      - product
      description: An unclaimed agent registration’s project setup, replaced whole. visibility is required for ai-search and both and refused otherwise; agent_picks is required for agent-picks and both and refused otherwise. Probed platforms are not part of a draft. Plan limits are applied when a person claims the registration.
      properties:
        product:
          description: 'What the project is set up for: ai-search, agent-picks or both.'
          type: string
          enum:
          - ai-search
          - agent-picks
          - both
        trial_plan:
          type:
          - string
          - 'null'
          description: 'The Agent Picks plan a new account’s trial starts on: local-runner (Local Runner monthly) or a Local Runner price id, at one project and with no units; cloud (Cloud monthly at 100 credits), a Cloud price id, or a Cloud price id and its units of 20 credits, such as price_…:9 for 180 credits. The retired plus and pro, and their price ids, select Cloud at 100 and 180 credits. Rejected for ai-search. For agent-picks a new account’s trial starts on it; for both it is accepted but not used. Null when none is chosen.'
        visibility:
          description: The AI search setup. Null unless product is ai-search or both.
          nullable: true
          type: object
          additionalProperties: false
          required:
          - domain
          properties:
            domain:
              type: string
              minLength: 1
              maxLength: 2048
              description: The project's website domain.
            brand_context:
              description: A description of the company. Null when none is given.
              type:
              - string
              - 'null'
              minLength: 20
              maxLength: 10000
            competitors:
              type: array
              maxItems: 25
              description: Under both, the one competitor list both products share.
              items:
                type: object
                additionalProperties: false
                required:
                - name
                - urls
                properties:
                  name:
                    type: string
                    minLength: 1
                    maxLength: 100
                  urls:
                    description: The competitor's website URLs.
                    type: array
                    minItems: 1
                    maxItems: 10
                    items:
                      type: string
                      minLength: 1
                      maxLength: 2048
            prompts:
              description: Prompts to track, as written.
              type: array
              maxItems: 50
              items:
                type: string
                minLength: 10
                maxLength: 1000
        agent_picks:
          description: 'The Agent Picks setup: a public category''s setup (use_category) or the project''s own job (start_from_scratch). Null unless product is agent-picks or both.'
          nullable: true
          oneOf:
          - type: object
            additionalProperties: false
            required:
            - starting_point
            - setup
            properties:
              starting_point:
                type: string
                const: use_category
              setup:
                type: object
                description: The body saveAgentPicksSetup accepts, with ids from getPublicAgentPicksCatalogue.
          - type: object
            additionalProperties: false
            required:
            - starting_point
            - job
            properties:
              starting_point:
                type: string
                const: start_from_scratch
              job:
                type: object
                description: The body saveAgentPicksJob accepts, with ids from getPublicAgentPicksCatalogue.
    AgentPicksPublicCatalogue:
      type: object
      additionalProperties: false
      required:
      - categories
      - environments
      - agents
      - max_competitor_tool_keys
      - max_agent_models
      description: 'The Agent Picks catalogue a draft may name: getAgentPicksCatalogue without included_in_plan, since a registration has no account until it is claimed.'
      properties:
        categories:
          $ref: '#/components/schemas/SetupAgentPicksCatalogue/properties/categories'
        environments:
          $ref: '#/components/schemas/SetupAgentPicksCatalogue/properties/environments'
        agents:
          description: The coding agents a setup can test, with their models.
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - agent
            - name
            - models
            properties:
              agent:
                type: string
              name:
                type: string
              models:
                type: array
                items:
                  type: string
                description: The models a setup can pair with the agent.
        max_competitor_tool_keys:
          type: integer
          minimum: 1
          description: The most competitor tools a setup can name.
        max_agent_models:
          type: integer
          minimum: 1
          description: The most agent and model pairs a setup can save.
    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
    SearchPlatformPublicCatalogue:
      type: object
      additionalProperties: false
      required:
      - platforms
      properties:
        platforms:
          type: array
          description: The AI platforms DevTune probes, in display order.
          items:
            type: object
            additionalProperties: false
            required:
            - platform
            - name
            properties:
              platform:
                type: string
              name:
                type: string
  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.