{
  "openapi": "3.0.3",
  "info": {
    "title": "OCR & PDF to Markdown API",
    "version": "0.1.0",
    "description": "Callable Labs public endpoint reference. Obtain the base URL and credentials from the marketplace listing. Availability can differ by marketplace."
  },
  "paths": {
    "/v1/ocr/image": {
      "post": {
        "tags": [
          "Read images & PDFs"
        ],
        "summary": "Read an image (OCR to Markdown)",
        "description": "Send one photo, scan or screenshot by URL, base64 or file upload. The JSON\nresponse carries the page as Markdown and as plain text, every table as HTML,\nMarkdown and cell rows, and typed blocks (title, heading, text, table, formula,\nchart, …) with bounding boxes in reading order.\n\n`format: markdown` or `format: text` returns just the page as `text/markdown`\nor `text/plain`. Use `mode: auto` (default) for varied documents, `layout`\nfor structured blocks, or `plain` for a single text block.\n\n**More examples**\n\n*Markdown only*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg\"\n  },\n  \"format\": \"markdown\"\n}\n```\n\n*Plain text, read as one block*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg\"\n  },\n  \"mode\": \"plain\",\n  \"format\": \"text\"\n}\n```",
        "operationId": "Read image",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageRequest"
              },
              "example": {
                "image": {
                  "url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg"
                },
                "format": "json"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image (PNG, JPEG, WebP, GIF, BMP or TIFF; ≤ 20 MB)"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "markdown",
                      "text"
                    ],
                    "description": "`json`: Markdown, text, blocks and tables; `markdown`: the page as `text/markdown`; `text`: plain text.",
                    "default": "json"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "layout",
                      "plain"
                    ],
                    "description": "auto (default) for varied documents; layout for structured blocks; plain for a single text block.",
                    "default": "auto"
                  },
                  "charts": {
                    "type": "boolean",
                    "description": "Turn bar, line and pie charts into data tables.",
                    "default": true
                  },
                  "include_blocks": {
                    "type": "boolean",
                    "description": "Include `blocks` (type, order, bounding box, content) in the JSON.",
                    "default": true
                  }
                },
                "type": "object",
                "required": [
                  "file"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The page: JSON (Markdown, text, blocks, tables), or `text/markdown` / `text/plain` per `format`",
            "headers": {
              "X-Page-Count": {
                "description": "Documents: total pages",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OcrResult"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed. Verify the RapidAPI subscription and generated request headers."
          },
          "413": {
            "description": "The request body exceeds the configured gateway or endpoint limit."
          },
          "422": {
            "description": "`invalid_request`: a field failed the schema (`errors[].loc` names it). `bad_image`: not a decodable image. `image_too_large`: over 40 megapixels. `file_too_large`: over 20 MB. `invalid_url`, `url_unreachable`, `private_address_blocked`, `invalid_base64`: the file could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "The subscriber's rate limit or monthly request allowance was exceeded."
          },
          "502": {
            "description": "Processing failed temporarily. Retry with bounded backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The service is busy or temporarily unavailable. Honor Retry-After and use bounded retries.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Processing exceeded the time limit. Try a smaller or simpler input if the error repeats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/ocr/document": {
      "post": {
        "tags": [
          "Read images & PDFs"
        ],
        "summary": "Read a PDF page",
        "description": "Read one page of a PDF — scanned or digital — into the same Markdown, text,\ntables and blocks. The response says how many pages there are (`page.count`,\n`X-Page-Count`); request `page: 2`, `3`, … to walk the document. Each page\nis a separate request. Use a URL or upload the PDF with each page request.\n\n**More examples**\n\n*Another page as Markdown*\n\n```json\n{\n  \"document\": {\n    \"url\": \"https://arxiv.org/pdf/1706.03762v7\"\n  },\n  \"page\": 3,\n  \"format\": \"markdown\"\n}\n```\n\n*A scan at higher resolution*\n\n```json\n{\n  \"document\": {\n    \"url\": \"https://arxiv.org/pdf/1706.03762v7\"\n  },\n  \"page\": 1,\n  \"dpi\": 300,\n  \"format\": \"text\"\n}\n```",
        "operationId": "Read PDF page",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentRequest"
              },
              "example": {
                "document": {
                  "url": "https://arxiv.org/pdf/1706.03762v7"
                },
                "page": 1,
                "format": "json"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The PDF (≤ 20 MB, ≤ 1,000 pages)"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "markdown",
                      "text"
                    ],
                    "description": "`json`: Markdown, text, blocks and tables; `markdown`: the page as `text/markdown`; `text`: plain text.",
                    "default": "json"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "layout",
                      "plain"
                    ],
                    "description": "auto (default) for varied documents; layout for structured blocks; plain for a single text block.",
                    "default": "auto"
                  },
                  "charts": {
                    "type": "boolean",
                    "description": "Turn bar, line and pie charts into data tables.",
                    "default": true
                  },
                  "include_blocks": {
                    "type": "boolean",
                    "description": "Include `blocks` (type, order, bounding box, content) in the JSON.",
                    "default": true
                  },
                  "page": {
                    "type": "integer",
                    "maximum": 1000,
                    "minimum": 1,
                    "description": "1-based page to read; the response carries `page.count` so you can loop.",
                    "default": 1
                  },
                  "dpi": {
                    "type": "integer",
                    "maximum": 300,
                    "minimum": 72,
                    "description": "Rendering resolution for the page (capped at 25 megapixels).",
                    "default": 200
                  }
                },
                "type": "object",
                "required": [
                  "file"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The page: JSON (Markdown, text, blocks, tables), or `text/markdown` / `text/plain` per `format`",
            "headers": {
              "X-Page-Count": {
                "description": "Documents: total pages",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OcrResult"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed. Verify the RapidAPI subscription and generated request headers."
          },
          "413": {
            "description": "The request body exceeds the configured gateway or endpoint limit."
          },
          "422": {
            "description": "`invalid_request`: a field failed the schema (`errors[].loc` names it). `bad_document`: not a readable PDF. `document_encrypted`: needs a password. `document_too_large`: over 1,000 pages. `page_out_of_range`: `page` is past the end (`page_count` says how many there are). `file_too_large`: over 20 MB. `invalid_url`, `url_unreachable`, `private_address_blocked`, `invalid_base64`: the file could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "The subscriber's rate limit or monthly request allowance was exceeded."
          },
          "502": {
            "description": "Processing failed temporarily. Retry with bounded backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The service is busy or temporarily unavailable. Honor Retry-After and use bounded retries.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Processing exceeded the time limit. Try a smaller or simpler input if the error repeats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ImageRequest": {
        "additionalProperties": false,
        "properties": {
          "format": {
            "default": "json",
            "description": "`json`: Markdown, text, blocks and tables; `markdown`: the page as `text/markdown`; `text`: plain text.",
            "enum": [
              "json",
              "markdown",
              "text"
            ],
            "title": "Format",
            "type": "string"
          },
          "mode": {
            "default": "auto",
            "description": "auto (default) for varied documents; layout for structured blocks; plain for a single text block.",
            "enum": [
              "auto",
              "layout",
              "plain"
            ],
            "title": "Mode",
            "type": "string"
          },
          "charts": {
            "default": true,
            "description": "Turn bar, line and pie charts into data tables.",
            "title": "Charts",
            "type": "boolean"
          },
          "include_blocks": {
            "default": true,
            "description": "Include `blocks` (type, order, bounding box, content) in the JSON.",
            "title": "Include Blocks",
            "type": "boolean"
          },
          "image": {
            "$ref": "#/components/schemas/ImageSource"
          }
        },
        "required": [
          "image"
        ],
        "title": "ImageRequest",
        "type": "object"
      },
      "ImageSource": {
        "additionalProperties": false,
        "properties": {
          "url": {
            "maxLength": 2048,
            "type": "string",
            "nullable": true,
            "title": "Url",
            "description": "Public http(s) URL of the image (≤ 20 MB). Private and internal addresses are refused.",
            "default": null,
            "example": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg"
          },
          "base64": {
            "maxLength": 27962090,
            "type": "string",
            "nullable": true,
            "title": "Base64",
            "description": "The image as base64 (a `data:` URI is fine), ≤ 20 MB decoded.",
            "default": null
          }
        },
        "title": "ImageSource",
        "type": "object"
      },
      "OcrResult": {
        "properties": {
          "markdown": {
            "title": "Markdown",
            "type": "string"
          },
          "text": {
            "title": "Text",
            "type": "string"
          },
          "blocks": {
            "items": {
              "$ref": "#/components/schemas/Block"
            },
            "title": "Blocks",
            "type": "array"
          },
          "tables": {
            "items": {
              "$ref": "#/components/schemas/Table"
            },
            "title": "Tables",
            "type": "array"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "markdown",
          "text",
          "blocks",
          "tables",
          "page"
        ],
        "title": "OcrResult",
        "type": "object",
        "additionalProperties": true
      },
      "Block": {
        "properties": {
          "type": {
            "description": "title, heading, text, table, formula, chart, image, caption, footnote, header, footer, page_number, code, seal, other",
            "title": "Type",
            "type": "string"
          },
          "order": {
            "description": "Reading order, from 0",
            "title": "Order",
            "type": "integer"
          },
          "bbox": {
            "description": "[x1, y1, x2, y2] in page pixels",
            "items": {
              "type": "integer"
            },
            "title": "Bbox",
            "type": "array"
          },
          "content": {
            "description": "Text (Markdown for tables, LaTeX for formulas)",
            "title": "Content",
            "type": "string"
          },
          "html": {
            "type": "string",
            "nullable": true,
            "title": "Html",
            "description": "Tables and charts: the table as HTML",
            "default": null
          },
          "markdown": {
            "type": "string",
            "nullable": true,
            "title": "Markdown",
            "description": "Tables and charts: the table as Markdown",
            "default": null
          },
          "latex": {
            "type": "string",
            "nullable": true,
            "title": "Latex",
            "description": "Formulas: LaTeX",
            "default": null
          }
        },
        "required": [
          "type",
          "order",
          "bbox",
          "content"
        ],
        "title": "Block",
        "type": "object",
        "additionalProperties": true
      },
      "Table": {
        "properties": {
          "order": {
            "title": "Order",
            "type": "integer"
          },
          "type": {
            "description": "table, or chart when a chart was turned into data",
            "title": "Type",
            "type": "string"
          },
          "bbox": {
            "items": {
              "type": "integer"
            },
            "title": "Bbox",
            "type": "array"
          },
          "html": {
            "title": "Html",
            "type": "string"
          },
          "markdown": {
            "title": "Markdown",
            "type": "string"
          },
          "rows": {
            "description": "Cell text by row; merged cells repeated across their span",
            "items": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "title": "Rows",
            "type": "array"
          }
        },
        "required": [
          "order",
          "type",
          "bbox",
          "html",
          "markdown",
          "rows"
        ],
        "title": "Table",
        "type": "object"
      },
      "PageInfo": {
        "properties": {
          "width": {
            "title": "Width",
            "type": "integer"
          },
          "height": {
            "title": "Height",
            "type": "integer"
          },
          "index": {
            "type": "integer",
            "nullable": true,
            "title": "Index",
            "description": "Documents: the 1-based page that was read",
            "default": null
          },
          "count": {
            "type": "integer",
            "nullable": true,
            "title": "Count",
            "description": "Documents: total pages",
            "default": null
          },
          "dpi": {
            "type": "integer",
            "nullable": true,
            "title": "Dpi",
            "description": "Documents: rendering resolution used",
            "default": null
          }
        },
        "required": [
          "width",
          "height"
        ],
        "title": "PageInfo",
        "type": "object"
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable failure code"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation"
              },
              "errors": {
                "type": "array",
                "description": "Per-field or per-line detail when there is more than one thing to fix",
                "items": {
                  "type": "object",
                  "properties": {
                    "loc": {
                      "type": "string",
                      "description": "Field path, e.g. `body.scale`"
                    },
                    "line": {
                      "type": "integer"
                    },
                    "column": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "additionalProperties": true
          }
        }
      },
      "DocumentRequest": {
        "additionalProperties": false,
        "properties": {
          "format": {
            "default": "json",
            "description": "`json`: Markdown, text, blocks and tables; `markdown`: the page as `text/markdown`; `text`: plain text.",
            "enum": [
              "json",
              "markdown",
              "text"
            ],
            "title": "Format",
            "type": "string"
          },
          "mode": {
            "default": "auto",
            "description": "auto (default) for varied documents; layout for structured blocks; plain for a single text block.",
            "enum": [
              "auto",
              "layout",
              "plain"
            ],
            "title": "Mode",
            "type": "string"
          },
          "charts": {
            "default": true,
            "description": "Turn bar, line and pie charts into data tables.",
            "title": "Charts",
            "type": "boolean"
          },
          "include_blocks": {
            "default": true,
            "description": "Include `blocks` (type, order, bounding box, content) in the JSON.",
            "title": "Include Blocks",
            "type": "boolean"
          },
          "page": {
            "default": 1,
            "description": "1-based page to read; the response carries `page.count` so you can loop.",
            "maximum": 1000,
            "minimum": 1,
            "title": "Page",
            "type": "integer"
          },
          "dpi": {
            "default": 200,
            "description": "Rendering resolution for the page (capped at 25 megapixels).",
            "maximum": 300,
            "minimum": 72,
            "title": "Dpi",
            "type": "integer"
          },
          "document": {
            "$ref": "#/components/schemas/DocumentSource"
          }
        },
        "required": [
          "document"
        ],
        "title": "DocumentRequest",
        "type": "object"
      },
      "DocumentSource": {
        "additionalProperties": false,
        "properties": {
          "url": {
            "maxLength": 2048,
            "type": "string",
            "nullable": true,
            "title": "Url",
            "description": "Public http(s) PDF URL, up to 20 MiB. Private and internal addresses are refused.",
            "default": null
          },
          "base64": {
            "maxLength": 27962090,
            "type": "string",
            "nullable": true,
            "title": "Base64",
            "description": "The PDF as base64 (a `data:` URI is fine), ≤ 20 MB decoded.",
            "default": null
          }
        },
        "title": "DocumentSource",
        "type": "object"
      }
    }
  }
}