ChangeThisFile Account API

openapi: 3.2.0
info:
  title: ChangeThisFile Account API
  summary: The conversion API for AI builders.
  description: 'The ChangeThisFile API provides a single, predictable HTTP surface covering 1,000+ supported conversion routes across images, video, audio, documents, spreadsheets, ebooks, archives, and fonts.


    Built for AI builders, automation pipelines, and back-office workflows that need flat, predictable pricing and broad format coverage.


    ## Authentication


    All requests to `/v1/*` (except `/v1/keys/free`) require an API key passed as a bearer token:


    ```

    Authorization: Bearer ctf_sk_xxxxxxxxxxxx

    ```


    Request a free API key by calling `POST /v1/keys/free` with an email address and following the verification link. The free developer tier includes 25 conversions per month shared across REST and authenticated MCP, with a 25 MB file size cap.


    ## Synchronous vs asynchronous


    `POST /v1/convert` is synchronous up to the active plan''s file-size limit and returns the converted file inline. Use `POST /v1/jobs` when you need asynchronous processing.


    `POST /v1/jobs` always queues a job and returns a `job_id` immediately, regardless of file size. Use this when you want predictable async behaviour.


    ## Rate limits


    Every response includes the standard rate-limit headers so you can throttle clients in real time:


    | Header | Description |

    |---|---|

    | `X-RateLimit-Limit` | Requests permitted in the current window |

    | `X-RateLimit-Remaining` | Requests remaining in the current window |

    | `X-RateLimit-Reset` | Unix timestamp when the window resets |


    Exceeding either the per-minute rate limit or your monthly conversion quota returns HTTP `429` with a structured error body.


    ## Errors


    Every error response uses the same envelope:


    ```json

    { "error": { "code": "quota_exceeded", "message": "Monthly conversion quota exceeded.", "details": { "limit": 25, "used": 25 } } }

    ```


    See the `Error` schema for the full list of error codes.'
  version: 1.1.0
  contact:
    name: ChangeThisFile Support
    email: support@changethisfile.com
    url: https://changethisfile.com/contact
  termsOfService: https://changethisfile.com/terms
  license:
    name: Commercial
    url: https://changethisfile.com/terms
servers:
- url: https://changethisfile.com
  description: Production
tags:
- name: Account
  description: API keys and usage reporting.
paths:
  /v1/keys/free:
    post:
      operationId: createFreeKey
      tags:
      - Account
      security: []
      summary: Request a verified free API key
      description: 'Sends an email-verification link. After verification, the dashboard creates the first API key and reveals it through a short-lived, account-bound reference. No credit card required.


        The free developer tier includes 25 conversions per month shared across REST and authenticated MCP, a 25 MB file size cap, and 10 requests per minute.


        Existing users receive the same sign-in link and can manage or rotate keys in the dashboard.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to associate with the key. Used for usage notifications.
                  examples:
                  - dev@example.com
      responses:
        '202':
          description: Verification email accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - verification_required
                - monthly_limit
                properties:
                  ok:
                    type: boolean
                  verification_required:
                    type: boolean
                  monthly_limit:
                    type: integer
                    description: Conversions permitted per calendar month on the issued plan.
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/usage:
    get:
      operationId: getUsage
      tags:
      - Account
      summary: Get current usage and plan limits
      description: Returns the caller's plan, current month conversion count, monthly quota, file size cap, and per-minute rate limit. Useful for surfacing usage inside customer-facing dashboards.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current usage snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Usage:
      type: object
      required:
      - plan
      - conversions_this_month
      - monthly_limit
      - max_file_size
      - rate_per_minute
      properties:
        plan:
          $ref: '#/components/schemas/PlanId'
        conversions_this_month:
          type: integer
          description: Conversions used in the current calendar month.
        monthly_limit:
          type: integer
          description: Conversions permitted per calendar month on the active plan. `-1` means unlimited. At quota, accounts hard-stop unless they have prepaid conversion credits.
        max_file_size:
          type: integer
          description: Maximum file size in bytes the active plan accepts.
        rate_per_minute:
          type: integer
          description: Maximum requests per minute the active plan accepts.
        credit_balance:
          type: integer
          description: Optional one-off credit balance (legacy a-la-carte packs only).
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              enum:
              - bad_request
              - invalid_api_key
              - quota_exceeded
              - rate_limited
              - file_too_large
              - unsupported_route
              - conversion_failed
              - service_unavailable
              - not_found
              - invalid_signature
            message:
              type: string
              description: Human-readable error message.
            details:
              type: object
              description: Optional structured details (e.g. limit, used, retry_after).
    PlanId:
      type: string
      enum:
      - free
      - hobby
      - startup
      - scale
      - growth
      - enterprise
      description: Self-serve plan identifier. `enterprise` is billed via custom contract — see `/pricing`.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Pass your API key as a bearer token. Get one for free at `POST /v1/keys/free` (no credit card required).

        '