flatmark Jobs API

openapi: 3.2.0
info:
  title: flatmark Jobs API
  description: 'Document to Markdown API and MCP server for PDF, Word, PowerPoint, Excel and HTML. OCR queue for large files. Hosted in Germany.


    Base URL: `https://api.flatmark.dev`.


    ### Authentication

    Send your key in the `X-API-Key` header. Calls without a key run anonymously at

    a lower rate limit per IP address.


    ### Rate limits

    Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset` (seconds until the window resets). Over-budget calls return

    `429` with a `Retry-After` header. Check your live budget at `GET /v1/me`.


    ### Pagination

    List endpoints return a keyset envelope: `{"items": [...], "next_cursor": "..."}`.

    Pass `next_cursor` back as the `?cursor=` query param for the next page; it is

    `null` on the last page.


    ### Errors

    Errors are RFC 9457 `problem+json` with a

    stable machine-readable **`code`** (e.g. `rate_limited`, `credits_exhausted`,

    `validation_error`). Branch on `code`. The `title` and `detail` text may change.


    ### Quickstart

    ```sh

    curl -H "X-API-Key: $API_KEY" https://api.flatmark.dev/v1/me

    ```'
  version: '1'
servers:
- url: https://api.flatmark.dev
tags:
- name: Jobs
  description: Track work submitted to the queue. Poll one job by id, or list your recent jobs. The submitting call returns the job id and its poll URL. Polling and listing are free.
paths:
  /v1/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get one queued job by ID
      description: 'Returns one of your jobs. An unknown ID, or a job owned by someone else,

        returns 404.


        **Credits:** free. This endpoint is not metered.'
      operationId: get_job
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: The `job_id` from the submit response.
          title: Job Id
        description: The `job_id` from the submit response.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404':
          description: No job with this ID belongs to your API key (`not_found`). A call without a valid key finds no jobs.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-credits-cost: 0
      x-connector:
        kind: action
  /v1/jobs:
    get:
      tags:
      - Jobs
      summary: List your queued jobs, newest first
      description: 'Lists your jobs, newest first. Pass `next_cursor` back as `cursor` to get

        the next page.


        **Credits:** free. This endpoint is not metered.'
      operationId: list_jobs
      security:
      - APIKeyHeader: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Items per page.
          default: 50
          title: Limit
        description: Items per page.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The `next_cursor` from the previous page.
          title: Cursor
        description: The `next_cursor` from the previous page.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponsePage'
        '429':
          description: Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-credits-cost: 0
      x-connector:
        kind: action
components:
  schemas:
    JobResponse:
      properties:
        id:
          type: string
          title: Id
          description: The job ID.
        kind:
          type: string
          title: Kind
        status:
          type: string
          title: Status
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
      type: object
      required:
      - id
      - kind
      - status
      title: JobResponse
      description: 'A job''s status and result. The webhook secret is not included. The submit

        response returns it once.'
    Problem:
      description: The RFC 9457 error body. Every error response uses it.
      properties:
        type:
          default: about:blank
          description: Problem type URI (RFC 9457).
          title: Type
          type: string
        title:
          description: Short human-readable summary of the status.
          title: Title
          type: string
        status:
          description: The HTTP status code, repeated in the body.
          title: Status
          type: integer
        detail:
          description: What went wrong with this request.
          title: Detail
          type: string
        instance:
          description: The request path that produced the error.
          title: Instance
          type: string
        code:
          description: Stable machine-readable error code. Branch on this, not on the text.
          title: Code
          type: string
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Correlation id for this request; quote it when asking for support.
          title: Request Id
        errors:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          default: null
          description: Per-field validation failures. Present on 422 only.
          title: Errors
        upgrade_url:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Where to add credits or move to a larger plan. Present on 402/403/429.
          title: Upgrade Url
      required:
      - title
      - status
      - detail
      - instance
      - code
      title: Problem
      type: object
    JobResponsePage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/JobResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: JobResponsePage
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key