ChangeThisFile Jobs API

openapi: 3.2.0
info:
  title: ChangeThisFile Jobs 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: Jobs
  description: Async-only conversion jobs. Use these for long-running operations or when you want to poll instead of holding the request open.
paths:
  /v1/jobs:
    post:
      operationId: createJob
      tags:
      - Jobs
      summary: Queue an async conversion job
      description: 'Always queues a conversion regardless of file size. Returns a `job_id` immediately so the caller can poll `GET /v1/jobs/{job_id}` for status.


        Use this endpoint when you need predictable async behaviour — for example, when running conversions inside a queue worker that cannot block on a long HTTP request.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
      responses:
        '202':
          description: Job accepted and queued.
          headers:
            Location:
              schema:
                type: string
              description: Absolute URL of the queued job (same as `status_url` in the body).
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          description: Conversion route is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/jobs/{job_id}:
    get:
      operationId: getJob
      tags:
      - Jobs
      summary: Poll the status of a conversion job
      description: Returns the current state of a queued, processing, completed, or failed conversion job. Once a job is `completed`, the `result` object includes a signed download URL valid for 24 hours.
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
          format: uuid
        description: The job identifier returned by `POST /v1/jobs` or `POST /v1/convert` (when the conversion was queued).
      responses:
        '200':
          description: Current job status.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Job not found or has expired (jobs are retained for 7 days).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RateLimitReset:
      schema:
        type: integer
        format: int64
      description: Unix timestamp (seconds) when the rate-limit window resets.
    RateLimitRemaining:
      schema:
        type: integer
      description: Number of requests remaining in the current window.
    RateLimitLimit:
      schema:
        type: integer
      description: Number of requests permitted per minute on the caller's plan.
  schemas:
    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).
    JobStatus:
      type: object
      required:
      - job_id
      - status
      properties:
        job_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          description: '* `queued` — accepted but not yet picked up by a worker

            * `processing` — currently being converted

            * `completed` — conversion finished; `result` contains the download URL

            * `failed` — conversion failed; `error` describes the cause

            '
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        result:
          type: object
          description: Present when `status` is `completed`.
          properties:
            file_url:
              type: string
              format: uri
              description: Signed download URL valid for 24 hours.
            size:
              type: integer
              description: Size of the converted file in bytes.
            duration_ms:
              type: integer
            source_format:
              type: string
            target_format:
              type: string
        error:
          $ref: '#/components/schemas/Error'
    Job:
      type: object
      required:
      - job_id
      - status_url
      - status
      properties:
        job_id:
          type: string
          format: uuid
        status_url:
          type: string
          format: uri
          description: Absolute URL to poll for job status.
        status:
          type: string
          enum:
          - queued
    ConversionRequest:
      type: object
      required:
      - file
      - target
      properties:
        file:
          type: string
          format: binary
          description: The file to convert. Maximum size depends on your plan (25 MB on Free, up to 5 GB on Growth).
        target:
          type: string
          description: Target format extension, case-insensitive (e.g. `jpg`, `pdf`, `mp4`). The only field most callers ever need.
          examples:
          - jpg
        source:
          type: string
          description: 'Source format extension. **Optional** — auto-detected from the filename extension and (if needed) magic bytes. Pass it explicitly only when you have a renamed file or need to force a specific interpretation.

            '
          examples:
          - png
        quality:
          type: integer
          minimum: 1
          maximum: 100
          description: Optional quality preset (1-100). Applies to lossy image, video, and audio routes. Ignored by lossless and document routes.
  responses:
    PayloadTooLarge:
      description: File exceeded the plan's maximum size.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-minute rate limit or monthly conversion quota exceeded.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      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).

        '