openapi: 3.2.0
info:
  title: V12 Me 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: Me
paths:
  /me:
    get:
      operationId: getMe
      summary: Get the token identity
      description: The user, organization and scopes behind this credential, plus the organization credit balance when the user may view billing. Any valid token may read it; organization.slug addresses every other endpoint.
      tags:
      - Me
      security:
      - bearer: []
      - oauth2: []
      x-mcp-tool: get_me
      parameters: []
      responses:
        '200':
          description: Get the token identity
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      username:
                        type: string
                      email:
                        type: string
                    required:
                    - username
                    - email
                    additionalProperties: false
                  organization:
                    type: object
                    properties:
                      slug:
                        type: string
                        description: 'Addresses the organization: /api/v2/orgs/<slug>/…'
                      name:
                        type: string
                      personal:
                        type: boolean
                    required:
                    - slug
                    - name
                    - personal
                    additionalProperties: false
                  token:
                    type: object
                    properties:
                      kind:
                        type: string
                        enum:
                        - pat
                        - oauth
                      scopes:
                        type: array
                        items:
                          type: string
                        description: Granted API scopes, e.g. "findings:read".
                    required:
                    - kind
                    - scopes
                    additionalProperties: false
                  credits:
                    anyOf:
                    - type: object
                      properties:
                        balanceCents:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        monthlyCapCents:
                          anyOf:
                          - type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          - type: 'null'
                      required:
                      - balanceCents
                      - monthlyCapCents
                      additionalProperties: false
                    - type: 'null'
                    description: Null unless the token user may view billing.
                required:
                - user
                - organization
                - token
                - credits
                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.