openapi: 3.2.0
info:
  title: looot Skill Uploads 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: Skill Uploads
paths:
  /v1/skill-uploads:
    get:
      summary: List tenant-scoped atomic skill upload receipts
      responses:
        '200':
          description: Redacted receipts without environment digests, credential references, request digests, file paths, or contents
        '403':
          description: local-product:read scope required
        '503':
          description: Control plane unavailable
      tags:
      - Skill Uploads
      operationId: getV1SkillUploads
      x-operation-id-source: derived
    post:
      summary: Atomically quarantine skill metadata and owned tool drafts
      description: The server validates the bounded manifest, recomputes manifest and content-set digests, derives tenant and actor identity, and commits bundle, tools, and receipt in one transaction. This metadata-only route does not receive or distribute raw file contents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - bundleId
              - idempotencyKey
              - manifest
              - selectedEnvironmentKeyNames
              - tools
              properties:
                bundleId:
                  type: string
                  pattern: ^[a-z][a-z0-9_-]{2,127}$
                idempotencyKey:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$
                manifest:
                  type: object
                  additionalProperties: false
                  required:
                  - name
                  - description
                  - entrypoint
                  - files
                  properties:
                    name:
                      type: string
                      pattern: ^[a-z][a-z0-9_-]{2,127}$
                    description:
                      type: string
                      minLength: 1
                      maxLength: 1000
                    entrypoint:
                      type: string
                      minLength: 1
                      maxLength: 512
                      pattern: ^(?!/)(?!.*\\)(?!.*(?:^|/)\.{1,2}(?:/|$)).+(?<!/)$
                    files:
                      type: array
                      minItems: 1
                      maxItems: 256
                      items:
                        type: object
                        additionalProperties: false
                        required:
                        - path
                        - sizeBytes
                        - digest
                        properties:
                          path:
                            type: string
                            minLength: 1
                            maxLength: 512
                            pattern: ^(?!/)(?!.*\\)(?!.*(?:^|/)\.{1,2}(?:/|$)).+(?<!/)$
                          sizeBytes:
                            type: integer
                            minimum: 0
                            maximum: 1048576
                          digest:
                            type: string
                            pattern: ^sha256:[a-f0-9]{64}$
                selectedEnvironmentKeyNames:
                  type: array
                  maxItems: 100
                  uniqueItems: true
                  items:
                    type: string
                    pattern: ^[A-Za-z_][A-Za-z0-9_]{0,255}$
                tools:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    description: Strict tenant tool definition without tenant, actor, or owner identity
                replace:
                  type: boolean
                  default: false
      responses:
        '201':
          description: Redacted atomic upload receipt
        '400':
          description: Invalid, missing environment name, or digest computation failure
        '403':
          description: local-product:manage scope required; default LOCAL_ALPHA token is intentionally denied
        '409':
          description: Idempotency, version, dependency, or replacement conflict
        '503':
          description: Generic retry-unsafe uncertain commit or unavailable control plane
      tags:
      - Skill Uploads
      operationId: postV1SkillUploads
      x-operation-id-source: derived
  /v1/skill-uploads/{uploadId}/removal-plan:
    get:
      summary: Preview a skill upload's removal plan
      responses:
        '200':
          description: Success
      tags:
      - Skill Uploads
      operationId: getV1SkillUploadsByUploadIdRemovalPlan
      x-operation-id-source: derived
  /v1/skill-uploads/{uploadId}/remove:
    post:
      summary: Apply a previously previewed skill upload removal plan
      responses:
        '200':
          description: Success
      tags:
      - Skill Uploads
      operationId: postV1SkillUploadsByUploadIdRemove
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer