flatmark Account API

openapi: 3.2.0
info:
  title: flatmark Account 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: Account
  description: Check your plan, your remaining requests and credits, and what your plan includes. `GET /v1/me` is always free.
paths:
  /v1/me:
    get:
      tags:
      - Account
      summary: Your plan, remaining requests, and remaining credits
      description: 'Check where you stand before a call fails.


        Returns the plan this request runs on and whether your key was recognized.

        Without an `X-API-Key`, the call runs anonymously at the rate limit for

        calls without a key. It also returns the requests left in the current window

        and the features your plan includes. On plans priced in credits, it returns

        the credits left in the current billing period.


        This call does not count against your rate limit, so the numbers it reports

        are the numbers you have.


        **Credits:** free. This endpoint is not metered.'
      operationId: get_me
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
      security:
      - APIKeyHeader: []
      x-credits-cost: 0
      x-connector:
        kind: action
components:
  schemas:
    MeResponse:
      properties:
        tier:
          type: string
          title: Tier
          description: The plan this request is served on.
        is_keyed:
          type: boolean
          title: Is Keyed
          description: Whether the request carried a valid API key. Without an `X-API-Key`, the call runs anonymously at the rate limit for calls without a key.
        rate_limit:
          $ref: '#/components/schemas/RateLimitInfo'
        credits:
          anyOf:
          - $ref: '#/components/schemas/CreditsInfo'
          - type: 'null'
          description: Null on plans that are not priced in credits.
        features:
          items:
            type: string
          type: array
          title: Features
          description: The features your plan includes.
      type: object
      required:
      - tier
      - is_keyed
      - rate_limit
      - features
      title: MeResponse
      description: 'The `GET /v1/me` payload: who the request is authenticated as, what is

        left of your request and credit allowances, and which features your plan

        includes.'
    CreditsInfo:
      properties:
        balance:
          type: integer
          title: Balance
        granted:
          type: integer
          title: Granted
        period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Period End
      type: object
      required:
      - balance
      - granted
      title: CreditsInfo
      description: 'Your credit balance for the current billing period. `granted` is what

        your plan included, `balance` what is still unspent, and `period_end` the

        date (ISO 8601) your allowance refills. Present only on plans that are

        priced in credits.'
    RateLimitInfo:
      properties:
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
        remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Remaining
        reset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reset
      type: object
      title: RateLimitInfo
      description: 'How many requests you may still make in the current window. These are the

        same numbers as the `X-RateLimit-*` response headers. `limit` is the size of the

        window, `remaining` what is left of it, and `reset` how many seconds until

        it refills (not a timestamp). All three are `null` in the rare case the

        counter cannot be read; treat that as "unknown", not zero.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key