openapi: 3.0.3
info:
  title: Redact PDF AI - Redaction API
  version: 1.0.0
  description: |
    Programmatic redaction API for PDFs.

    Core model:
    - Create an async Job by uploading one or more files.
    - Poll the Job until it reaches a terminal state.
    - Download outputs per Document.

servers:
  - url: https://api.redactpdf.ai
paths:
  /v1/me:
    get:
      summary: Get current API identity
      description: Validate an API key and return basic account info.
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        '401':
          description: Unauthorized

  /v1/jobs:
    post:
      summary: Create a redaction job
      description: Upload one or more PDFs to create an async redaction job.
      security:
        - apiKeyAuth: []
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: false
          description: Prevent duplicate job creation on retries.
          schema:
            type: string
            maxLength: 200
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: PDF files to redact.
                pii_categories:
                  type: string
                  description: JSON array string of PII categories. If omitted, user defaults apply.
                  example: '["Person","Email","PhoneNumber"]'
                retention:
                  type: string
                  enum: [ephemeral, studio]
                  default: ephemeral
                  description: |
                    Retention mode.
                    - ephemeral: delete originals after processing; keep outputs for a short time
                    - studio: keep originals + masks so you can open in the Studio
              required:
                - files
      responses:
        '200':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '402':
          description: Payment required (quota exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/jobs/{job_id}:
    get:
      summary: Get job status
      security:
        - apiKeyAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
        '404':
          description: Not found

    delete:
      summary: Delete a job
      description: Purge a job and associated files (subject to retention policy).
      security:
        - apiKeyAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          description: Unauthorized
        '404':
          description: Not found

  /v1/documents/{doc_id}/output:
    get:
      summary: Download redacted output
      security:
        - apiKeyAuth: []
      parameters:
        - name: doc_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Redacted PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: Not found

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          example: quota_exceeded
        request_id:
          type: string
          example: req_123

    Me:
      type: object
      properties:
        user_id:
          type: string
          example: user_123
        email:
          type: string
          example: you@company.com

    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        file_name:
          type: string
          example: contract.pdf
        status:
          type: string
          example: uploaded
          enum: [uploaded, analyzing, redacting, redacted, error]
        page_count:
          type: integer
          example: 3
        error_message:
          type: string
          nullable: true

    Job:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [uploaded, analyzing, redacting, redacted, error]
          example: analyzing
        retention:
          type: string
          enum: [ephemeral, studio]
          example: ephemeral
        created_at:
          type: string
          format: date-time
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'