flatmark Webhooks API

openapi: 3.2.0
info:
  title: flatmark Webhooks 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: Webhooks
  description: 'Get events POSTed to your own https endpoint, signed per Standard Webhooks: verify the `webhook-signature` header with the endpoint''s secret, and use `webhook-id` to drop duplicates. A failed delivery is retried for a little over a day.'
paths:
  /v1/webhooks:
    get:
      tags:
      - Webhooks
      summary: List your webhook endpoints
      description: 'Lists your webhook endpoints, oldest first. There are at most 10, so

        `next_cursor` is always null.


        **Credits:** free. This endpoint is not metered.'
      operationId: list_webhook_endpoints
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointResponsePage'
        '401':
          description: No valid API key (`unauthorized`).
          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'
      security:
      - APIKeyHeader: []
      x-connector:
        kind: hidden
      x-credits-cost: 0
    post:
      tags:
      - Webhooks
      summary: Create a webhook endpoint
      description: 'Subscribes a URL to events. The response carries the signing secret,

        the only time it is shown. Every delivery is a POST signed per Standard

        Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`).


        **Credits:** free. This endpoint is not metered.'
      operationId: create_webhook_endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreated'
        '401':
          description: No valid API key (`unauthorized`).
          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'
        '409':
          description: You already have 10 endpoints (`endpoint_limit`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: The URL is not public https (`invalid_url`), an event type is unknown (`unknown_event_type`), or the body is invalid (`validation_error`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - APIKeyHeader: []
      x-connector:
        kind: hidden
      x-credits-cost: 0
  /v1/webhooks/{endpoint_id}:
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook endpoint
      description: 'Deletes an endpoint and its delivery history. Pending deliveries are

        not sent.


        **Credits:** free. This endpoint is not metered.'
      operationId: delete_webhook_endpoint
      security:
      - APIKeyHeader: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The endpoint's `id`.
          title: Endpoint Id
        description: The endpoint's `id`.
      responses:
        '204':
          description: Successful Response
        '401':
          description: No valid API key (`unauthorized`).
          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'
        '404':
          description: No endpoint with this ID belongs to you (`not_found`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-connector:
        kind: hidden
      x-credits-cost: 0
  /v1/webhooks/{endpoint_id}/test:
    post:
      tags:
      - Webhooks
      summary: Send a test event to a webhook endpoint
      description: 'Queues a `webhook.test` event for this endpoint, whatever event types it

        subscribes to. It is sent within seconds.


        **Credits:** free. This endpoint is not metered.'
      operationId: send_webhook_test_event
      security:
      - APIKeyHeader: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The endpoint's `id`.
          title: Endpoint Id
        description: The endpoint's `id`.
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestQueued'
        '401':
          description: No valid API key (`unauthorized`).
          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'
        '404':
          description: No endpoint with this ID belongs to you (`not_found`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: The endpoint is disabled (`endpoint_disabled`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-connector:
        kind: hidden
      x-credits-cost: 0
components:
  schemas:
    WebhookEndpointCreated:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: Empty means every event type.
        description:
          type: string
          title: Description
        enabled:
          type: boolean
          title: Enabled
          description: False once delivery failed 20 times in a row. Create the endpoint again.
        disabled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Disabled At
        created_at:
          type: string
          format: date-time
          title: Created At
        secret:
          type: string
          title: Secret
          description: 'The Standard Webhooks signing secret (`whsec_…`). Store it now: it is not shown again.'
      type: object
      required:
      - id
      - url
      - event_types
      - description
      - enabled
      - created_at
      - secret
      title: WebhookEndpointCreated
      description: The new endpoint, with its signing secret.
    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
    WebhookEndpointRequest:
      properties:
        url:
          type: string
          maxLength: 2000
          title: Url
          description: Where to send events. Must be `https://` on a public host.
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: The event types to receive. Empty receives every type.
        description:
          type: string
          maxLength: 200
          title: Description
          description: A note for yourself.
          default: ''
      type: object
      required:
      - url
      title: WebhookEndpointRequest
      description: A new endpoint.
    WebhookTestQueued:
      properties:
        msg_id:
          type: string
          title: Msg Id
          description: The `webhook-id` header the test delivery carries.
      type: object
      required:
      - msg_id
      title: WebhookTestQueued
      description: The queued test event.
    WebhookEndpointResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: Empty means every event type.
        description:
          type: string
          title: Description
        enabled:
          type: boolean
          title: Enabled
          description: False once delivery failed 20 times in a row. Create the endpoint again.
        disabled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Disabled At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - url
      - event_types
      - description
      - enabled
      - created_at
      title: WebhookEndpointResponse
      description: A webhook endpoint. The signing secret is returned only when it is created.
    WebhookEndpointResponsePage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WebhookEndpointResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: WebhookEndpointResponsePage
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key