{"openapi":"3.1.0","info":{"title":"flatmark","description":"Convert PDF, Word, PowerPoint, Excel and HTML to Markdown for RAG and agents. REST API and MCP server, hosted in Germany.\n\nBase URL: `https://api.flatmark.dev`.\n\n### Authentication\nSend your key in the `X-API-Key` header. Calls without a key run anonymously at\na lower rate limit per IP address.\n\n### Rate limits\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and\n`X-RateLimit-Reset` (seconds until the window resets). Over-budget calls return\n`429` with a `Retry-After` header. Check your live budget at `GET /v1/me`.\n\n### Pagination\nList endpoints return a keyset envelope: `{\"items\": [...], \"next_cursor\": \"...\"}`.\nPass `next_cursor` back as the `?cursor=` query param for the next page; it is\n`null` on the last page.\n\n### Errors\nErrors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json` with a\nstable machine-readable **`code`** (e.g. `rate_limited`, `credits_exhausted`,\n`validation_error`). Branch on `code`. The `title` and `detail` text may change.\n\n### Quickstart\n```sh\ncurl -H \"X-API-Key: $API_KEY\" https://api.flatmark.dev/v1/me\n```\n","version":"1"},"servers":[{"url":"https://api.flatmark.dev"}],"paths":{"/v1/me":{"get":{"tags":["Account"],"summary":"Your plan, remaining requests, and remaining credits","description":"Check where you stand before a call fails.\n\nReturns the plan this request runs on and whether your key was recognized.\nWithout an `X-API-Key`, the call runs anonymously at the rate limit for\ncalls without a key. It also returns the requests left in the current window\nand the features your plan includes. On plans priced in credits, it returns\nthe credits left in the current billing period.\n\nThis call does not count against your rate limit, so the numbers it reports\nare the numbers you have.\n\n**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}},"/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,\nreturns 404.\n\n**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}},"/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\nthe next page.\n\n**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}},"/v1/convert":{"post":{"tags":["Convert"],"summary":"Convert a document to Markdown in one call","description":"Converts one document up to 8 MB and returns the Markdown in the response.\n\nAccepted types: PDF (`application/pdf`), Word `.docx`, PowerPoint `.pptx`,\nExcel `.xlsx`, HTML (`text/html`) and plain text (`text/plain`). The\nContent-Type of the file part decides how it is read. Conversion uses\nMarkItDown. PDFs come back as plain text without headings and without OCR.\nFor scans, tables and page numbers, use the queue (`POST /v1/convert/jobs`).\n\nWorks without an API key at the anonymous rate limit. With a key, a\nrejected or failed call costs no credits.\n\n**Credits:** 1 per call.","operationId":"convert_document","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_document"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncConvertResponse"}}}},"402":{"description":"Your credit balance is used up (`credits_exhausted`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The file is larger than 8 MB (`payload_too_large`). Use the queue.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"The file type is not accepted, or the file does not match its declared type (`unsupported_media_type`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The document could not be converted, for example because it is damaged or password-protected (`conversion_failed`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests. Wait for the number of seconds in `Retry-After`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"A service this call depends on is unavailable. Try again later.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"APIKeyHeader":[]}],"x-credits-cost":1}},"/v1/convert/jobs":{"post":{"tags":["Convert"],"summary":"Queue a document for conversion with OCR and tables","description":"Queues one document up to 25 MB and 200 pages for conversion with Docling.\n\nAccepted types are the same as for `POST /v1/convert`. The queue runs OCR\n(text recognition) and recognizes tables, headings and reading order. A\nconversion may take up to about 2 minutes; longer ones are stopped and fail.\n\nPoll `GET /v1/jobs/{id}` (free) until `status` is `succeeded` or `failed`,\nthen download the result from `result_url` (free). The result is Markdown, or\nthe DoclingDocument JSON with `?format=json`.\n\nWith `webhook_url`, the job's final state is POSTed there as JSON\n(`job_id`, `status`, `result`, `error`). The request carries\n`X-Appkit-Signature: sha256=<hex>`, an HMAC-SHA256 of the raw request body\nkeyed with the `webhook_secret` from this response. `webhook_secret` is shown\nonly once. A delivery that fails is retried, 3 attempts in total.\n\nRequires an API key. The credits are charged at submission and refunded if\nthe job fails. The uploaded file is deleted when the job finishes. Results\nare kept for 7 days after submission.\n\n**Credits:** 10 per call.","operationId":"submit_conversion_job","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_submit_conversion_job"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitResponse"}}}},"401":{"description":"No valid API key in the `X-API-Key` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Your credit balance is used up (`credits_exhausted`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The file is larger than 25 MB (`payload_too_large`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"The file type is not accepted (`unsupported_media_type`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`webhook_url` is not a public http or https address (`invalid_webhook_url`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests. Wait for the number of seconds in `Retry-After`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"A service this call depends on is unavailable. Try again later.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"APIKeyHeader":[]}],"x-credits-cost":10}},"/v1/convert/jobs/{job_id}/result":{"get":{"tags":["Convert"],"summary":"Download a queued job's Markdown or JSON","description":"Returns the output of one of your finished queued jobs.\n\nMarkdown (`text/markdown`) by default, or the DoclingDocument JSON\n(`application/json`) with `?format=json`. The JSON carries page numbers for\nPDF, slide numbers for PowerPoint and sheet names for Excel.\n\n**Credits:** free. This endpoint is not metered.","operationId":"get_conversion_result","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["markdown","json"],"type":"string","description":"`markdown` (default) or `json` for the DoclingDocument structure file.","default":"markdown","title":"Format"},"description":"`markdown` (default) or `json` for the DoclingDocument structure file."}],"responses":{"200":{"description":"The converted document.","content":{"text/markdown":{},"application/json":{}}},"404":{"description":"No job with this id in your account (`not_found`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The job has not finished (`job_not_ready`), or it failed (`job_failed`, with the reason in `detail`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The result was deleted 7 days after submission (`result_expired`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`format` is not `markdown` or `json`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests. Wait for the number of seconds in `Retry-After`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":0}}},"components":{"schemas":{"Body_convert_document":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document, sent as multipart form data with its Content-Type."}},"type":"object","required":["file"],"title":"Body_convert_document"},"Body_submit_conversion_job":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document, sent as multipart form data with its Content-Type."},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"Optional. A public http or https URL that receives a POST when the job finishes."}},"type":"object","required":["file"],"title":"Body_submit_conversion_job"},"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\nyour plan included, `balance` what is still unspent, and `period_end` the\ndate (ISO 8601) your allowance refills. Present only on plans that are\npriced in credits."},"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\nresponse returns it once."},"JobSubmitResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"The job id."},"status":{"type":"string","title":"Status","description":"`queued` at submission."},"webhook_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Secret","description":"The key for checking the webhook signature. Only set when you sent `webhook_url`, and only shown in this response."},"result_url":{"type":"string","title":"Result Url","description":"Where to download the result once the job succeeded."},"poll_url":{"type":"string","title":"Poll Url","description":"Where to check the job's status."}},"type":"object","required":["job_id","status","result_url","poll_url"],"title":"JobSubmitResponse","description":"A queued conversion job."},"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\nleft of your request and credit allowances, and which features your plan\nincludes."},"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\nsame numbers as the `X-RateLimit-*` response headers. `limit` is the size of the\nwindow, `remaining` what is left of it, and `reset` how many seconds until\nit refills (not a timestamp). All three are `null` in the rare case the\ncounter cannot be read; treat that as \"unknown\", not zero."},"SyncConvertResponse":{"properties":{"markdown":{"type":"string","title":"Markdown","description":"The document as Markdown."},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Details about the source: `filename`, and `title` when the document has one."}},"type":"object","required":["markdown"],"title":"SyncConvertResponse","description":"The result of a direct conversion."},"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"}}},"tags":[{"name":"Convert"},{"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."},{"name":"Account","description":"Check your plan, your remaining requests and credits, and what your plan includes. `GET /v1/me` is always free."}]}