{"openapi":"3.1.0","info":{"title":"RagBytes API","description":"\nTurn PDFs, Word documents, web pages, Markdown and plain text into chunks that are ready to embed.\n\nEach chunking tier has its own endpoint: upload a file as `multipart/form-data` to\n`POST /v1/chunk/basic` or `POST /v1/chunk/structured`. Each chunk comes back with `embed_text` (its\nheading path, a blank line, then its text) to send to your embedding model, `content` to store\nalongside the vector, and `metadata` describing where it came from.\n\nUploads are processed in memory and discarded once the response is sent. The service only keeps a\nrunning count of documents chunked and chunks returned. Requests are limited to 50 MB, about 100\nseconds, and a few per second from one address.\n","version":"f4d9ea56cf8cd92d1b433a20bb3e1d8f262b9363"},"paths":{"/v1/methods":{"get":{"tags":["service"],"summary":"List Methods","description":"List the chunking tiers, the endpoint for each, and the file types this service accepts.","operationId":"list_methods_v1_methods_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodsResponse"}}}}}}},"/v1/stats":{"get":{"tags":["service"],"summary":"Usage Stats","description":"Count the documents chunked and the chunks returned. No document content is kept.","operationId":"usage_stats_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}},"/v1/chunk/basic":{"post":{"tags":["chunking"],"summary":"Basic: fixed-size chunks","description":"About 2,000 characters per chunk with a 200-character overlap. Small paragraphs under one heading are packed together, and long tables split between rows.","operationId":"chunk_basic_v1_chunk_basic_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ChunkUpload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChunkResponse"}}}},"400":{"description":"The file could not be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"The filename suffix is not a supported file type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chunk/structured":{"post":{"tags":["chunking"],"summary":"Structured: follows titles and sections","description":"Chunks follow the document's heading tree. Each section becomes one chunk where it fits, small neighbouring sections are merged under their shared heading, and long sections are split evenly.","operationId":"chunk_structured_v1_chunk_structured_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ChunkUpload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChunkResponse"}}}},"400":{"description":"The file could not be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"The filename suffix is not a supported file type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["service"],"summary":"Health","description":"Report that the service is up and which build it is running.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"schemas":{"Chunk":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"metadata":{"$ref":"#/components/schemas/ChunkMetadata"},"embed_text":{"type":"string","title":"Embed Text","description":"Heading path and chunk text, ready to embed. An image or complex region uses its label."},"content":{"type":"string","title":"Content"}},"type":"object","required":["metadata","embed_text","content"],"title":"Chunk","description":"One piece of a file.\n\n``chunk_id`` identifies this chunk. A section split into several chunks\ngets a new id on each one. ``metadata`` is written before ``content``.\n``embed_text`` is the string to embed: the heading path, a blank line,\nthen the chunk's text, or its label when the chunk is an image or a\ncomplex region. ``content`` is the one value for this chunk: the text, or\nthe original bytes of an image or complex region. ``metadata.format``\nsays which it is. Bytes are base64 in the response."},"ChunkDetails":{"properties":{"start":{"type":"integer","title":"Start","description":"Start offset in the chunked document text."},"end":{"type":"integer","title":"End","description":"End offset in the chunked document text."}},"type":"object","required":["start","end"],"title":"ChunkDetails","description":"Where this chunk sits in the chunked document text."},"ChunkMetadata":{"properties":{"filename":{"type":"string","title":"Filename"},"file_id":{"type":"string","title":"File Id"},"chunk_number":{"type":"integer","title":"Chunk Number","description":"Place of this chunk in the response, starting at 0."},"headings":{"items":{"type":"string"},"type":"array","title":"Headings"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"subheading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subheading"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page"},"format":{"type":"string","enum":["text","list","table","image","chart","code","complex"],"title":"Format"},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Media Type"},"details":{"$ref":"#/components/schemas/ChunkDetails"}},"type":"object","required":["filename","file_id","chunk_number","format","details"],"title":"ChunkMetadata"},"ChunkResponse":{"properties":{"filename":{"type":"string","title":"Filename"},"file_id":{"type":"string","title":"File Id"},"chunks":{"items":{"$ref":"#/components/schemas/Chunk"},"type":"array","title":"Chunks"}},"type":"object","required":["filename","file_id","chunks"],"title":"ChunkResponse"},"ChunkUpload":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document to chunk. Its filename must end in one of: .pdf, .docx, .html, .htm, .md, .markdown, .txt."}},"type":"object","required":["file"],"title":"ChunkUpload"},"ChunkingMethod":{"properties":{"name":{"type":"string","title":"Name","description":"Tier name."},"path":{"type":"string","title":"Path","description":"Endpoint to POST a file to for this tier."},"description":{"type":"string","title":"Description"}},"type":"object","required":["name","path","description"],"title":"ChunkingMethod"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","const":"ok","title":"Status","default":"ok"},"version":{"type":"string","title":"Version","description":"Commit SHA the running image was built from, or dev."}},"type":"object","required":["version"],"title":"HealthResponse"},"MethodsResponse":{"properties":{"methods":{"items":{"$ref":"#/components/schemas/ChunkingMethod"},"type":"array","title":"Methods"},"file_types":{"items":{"type":"string"},"type":"array","title":"File Types","description":"Filename suffixes that can be uploaded."}},"type":"object","required":["methods","file_types"],"title":"MethodsResponse"},"StatsResponse":{"properties":{"documents":{"type":"integer","title":"Documents","description":"Documents chunked since the service started counting."},"chunks":{"type":"integer","title":"Chunks","description":"Chunks returned for those documents."}},"type":"object","required":["documents","chunks"],"title":"StatsResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"chunking","description":"Split a document into chunks. One endpoint per tier."},{"name":"service","description":"Check the service is running and how much it has chunked."}]}