openapi: 3.2.0
info:
  title: V12 Members API
  version: 2.0.0
  description: Findings, runs and context documents of one V12 organization. Every path but /me sits under /orgs/{org}, where {org} is the organization's slug (GET /me returns it); a token reaches only its own organization, and any other slug answers 404.
servers:
- url: https://v12.sh/api/v2
tags:
- name: Members
paths:
  /orgs/{org}/members:
    get:
      operationId: listMembers
      summary: List organization members
      description: Members of the token organization, sorted by username, then email. Use a member email or username to assign findings.
      tags:
      - Members
      security:
      - bearer: []
      - oauth2:
        - user:read
      x-mcp-tool: list_members
      parameters:
      - name: org
        in: path
        required: true
        description: Organization slug; must be the token's organization.
        schema:
          type: string
      responses:
        '200':
          description: List organization members
          content:
            application/json:
              schema:
                type: object
                properties:
                  nextCursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        username:
                          type: string
                        email:
                          type: string
                        role:
                          type: string
                          enum:
                          - owner
                          - member
                      required:
                      - username
                      - email
                      - role
                      additionalProperties: false
                required:
                - nextCursor
                - items
                additionalProperties: false
        '400':
          description: The request is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: The token lacks a scope, or its user lacks a permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Not found in the token organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '409':
          description: The request conflicts with the current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '503':
          description: Temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
components:
  schemas:
    ApiErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - repository_required
              - unauthenticated
              - insufficient_credits
              - spend_cap_reached
              - insufficient_scope
              - forbidden
              - not_found
              - repository_not_visible
              - repository_not_added
              - method_not_allowed
              - position_unavailable
              - decision_active
              - conflict
              - price_exceeds_max
              - quote_stale
              - change_refused
              - nothing_to_review
              - repository_not_runnable
              - idempotency_key_reused
              - api_version_retired
              - payload_too_large
              - unsupported_media_type
              - rate_limited
              - internal_error
              - upstream_error
              - platform_unavailable
              - repository_access_unavailable
              - rate_limit_unavailable
              - public_api_disabled
            message:
              type: string
            details:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          additionalProperties: false
        requestId:
          type: string
      required:
      - error
      - requestId
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A personal access token (v12p_…) or an OAuth access token (v12a_…).
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://v12.sh/oauth/authorize
          tokenUrl: https://v12.sh/api/oauth/token
          refreshUrl: https://v12.sh/api/oauth/token
          scopes:
            user:read: 'The member directory: usernames, emails and roles. Any key reads its own account, organization and credit balance without it.'
            repos:read: Repositories, branches, pull requests, tags and Steer instructions.
            repos:write: Add public repositories to the workspace; owners can also add private repositories granted by GitHub, create repositories V12 hosts and push code to them.
            steers:write: Create, edit, archive and restore Steers. Archiving detaches them from Autopilot rules; finding tags and run history are kept.
            runs:read: Runs, their progress and context documents.
            runs:write: Estimate and start runs; add or archive context documents.
            runs:manage: Cancel runs.
            runs:share: Create, change and revoke guest links that open a run to people outside the organization.
            findings:read: 'The inbox: findings, their status, reports and comments.'
            findings:write: Change status, comment and update triage decisions.