openapi: 3.1.0
info:
  title: C2PA Content Provenance API
  version: "1.0.0"
  description: >
    Sign media with C2PA Content Credentials (provenance, AI-origin, creator,
    edit history) and verify existing credentials. Built on the open C2PA
    standard to help meet EU AI Act content-transparency requirements
    (effective 2026-08-02). Distributed via RapidAPI.
servers:
  - url: https://content-provenance.p.rapidapi.com
    description: RapidAPI gateway (replace with your RapidAPI host)
security:
  - rapidApiKey: []
paths:
  /v1/sign:
    post:
      operationId: signContent
      summary: Embed C2PA Content Credentials into an asset
      description: Provide exactly one of image_base64 (with mime_type) or image_url.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignRequest'
            examples:
              fromUrl:
                value: { image_url: "https://example.com/photo.jpg", creator: "Jane Doe", ai: false }
      responses:
        "200":
          description: Signed asset stored; presigned download URL returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignResponse'
        "400": { $ref: '#/components/responses/Error' }
        "403": { $ref: '#/components/responses/Error' }
        "413": { $ref: '#/components/responses/Error' }
        "415": { $ref: '#/components/responses/Error' }
        "502": { $ref: '#/components/responses/Error' }
  /v1/verify:
    post:
      operationId: verifyContent
      summary: Read and validate C2PA Content Credentials from an asset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
            examples:
              fromUrl:
                value: { image_url: "https://example.com/signed.jpg" }
      responses:
        "200":
          description: Provenance report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        "400": { $ref: '#/components/responses/Error' }
        "403": { $ref: '#/components/responses/Error' }
        "415": { $ref: '#/components/responses/Error' }
        "502": { $ref: '#/components/responses/Error' }
  /v1/usage:
    get:
      operationId: getUsage
      summary: Detected RapidAPI plan and per-plan limits (quota metered by RapidAPI)
      responses:
        "200":
          description: Plan snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        "403": { $ref: '#/components/responses/Error' }
  /v1/manifest:
    get:
      operationId: getManifest
      summary: Machine-readable capability manifest
      security: []
      responses:
        "200": { description: Capability manifest. }
  /healthz:
    get:
      operationId: health
      summary: Health check
      security: []
      responses:
        "200": { description: Service healthy. }
components:
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: >
        Your RapidAPI application key. RapidAPI authenticates the consumer,
        meters usage, and proxies the call to the backend. Subscribe to a plan
        on the RapidAPI Hub to obtain a key.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string }
      description: Safe retries — identical keys return the stored result without re-signing.
  schemas:
    SignRequest:
      type: object
      properties:
        image_base64: { type: string, description: Base64 of the asset (with mime_type). }
        image_url: { type: string, format: uri, description: http(s) URL of the asset to fetch. }
        mime_type: { type: string, example: image/jpeg }
        title: { type: string }
        creator: { type: string, description: Author/creator name. }
        ai: { type: boolean, description: Mark content as AI-generated. }
        edited: { type: boolean, description: Mark as an edit of existing content. }
        claims:
          type: array
          description: Extra C2PA assertions to embed.
          items:
            type: object
            properties:
              label: { type: string }
              data: { type: object }
              kind: { type: string, enum: [Json, Cbor, Binary], default: Json }
        filename: { type: string }
        returnBase64: { type: boolean }
      oneOf:
        - required: [image_base64, mime_type]
        - required: [image_url]
    SignResponse:
      type: object
      properties:
        id: { type: string }
        download_url: { type: string, format: uri }
        expires_in: { type: integer }
        bytes: { type: integer }
        mime_type: { type: string }
        filename: { type: string }
        signer_mode: { type: string, enum: [production, test] }
        plan: { type: string }
        signed_base64: { type: string, nullable: true }
    VerifyRequest:
      type: object
      properties:
        image_base64: { type: string }
        image_url: { type: string, format: uri }
        mime_type: { type: string }
      oneOf:
        - required: [image_base64]
        - required: [image_url]
    VerifyResponse:
      type: object
      properties:
        mime_type: { type: string }
        has_manifest: { type: boolean }
        verified: { type: boolean }
        validation_status:
          type: array
          items: { type: object }
        manifest_count: { type: integer }
        plan: { type: string }
        active_manifest:
          type: object
          nullable: true
          properties:
            title: { type: string, nullable: true }
            claim_generator: { type: string, nullable: true }
            format: { type: string, nullable: true }
            ai_generated: { type: boolean }
            authors:
              type: array
              items: { type: string }
            actions:
              type: array
              items:
                type: object
                properties:
                  action: { type: string }
                  digital_source_type: { type: string, nullable: true }
            signature:
              type: object
              nullable: true
              properties:
                issuer: { type: string, nullable: true }
                time: { type: string, nullable: true }
                cert_serial: { type: string, nullable: true }
    Usage:
      type: object
      properties:
        plan: { type: string }
        rapidapi_plan: { type: string, nullable: true }
        user: { type: string, nullable: true }
        max_bytes_per_op: { type: integer }
        note: { type: string }
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
            hint: { type: string, nullable: true }
            request_id: { type: string }
        request_id: { type: string }
  responses:
    Error:
      description: Structured error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
