openapi: 3.2.0
info:
  title: looot Compatibility Drafts API
  version: 0.1.0
  description: Discover, inspect, run, and pay for real (or fixture) provider operations through one bearer token.
servers:
- url: https://api.looot.ai
  description: Public API (default)
- url: https://coset-gateway.onrender.com
  description: Legacy host -- still live, for tokens issued before the public domain existed
- url: http://127.0.0.1:8787
  description: Local development
security:
- bearerAuth: []
tags:
- name: Compatibility Drafts
paths:
  /v1/compatibility-drafts:
    get:
      summary: List non-executable compatibility drafts
      responses:
        '200':
          description: Drafts with unresolved gates
        '403':
          description: candidates:read scope required
      tags:
      - Compatibility Drafts
      operationId: getV1CompatibilityDrafts
      x-operation-id-source: derived
    post:
      summary: Create an idempotent compatibility draft from an accepted candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompatibilityDraft'
      responses:
        '200':
          description: Existing draft
        '201':
          description: New draft
        '400':
          description: Candidate not accepted or identity incomplete
        '403':
          description: candidates:write scope required
        '404':
          description: Candidate not found
        '409':
          description: Candidate drift
      tags:
      - Compatibility Drafts
      operationId: postV1CompatibilityDrafts
      x-operation-id-source: derived
  /v1/compatibility-drafts/{draftId}:
    get:
      summary: Get one non-executable compatibility draft
      responses:
        '200':
          description: Compatibility draft
        '403':
          description: candidates:read scope required
        '404':
          description: Draft not found
      tags:
      - Compatibility Drafts
      operationId: getV1CompatibilityDraftsByDraftId
      x-operation-id-source: derived
  /v1/compatibility-drafts/{draftId}/gates:
    get:
      summary: Get the immutable compatibility gate audit
      responses:
        '200':
          description: Gate submissions, decisions and unresolved gates; never activation
        '403':
          description: compatibility:read scope required
        '404':
          description: Draft not found
      tags:
      - Compatibility Drafts
      operationId: getV1CompatibilityDraftsByDraftIdGates
      x-operation-id-source: derived
    post:
      summary: Submit content-addressed evidence for one compatibility gate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitCompatibilityGate'
      responses:
        '200':
          description: Idempotent replay
        '201':
          description: Immutable submission created
        '403':
          description: compatibility:submit scope required
        '404':
          description: Draft not found
      tags:
      - Compatibility Drafts
      operationId: postV1CompatibilityDraftsByDraftIdGates
      x-operation-id-source: derived
components:
  schemas:
    CompatibilityEvidenceRef:
      type: object
      additionalProperties: false
      required:
      - url
      - digest
      - observedAt
      - kind
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://
        digest:
          type: string
          pattern: ^sha256:[a-f0-9]{64}$
        observedAt:
          type: string
          format: date-time
        kind:
          enum:
          - official_docs
          - openapi
          - terms
          - pricing
          - authenticated_test
          - internal_review
    CreateCompatibilityDraft:
      type: object
      additionalProperties: false
      required:
      - candidateId
      properties:
        candidateId:
          type: string
          minLength: 1
          maxLength: 300
    SubmitCompatibilityGate:
      type: object
      additionalProperties: false
      required:
      - gate
      - claim
      - evidenceRefs
      properties:
        gate:
          enum:
          - provider_identity
          - capability_mapping
          - official_evidence
          - rights
          - auth
          - base_url
          - effect_classification
          - price
          - executor
          - error_contract
          - rate_limits
          - retention
          - authenticated_test
          - production_approval
        claim:
          type: string
          minLength: 1
          maxLength: 2000
        evidenceRefs:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/CompatibilityEvidenceRef'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer