> ## 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.

# List Agent Picks setups

> List the project’s Agent Picks setups with what each tests, oldest first, and the catalogue ids a save names. kind is job (the project’s own job), copy (its copy of a public category) or category (a setup saved on a public category itself). snapshot_digest is what saveAgentPicksJob and saveAgentPicksSetup take as snapshot_digest, so a setup changed since it was read is refused with 409 setup_changed. A category setup’s tool signals and building blocks are DevTune’s and come back null. The agentpicks CLI reads this to list, pull, push and run setups. The API key, or an OAuth token for the project, needs visibility.read. Requires Agent Picks. Requires the `visibility.read` scope.



## OpenAPI

````yaml /openapi.json get /projects/{projectId}/agent-picks/setup
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}/agent-picks/setup:
    get:
      tags:
        - Agent Picks
      summary: List Agent Picks setups
      description: >-
        List the project’s Agent Picks setups with what each tests, oldest
        first, and the catalogue ids a save names. kind is job (the project’s
        own job), copy (its copy of a public category) or category (a setup
        saved on a public category itself). snapshot_digest is what
        saveAgentPicksJob and saveAgentPicksSetup take as snapshot_digest, so a
        setup changed since it was read is refused with 409 setup_changed. A
        category setup’s tool signals and building blocks are DevTune’s and come
        back null. The agentpicks CLI reads this to list, pull, push and run
        setups. The API key, or an OAuth token for the project, needs
        visibility.read. Requires Agent Picks. Requires the `visibility.read`
        scope.
      operationId: listAgentPicksSetups
      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 project’s setups and the catalogue
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentPicksSetupListData'
                  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'
      security:
        - bearerAuth: []
        - oauthBearer: []
components:
  schemas:
    AgentPicksSetupListData:
      type: object
      required:
        - setups
        - catalogue
      properties:
        setups:
          type: array
          items:
            type: object
            required:
              - id
              - category_id
              - category_slug
              - name
              - kind
              - source_category_slug
              - source_category_id
              - snapshot_digest
              - requests
              - tools
              - own_tool_key
              - competitor_tool_keys
              - environments
              - agent_models
              - building_blocks
            properties:
              id:
                type: string
                format: uuid
              category_id:
                type: string
                format: uuid
                description: >-
                  The setup’s own category id. Pass it as category_id with setup
                  when saving through agent-picks/setup, including a copy whose
                  public source category is unpublished.
              category_slug:
                type: string
                description: >-
                  The slug a self-run upload names as its manifest’s
                  request.category to file its runs on this setup.
              name:
                type: string
                description: The category’s name, or the job line.
              kind:
                type: string
                enum:
                  - job
                  - copy
                  - category
              source_category_slug:
                type:
                  - string
                  - 'null'
                description: >-
                  The public category a copy or category setup is of; null for a
                  job.
              source_category_id:
                type:
                  - string
                  - 'null'
                format: uuid
                description: >-
                  A copy’s public source category id. Pass it as
                  source_category_id when saving its tools through
                  agent-picks/job. Null for a job or a setup on a public
                  category itself.
              snapshot_digest:
                type: string
                pattern: ^[a-f0-9]{64}$
              requests:
                type: object
                description: >-
                  The active request per intent (add, recommend, hosted,
                  improve); null for one left out.
                additionalProperties:
                  type:
                    - string
                    - 'null'
              tools:
                type: array
                items:
                  type: object
                  required:
                    - tool_key
                    - display_name
                    - brand_domain
                    - signals
                  properties:
                    tool_key:
                      type: string
                    display_name:
                      type: string
                    brand_domain:
                      type:
                        - string
                        - 'null'
                    signals:
                      type:
                        - object
                        - 'null'
                      additionalProperties: true
                      description: >-
                        In the shape saveAgentPicksJob takes, for a tool the
                        customer authored. Null for a tool whose key is in
                        DevTune’s catalogue, whose signals are DevTune’s: name
                        it by key.
              own_tool_key:
                type:
                  - string
                  - 'null'
              competitor_tool_keys:
                type: array
                items:
                  type: string
              environments:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - slug
                  properties:
                    id:
                      type: string
                      format: uuid
                    slug:
                      type: string
              agent_models:
                type: array
                items:
                  $ref: '#/components/schemas/AgentPicksAgentModel'
              building_blocks:
                type:
                  - object
                  - 'null'
                additionalProperties: true
                description: >-
                  A job’s building blocks. Null for a copy or category setup,
                  whose building blocks are the catalogue’s.
        catalogue:
          type: object
          required:
            - categories
            - environments
            - agents
          properties:
            categories:
              type: array
              description: Published public categories.
              items:
                type: object
                required:
                  - id
                  - slug
                properties:
                  id:
                    type: string
                    format: uuid
                  slug:
                    type: string
            environments:
              type: array
              description: Test apps a new setup may name; retired ones are left out.
              items:
                type: object
                required:
                  - id
                  - slug
                properties:
                  id:
                    type: string
                    format: uuid
                  slug:
                    type: string
            agents:
              type: array
              items:
                type: object
                required:
                  - agent
                  - models
                  - included_in_plan
                properties:
                  agent:
                    type: string
                    enum:
                      - claude_code
                      - codex
                      - opencode
                      - pi
                      - muse_code
                  models:
                    type: array
                    items:
                      type: string
                  included_in_plan:
                    type: boolean
    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
    AgentPicksAgentModel:
      type: object
      additionalProperties: false
      properties:
        agent:
          type: string
          enum:
            - claude_code
            - codex
            - opencode
            - pi
            - muse_code
          description: Every Agent Picks plan includes every agent.
        model:
          type: string
          description: >-
            A priced model offered for the selected agent. Claude Code:
            claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1,
            claude-haiku-5-5. Codex: gpt-6.1-sol, gpt-6-astra, gpt-6-luna. Pi
            and OpenCode: any of those seven, and zai/glm-5.3,
            zai/glm-5.3-flash, deepseek/deepseek-v4.1-flash-1017 and
            deepseek/deepseek-v4-pro-0813. Muse Code: meta/muse-wonder-1.0.
      required:
        - agent
        - model
    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:
    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'
  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.