openapi.yaml

openapi: 3.1.0
info:
  title: GitHub PR Attachment Service
  version: 0.1.0
  description: Uploads files for programmatic use in GitHub pull-request Markdown.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://{worker}.{subdomain}.workers.dev
    variables:
      worker:
        default: github-pr-attachments
      subdomain:
        default: example
paths:
  /healthz:
    get:
      summary: Check service health
      operationId: getHealth
      security: []
      responses:
        "200":
          description: Service is available
          content:
            application/json:
              schema:
                type: object
                required: [service, status]
                properties:
                  service: { type: string }
                  status: { type: string, const: ok }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/attachments:
    post:
      summary: Upload an attachment
      operationId: createAttachment
      security: [{ bearerAuth: [] }]
      parameters:
        - name: X-Filename
          in: header
          required: true
          description: Raw filename, or percent-encoded UTF-8 when X-Filename-Encoding is percent. Decoded filenames are limited to 200 Unicode characters.
          schema: { type: string, maxLength: 2400 }
        - name: X-Filename-Encoding
          in: header
          required: false
          description: Set when X-Filename contains percent-encoded UTF-8.
          schema: { type: string, enum: [percent] }
        - name: X-Alt-Text
          in: header
          required: false
          schema: { type: string, maxLength: 300 }
        - name: Content-Length
          in: header
          required: true
          schema: { type: integer, minimum: 1 }
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
          image/png:
            schema: { type: string, format: binary }
          image/jpeg:
            schema: { type: string, format: binary }
      responses:
        "201":
          description: Attachment stored
          headers:
            Location:
              schema: { type: string, format: uri }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Attachment" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "411": { $ref: "#/components/responses/LengthRequired" }
        "413": { $ref: "#/components/responses/TooLarge" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "507": { $ref: "#/components/responses/QuotaExceeded" }
  /v1/attachments/{id}:
    delete:
      summary: Delete an attachment
      operationId: deleteAttachment
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/AttachmentId"
      responses:
        "204": { description: Attachment deleted or already absent }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /v1/quota:
    get:
      summary: Read quota consumption
      operationId: getQuota
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Current quota consumption
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Quota" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /a/{id}/{filename}:
    get:
      summary: Retrieve an attachment
      operationId: getAttachment
      security: []
      parameters:
        - $ref: "#/components/parameters/AttachmentId"
        - $ref: "#/components/parameters/Filename"
      responses:
        "200":
          description: Attachment bytes
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "304": { description: Not modified }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/Expired" }
    head:
      summary: Read attachment metadata
      operationId: headAttachment
      security: []
      parameters:
        - $ref: "#/components/parameters/AttachmentId"
        - $ref: "#/components/parameters/Filename"
      responses:
        "200": { description: Attachment metadata headers }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/Expired" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    AttachmentId:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }
    Filename:
      name: filename
      in: path
      required: true
      description: Exact attachment filename, URL-encoded in the request path.
      schema: { type: string }
  schemas:
    Attachment:
      type: object
      required: [contentType, etag, expiresAt, filename, id, markdown, size, url]
      properties:
        contentType: { type: string }
        etag: { type: string }
        expiresAt: { type: string, format: date-time }
        filename: { type: string }
        id: { type: string, format: uuid }
        markdown: { type: string }
        size: { type: integer, minimum: 1 }
        url: { type: string, format: uri }
    Quota:
      type: object
      required:
        - dailyUploadLimit
        - dailyUploads
        - maxObjects
        - maxStoredBytes
        - monthlyUploadLimit
        - monthlyUploads
        - objectCount
        - reservedBytes
        - storedBytes
      properties:
        dailyUploadLimit: { type: integer }
        dailyUploads: { type: integer }
        maxObjects: { type: integer }
        maxStoredBytes: { type: integer }
        monthlyUploadLimit: { type: integer }
        monthlyUploads: { type: integer }
        objectCount: { type: integer }
        reservedBytes: { type: integer }
        storedBytes: { type: integer }
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }
  responses:
    BadRequest:
      description: Invalid attachment metadata or body
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    LengthRequired:
      description: Content-Length is missing or invalid
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    TooLarge:
      description: Attachment exceeds the configured size limit
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RateLimited:
      description: Daily or monthly upload limit reached
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    QuotaExceeded:
      description: Byte or object quota reached
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotFound:
      description: Attachment not found
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Expired:
      description: Attachment has expired
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }