> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft a new project for a person to claim

> Starts the auth.md registration and claim from this connection, for another product or brand: the credential stays bound to its own project. Takes the person's sign-in email and a whole setup draft, in the shape PUT /agent/setup-draft takes. No project exists and nothing is spent until the person claims it. Give the person claim_attempt.verification_uri and claim_attempt.user_code; they sign in with that email, review the draft on the claim page and confirm it into their account, where plan limits are applied. Poll token_endpoint with grant_type and claim_token for the new project's access token. The draft cannot be read or changed afterwards; another call starts a second registration. Agent Picks ids must be ones GET /projects/{projectId}/setup/catalogue/agent-picks lists. A body that isn't JSON, an email that isn't an address or a field other than email and draft is 400 bad_request; a missing or invalid draft is 400 invalid_draft. A sixth call within an hour from the calling project is 429 rate_limit_exceeded, with details.retryAt and Retry-After. On that draft-window 429, X-RateLimit-Limit is 5, X-RateLimit-Remaining is 0 and X-RateLimit-Reset is the draft window reset as Unix epoch seconds. Successful drafts keep the credential quota headers. Writes nothing when refused. Requires the `setup.write` scope.



## OpenAPI

````yaml /openapi.json post /projects/{projectId}/setup/new-project-draft
openapi: 3.1.0
info:
  title: DevTune 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.
  - name: Setup
    description: >-
      Brands, domains, brand terms, platforms, content sources and pausing a
      project.
  - name: Prompts and topics
    description: Tracked prompts, their topics, and prompt-set analysis.
  - name: Visibility
    description: >-
      Visibility metrics, AI answers, sentiment, competitive position and the
      project timeline.
  - name: Citations
    description: >-
      Citation statistics, the most-cited domains and pages, and cited lookalike
      sites.
  - name: Positioning
    description: How well AI answers match your positioning statements.
  - name: Accuracy
    description: Claims AI answers make about your brand, and contradictions.
  - name: Content gaps
    description: Topics, sources and brands where competitors are cited.
  - name: AI Traffic
    description: >-
      AI referrals, answer fetches, crawls, 404 Demand, Direct lift and Search
      Console totals.
  - name: Adoption
    description: npm downloads and GitHub stars for project domains.
  - name: Audit and pages
    description: Audit findings, Google eligibility, page metrics, and locked pages.
  - name: Actions
    description: Suggested and accepted work, briefs, drafts and pull requests.
  - name: Results
    description: Content changes, measured results and what works.
  - name: Agents
    description: Managed agents, their schedules and runs.
  - name: Dex
    description: Private Dex conversations, specialist handoffs and memory.
  - name: Agent Picks
    description: Agent Picks setup, tests, schedules and results.
  - name: Library and Knowledge
    description: Library items and the Knowledge Profile.
  - name: Webhooks
    description: Webhook subscriptions and signing secrets.
  - name: Agent registration
    description: Setup drafts for an unclaimed agent registration.
paths:
  /projects/{projectId}/setup/new-project-draft:
    post:
      tags:
        - Setup
      summary: Draft a new project for a person to claim
      description: >-
        Starts the auth.md registration and claim from this connection, for
        another product or brand: the credential stays bound to its own project.
        Takes the person's sign-in email and a whole setup draft, in the shape
        PUT /agent/setup-draft takes. No project exists and nothing is spent
        until the person claims it. Give the person
        claim_attempt.verification_uri and claim_attempt.user_code; they sign in
        with that email, review the draft on the claim page and confirm it into
        their account, where plan limits are applied. Poll token_endpoint with
        grant_type and claim_token for the new project's access token. The draft
        cannot be read or changed afterwards; another call starts a second
        registration. Agent Picks ids must be ones GET
        /projects/{projectId}/setup/catalogue/agent-picks lists. A body that
        isn't JSON, an email that isn't an address or a field other than email
        and draft is 400 bad_request; a missing or invalid draft is 400
        invalid_draft. A sixth call within an hour from the calling project is
        429 rate_limit_exceeded, with details.retryAt and Retry-After. On that
        draft-window 429, X-RateLimit-Limit is 5, X-RateLimit-Remaining is 0 and
        X-RateLimit-Reset is the draft window reset as Unix epoch seconds.
        Successful drafts keep the credential quota headers. Writes nothing when
        refused. Requires the `setup.write` scope.
      operationId: draftNewProject
      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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - email
                - draft
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 320
                  description: The sign-in email of the person who will claim it.
                draft:
                  $ref: '#/components/schemas/AgentSetupDraft'
      responses:
        '201':
          description: The started claim
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NewProjectDraft'
                  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'
      security:
        - bearerAuth: []
        - oauthBearer: []
components:
  schemas:
    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.
    NewProjectDraft:
      type: object
      additionalProperties: false
      required:
        - registration_id
        - claim_token
        - claim_token_expires
        - claim_attempt
        - claim_url
        - token_endpoint
        - grant_type
        - post_claim_scopes
      properties:
        registration_id:
          type: string
          description: The agent registration holding the draft.
        claim_token:
          type: string
          description: >-
            The secret the agent polls the token endpoint with, and restarts the
            claim with. Returned only in this response.
        claim_token_expires:
          type: string
          format: date-time
          description: When the unclaimed registration and its draft expire.
        claim_attempt:
          type: object
          additionalProperties: false
          required:
            - user_code
            - verification_uri
            - expires_in
            - interval
          description: What the person needs to claim the draft.
          properties:
            user_code:
              type: string
              description: The code the person types on the claim page.
            verification_uri:
              type: string
              format: uri
              description: The claim page link, through sign-in with the email given.
            expires_in:
              type: integer
              description: >-
                Seconds until the code expires. Restart the claim at claim_url
                for a new one.
            interval:
              type: integer
              description: The fewest seconds between polls of the token endpoint.
        claim_url:
          type: string
          format: uri
          description: >-
            Where to POST claim_token and email for a new code once this one
            expires.
        token_endpoint:
          type: string
          format: uri
          description: >-
            Where to poll with grant_type and claim_token. It answers
            authorization_pending until the person confirms, then returns an
            access token for the new project.
        grant_type:
          type: string
          enum:
            - urn:workos:agent-auth:grant-type:claim
        post_claim_scopes:
          type: array
          items:
            type: string
          description: >-
            The scopes the new project's key can hold; the claim grants the
            subset the person's plan offers.
    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
    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
  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'
    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'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in current window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the window resets
      schema:
        type: integer
  securitySchemes:
    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.
    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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.