{ "openapi": "3.1.0", "info": { "title": "Dawloom API", "version": "1.0.0", "summary": "Free document-to-markdown conversion and a contact endpoint, both open to agents.", "description": "The Dawloom API converts documents to markdown and accepts project enquiries. It is free, needs no API key, and never stores uploaded files.\n\n## Versioning\n\nThe version is in the URL path: every endpoint lives under `/api/v1/`. A new major version gets a new path (`/api/v2/`) and both run side by side. Breaking changes never land in an existing version. Additive changes (new fields, new endpoints, new enum members) can land in `v1` at any time, so parse responses leniently. Every response carries an `X-Api-Version` header.\n\n## Deprecation policy\n\nWhen an endpoint or a version is deprecated it keeps working for at least 12 months. Deprecated responses carry `Deprecation: true`, a `Sunset` HTTP-date header (RFC 8594), and a `Link` header with `rel=\"deprecation\"` pointing at the notice. The unversioned aliases `/api/convert` and `/api/contact` are deprecated today and are scheduled for sunset on Wed, 31 Dec 2031 23:59:59 GMT.\n\n## Rate limits\n\nLimits are per client IP: 120 reads per 60s, 30 conversions per 60s, 5 contact messages per 600s. Every response carries `RateLimit` and `RateLimit-Policy` (IETF structured fields) plus the older `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` fields. A 429 also carries `Retry-After`.\n\n## Errors\n\nEvery 4xx and 5xx response uses the same `Problem` object, modelled on RFC 9457. It always has a machine-readable `code`, a human-readable `title` and `detail`, a `hint` telling you what to do next, and a `documentation_url`. Send `Accept: application/problem+json` to get the response typed as a problem document.", "contact": { "name": "Dawloom", "url": "https://dawloom.com/developers/", "email": "support@dawloom.com" }, "license": { "name": "Free to use", "url": "https://dawloom.com/developers/" }, "termsOfService": "https://dawloom.com/privacy/" }, "externalDocs": { "description": "Developer portal", "url": "https://dawloom.com/developers/" }, "servers": [ { "url": "https://dawloom.com", "description": "Production" } ], "tags": [ { "name": "meta", "description": "Discovery, health, and capability endpoints." }, { "name": "convert", "description": "Document to markdown conversion." }, { "name": "contact", "description": "Send a project enquiry to the Dawloom team." } ], "security": [], "x-api-versioning": { "strategy": "url-path", "current": "v1", "supported": [ "v1" ], "version_header": "X-Api-Version" }, "x-deprecation-policy": { "notice_period_months": 12, "signals": [ "Deprecation", "Sunset", "Link" ], "deprecated": [ { "path": "/api/convert", "replacement": "/api/v1/convert", "sunset": "Wed, 31 Dec 2031 23:59:59 GMT" }, { "path": "/api/contact", "replacement": "/api/v1/contact", "sunset": "Wed, 31 Dec 2031 23:59:59 GMT" } ] }, "x-rate-limits": { "read": { "limit": 120, "window_seconds": 60 }, "convert": { "limit": 30, "window_seconds": 60 }, "contact": { "limit": 5, "window_seconds": 600 } }, "x-mcp-server": { "url": "https://dawloom.com/mcp", "transport": "streamable-http", "manifest": "https://dawloom.com/.well-known/mcp.json" }, "paths": { "/api/v1/": { "get": { "operationId": "getApiIndex", "summary": "List the API endpoints", "description": "Returns every endpoint in this version with its method, path, and a one-line description, plus links to the OpenAPI document, the MCP server, and the developer portal. Start here when discovering the API.", "tags": [ "meta" ], "parameters": [], "responses": { "200": { "description": "The endpoint index.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Check that the API is up", "description": "Returns the service status and the API version. Cheap to call, safe to poll, no side effects.", "tags": [ "meta" ], "parameters": [], "responses": { "200": { "description": "The service is healthy.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/formats": { "get": { "operationId": "listSupportedFormats", "summary": "List the document formats that can be converted", "description": "Returns every file extension the convert endpoint accepts, with the maximum file size. Call this before uploading if you need to check a format at runtime.", "tags": [ "convert" ], "parameters": [], "responses": { "200": { "description": "The supported formats.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatList" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "Fetch this OpenAPI document", "description": "Returns the OpenAPI 3.1 description of the API. Use it to generate a client or to build LLM function-calling tool definitions.", "tags": [ "meta" ], "parameters": [], "responses": { "200": { "description": "The OpenAPI 3.1 document.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document.", "additionalProperties": true } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/convert": { "get": { "operationId": "getConvertUsage", "summary": "Usage notes for the convert endpoint", "description": "Returns the supported formats, size limits, rate limits, and copy-paste curl examples for the convert endpoint. Safe to call without a document.", "tags": [ "convert" ], "deprecated": false, "parameters": [], "responses": { "200": { "description": "Usage notes, supported formats, and limits.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertUsage" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "convertDocument", "summary": "Convert a document to markdown", "description": "Converts a Word, PDF, PowerPoint, Excel, OpenDocument, RTF, EPUB, or CSV document to GitHub-flavored markdown. No authentication. The file is converted in memory and never stored. Maximum size 25 MB. Provide the document as a multipart file, as a JSON body with \"url\" or \"base64\", or as raw bytes with the filename in the X-Filename header.", "tags": [ "convert" ], "deprecated": false, "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Send text/markdown to get the markdown body on its own. Send application/problem+json to get errors as RFC 9457 problem documents. Anything else returns the JSON envelope.", "schema": { "type": "string", "enum": [ "application/json", "text/markdown", "application/problem+json" ], "default": "application/json" } }, { "name": "X-Filename", "in": "header", "required": false, "description": "Same as the filename query parameter, for raw byte uploads.", "schema": { "type": "string", "examples": [ "report.docx" ] } }, { "name": "filename", "in": "query", "required": false, "description": "Filename with extension, used for format detection when the bytes are sent raw. Required for CSV.", "schema": { "type": "string", "examples": [ "report.docx" ] } } ], "requestBody": { "required": true, "description": "The document to convert. Send it as a multipart file, as JSON with a url or base64 field, or as raw bytes.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document to convert." } }, "required": [ "file" ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConvertRequest" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw document bytes." } } } }, "responses": { "200": { "description": "The document was converted. Returns the JSON envelope, or a raw markdown body when Accept is text/markdown.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResult" } }, "text/markdown": { "schema": { "type": "string", "description": "The converted markdown document." } } } }, "400": { "description": "The request body could not be read.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Request could not be understood", "value": { "type": "https://dawloom.com/developers/errors/#invalid_request", "title": "Request could not be understood", "status": 400, "code": "invalid_request", "detail": "Request could not be understood", "hint": "Check the request body against the OpenAPI schema at https://dawloom.com/api/v1/openapi.json.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "invalid_request" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is larger than 25 MB.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Payload exceeds the size limit", "value": { "type": "https://dawloom.com/developers/errors/#payload_too_large", "title": "Payload exceeds the size limit", "status": 413, "code": "payload_too_large", "detail": "Payload exceeds the size limit", "hint": "The limit is 25 MB. Split the document or send a URL instead of the bytes.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "payload_too_large" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The document was read but could not be converted. The \"code\" field says why: unsupported, malformed, encrypted, resourceLimit, or missingPart.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unprocessable": { "summary": "The document could not be converted", "value": { "type": "https://dawloom.com/developers/errors/#unprocessable", "title": "The document could not be converted", "status": 422, "code": "unprocessable", "detail": "The document could not be converted", "hint": "See \"code\" for the reason. Encrypted files and image-only PDFs cannot be converted.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "unprocessable" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The document URL could not be fetched.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fetch_failed": { "summary": "The document URL could not be fetched", "value": { "type": "https://dawloom.com/developers/errors/#fetch_failed", "title": "The document URL could not be fetched", "status": 502, "code": "fetch_failed", "detail": "The document URL could not be fetched", "hint": "Check that the URL is public and returns the file directly.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "fetch_failed" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/contact": { "post": { "operationId": "submitContactMessage", "summary": "Send a project enquiry to Dawloom", "description": "Delivers a project enquiry to the Dawloom team by email. An engineer replies. Use this when a user asks you to get in touch with Dawloom about building software. Do not use it for anything else: the messages go to real people.", "tags": [ "contact" ], "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Send text/markdown to get the markdown body on its own. Send application/problem+json to get errors as RFC 9457 problem documents. Anything else returns the JSON envelope.", "schema": { "type": "string", "enum": [ "application/json", "text/markdown", "application/problem+json" ], "default": "application/json" } } ], "requestBody": { "required": true, "description": "The enquiry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } } }, "responses": { "200": { "description": "The message was delivered.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResult" } } } }, "400": { "description": "A field failed validation.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "summary": "One or more fields failed validation", "value": { "type": "https://dawloom.com/developers/errors/#validation_failed", "title": "One or more fields failed validation", "status": 400, "code": "validation_failed", "detail": "One or more fields failed validation", "hint": "Fix the fields listed in \"errors\" and send the request again.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "validation_failed" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The email provider rejected the message.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_failed": { "summary": "An upstream service failed", "value": { "type": "https://dawloom.com/developers/errors/#upstream_failed", "title": "An upstream service failed", "status": 502, "code": "upstream_failed", "detail": "An upstream service failed", "hint": "Retry once. If it keeps failing, email support@dawloom.com.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "upstream_failed" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Email delivery is not configured.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_configured": { "summary": "The endpoint is temporarily not configured", "value": { "type": "https://dawloom.com/developers/errors/#not_configured", "title": "The endpoint is temporarily not configured", "status": 503, "code": "not_configured", "detail": "The endpoint is temporarily not configured", "hint": "Nothing to fix on your side. Retry later or email support@dawloom.com.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "not_configured" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/convert": { "get": { "operationId": "getConvertUsageLegacy", "summary": "Usage notes for the convert endpoint", "description": "Returns the supported formats, size limits, rate limits, and copy-paste curl examples for the convert endpoint. Safe to call without a document.", "tags": [ "convert" ], "deprecated": true, "parameters": [], "responses": { "200": { "description": "Usage notes, supported formats, and limits.", "headers": { "Deprecation": { "description": "Always \"true\" on the unversioned alias. The endpoint still works.", "schema": { "type": "string", "examples": [ "true" ] } }, "Sunset": { "description": "HTTP date after which the unversioned alias may stop working.", "schema": { "type": "string", "examples": [ "Wed, 31 Dec 2031 23:59:59 GMT" ] } }, "Link": { "description": "Points at the versioned replacement and the deprecation notice.", "schema": { "type": "string" } }, "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertUsage" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "convertDocumentLegacy", "summary": "Convert a document to markdown", "description": "Converts a Word, PDF, PowerPoint, Excel, OpenDocument, RTF, EPUB, or CSV document to GitHub-flavored markdown. No authentication. The file is converted in memory and never stored. Maximum size 25 MB. Provide the document as a multipart file, as a JSON body with \"url\" or \"base64\", or as raw bytes with the filename in the X-Filename header.", "tags": [ "convert" ], "deprecated": true, "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Send text/markdown to get the markdown body on its own. Send application/problem+json to get errors as RFC 9457 problem documents. Anything else returns the JSON envelope.", "schema": { "type": "string", "enum": [ "application/json", "text/markdown", "application/problem+json" ], "default": "application/json" } }, { "name": "X-Filename", "in": "header", "required": false, "description": "Same as the filename query parameter, for raw byte uploads.", "schema": { "type": "string", "examples": [ "report.docx" ] } }, { "name": "filename", "in": "query", "required": false, "description": "Filename with extension, used for format detection when the bytes are sent raw. Required for CSV.", "schema": { "type": "string", "examples": [ "report.docx" ] } } ], "requestBody": { "required": true, "description": "The document to convert. Send it as a multipart file, as JSON with a url or base64 field, or as raw bytes.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document to convert." } }, "required": [ "file" ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConvertRequest" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw document bytes." } } } }, "responses": { "200": { "description": "The document was converted. Returns the JSON envelope, or a raw markdown body when Accept is text/markdown.", "headers": { "Deprecation": { "description": "Always \"true\" on the unversioned alias. The endpoint still works.", "schema": { "type": "string", "examples": [ "true" ] } }, "Sunset": { "description": "HTTP date after which the unversioned alias may stop working.", "schema": { "type": "string", "examples": [ "Wed, 31 Dec 2031 23:59:59 GMT" ] } }, "Link": { "description": "Points at the versioned replacement and the deprecation notice.", "schema": { "type": "string" } }, "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResult" } }, "text/markdown": { "schema": { "type": "string", "description": "The converted markdown document." } } } }, "400": { "description": "The request body could not be read.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Request could not be understood", "value": { "type": "https://dawloom.com/developers/errors/#invalid_request", "title": "Request could not be understood", "status": 400, "code": "invalid_request", "detail": "Request could not be understood", "hint": "Check the request body against the OpenAPI schema at https://dawloom.com/api/v1/openapi.json.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "invalid_request" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is larger than 25 MB.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Payload exceeds the size limit", "value": { "type": "https://dawloom.com/developers/errors/#payload_too_large", "title": "Payload exceeds the size limit", "status": 413, "code": "payload_too_large", "detail": "Payload exceeds the size limit", "hint": "The limit is 25 MB. Split the document or send a URL instead of the bytes.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "payload_too_large" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The document was read but could not be converted. The \"code\" field says why: unsupported, malformed, encrypted, resourceLimit, or missingPart.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unprocessable": { "summary": "The document could not be converted", "value": { "type": "https://dawloom.com/developers/errors/#unprocessable", "title": "The document could not be converted", "status": 422, "code": "unprocessable", "detail": "The document could not be converted", "hint": "See \"code\" for the reason. Encrypted files and image-only PDFs cannot be converted.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "unprocessable" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client went over its rate limit.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "type": "https://dawloom.com/developers/errors/#rate_limited", "title": "Too many requests", "status": 429, "code": "rate_limited", "detail": "Too many requests", "hint": "Wait for the number of seconds in Retry-After, then retry.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "rate_limited" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The document URL could not be fetched.", "headers": { "RateLimit": { "description": "Current quota state for this client, as an HTTP structured field: \"policy\";r=;t=.", "schema": { "type": "string", "examples": [ "\"convert\";r=29;t=60" ] } }, "RateLimit-Policy": { "description": "The quota policy in force: \"policy\";q=;w=.", "schema": { "type": "string", "examples": [ "\"convert\";q=30;w=60" ] } }, "RateLimit-Limit": { "description": "Requests allowed in the current window. Sent for clients that read the older field names.", "schema": { "type": "integer", "examples": [ 30 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 29 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-Api-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "examples": [ "v1" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "fetch_failed": { "summary": "The document URL could not be fetched", "value": { "type": "https://dawloom.com/developers/errors/#fetch_failed", "title": "The document URL could not be fetched", "status": 502, "code": "fetch_failed", "detail": "The document URL could not be fetched", "hint": "Check that the URL is public and returns the file directly.", "documentation_url": "https://dawloom.com/developers/", "ok": false, "error": "fetch_failed" } } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": {}, "schemas": { "Problem": { "type": "object", "title": "Problem", "description": "The error object returned by every 4xx and 5xx response, modelled on RFC 9457 problem details.", "properties": { "type": { "type": "string", "format": "uri", "description": "A URL that documents this error code." }, "title": { "type": "string", "description": "A short human-readable summary." }, "status": { "type": "integer", "description": "The HTTP status code." }, "code": { "type": "string", "description": "A stable machine-readable error code. Branch on this.", "enum": [ "invalid_json", "invalid_request", "validation_failed", "not_found", "method_not_allowed", "payload_too_large", "unsupported_media_type", "unprocessable", "rate_limited", "not_configured", "upstream_failed", "fetch_failed" ] }, "detail": { "type": "string", "description": "What went wrong on this specific request." }, "hint": { "type": "string", "description": "What to change before retrying." }, "documentation_url": { "type": "string", "format": "uri" }, "instance": { "type": "string", "description": "The path that produced the error." }, "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Same value as \"code\". Kept for older clients." }, "errors": { "type": "array", "description": "Field-level problems, present on validation failures.", "items": { "$ref": "#/components/schemas/FieldError" } }, "allow": { "type": "string", "description": "Allowed HTTP methods, present on 405 responses." }, "retry_after_seconds": { "type": "integer", "description": "Seconds to wait, present on 429 responses." } }, "required": [ "type", "title", "status", "code", "detail", "hint", "documentation_url", "ok", "error" ] }, "FieldError": { "type": "object", "title": "FieldError", "description": "One field that failed validation.", "properties": { "field": { "type": "string", "description": "The name of the field." }, "code": { "type": "string", "description": "Why it failed, machine-readable." }, "message": { "type": "string", "description": "Why it failed, in plain words." } }, "required": [ "field", "code", "message" ] }, "ApiIndex": { "type": "object", "title": "ApiIndex", "description": "The list of endpoints in this API version.", "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "mcp_url": { "type": "string", "format": "uri" }, "llms_txt_url": { "type": "string", "format": "uri" }, "authentication": { "type": "string", "description": "How to authenticate. \"none\" means no key is needed." }, "rate_limits": { "$ref": "#/components/schemas/RateLimitPolicies" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointSummary" } } }, "required": [ "ok", "service", "version", "endpoints" ] }, "EndpointSummary": { "type": "object", "title": "EndpointSummary", "description": "One endpoint in the index.", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operation_id": { "type": "string" }, "description": { "type": "string" }, "deprecated": { "type": "boolean" } }, "required": [ "method", "path", "operation_id", "description" ] }, "RateLimitPolicies": { "type": "object", "title": "RateLimitPolicies", "description": "The quota in force for each group of endpoints.", "properties": { "read": { "$ref": "#/components/schemas/RateLimitPolicy" }, "convert": { "$ref": "#/components/schemas/RateLimitPolicy" }, "contact": { "$ref": "#/components/schemas/RateLimitPolicy" } } }, "RateLimitPolicy": { "type": "object", "title": "RateLimitPolicy", "description": "A quota expressed as a number of requests per window.", "properties": { "limit": { "type": "integer" }, "window_seconds": { "type": "integer" } }, "required": [ "limit", "window_seconds" ] }, "Health": { "type": "object", "title": "Health", "description": "Service health.", "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" }, "service": { "type": "string" } }, "required": [ "ok", "status", "version" ] }, "FormatList": { "type": "object", "title": "FormatList", "description": "Formats the convert endpoint accepts.", "properties": { "ok": { "type": "boolean", "const": true }, "formats": { "type": "array", "description": "File extensions, without the dot.", "items": { "type": "string", "enum": [ "csv", "doc", "docx", "epub", "odp", "ods", "odt", "pdf", "ppt", "pptx", "rtf", "xls", "xlsx" ] } }, "max_file_size_bytes": { "type": "integer" }, "notes": { "type": "string" } }, "required": [ "ok", "formats", "max_file_size_bytes" ] }, "ConvertRequest": { "type": "object", "title": "ConvertRequest", "description": "A conversion request sent as JSON. Set exactly one of url or base64.", "properties": { "url": { "type": "string", "format": "uri", "description": "Public http or https URL of the document to fetch and convert." }, "base64": { "type": "string", "contentEncoding": "base64", "description": "Base64-encoded document bytes, for local files." }, "filename": { "type": "string", "description": "Filename with extension. Improves format detection and is required for CSV." } }, "anyOf": [ { "required": [ "url" ] }, { "required": [ "base64" ] } ] }, "ConvertResult": { "type": "object", "title": "ConvertResult", "description": "A successful conversion.", "properties": { "ok": { "type": "boolean", "const": true }, "format": { "type": "string", "description": "The format that was detected.", "enum": [ "csv", "doc", "docx", "epub", "odp", "ods", "odt", "pdf", "ppt", "pptx", "rtf", "xls", "xlsx", "auto" ] }, "duration_ms": { "type": "number", "description": "Conversion time in milliseconds." }, "markdown": { "type": "string", "description": "The converted GitHub-flavored markdown." } }, "required": [ "ok", "format", "duration_ms", "markdown" ] }, "ConvertUsage": { "type": "object", "title": "ConvertUsage", "description": "Usage notes for the convert endpoint.", "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string" }, "version": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "mcp_url": { "type": "string", "format": "uri" }, "formats": { "type": "array", "items": { "type": "string" } }, "max_file_size_bytes": { "type": "integer" }, "price": { "type": "string" }, "authentication": { "type": "string" }, "rate_limit": { "$ref": "#/components/schemas/RateLimitPolicy" }, "examples": { "type": "object", "description": "Copy-paste curl commands.", "additionalProperties": { "type": "string" } }, "privacy": { "type": "string" } }, "required": [ "ok", "service", "formats", "max_file_size_bytes" ] }, "ContactRequest": { "type": "object", "title": "ContactRequest", "description": "A project enquiry.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Who is writing." }, "email": { "type": "string", "format": "email", "maxLength": 200, "description": "Where the reply should go." }, "message": { "type": "string", "minLength": 10, "maxLength": 5000, "description": "What you want built." }, "company": { "type": "string", "maxLength": 200, "description": "Optional company name." }, "source": { "type": "string", "maxLength": 100, "description": "Optional: how you found Dawloom." } }, "required": [ "name", "email", "message" ] }, "ContactResult": { "type": "object", "title": "ContactResult", "description": "The enquiry was accepted for delivery.", "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "delivered" ] }, "message": { "type": "string" } }, "required": [ "ok", "status" ] } } } }