{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-index.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Documents","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"style":{"color":"#cdcefb","fontSize":"14px","fontWeight":"700","textTransform":"uppercase","letterSpacing":"0.05em","display":"block","marginBottom":"-30px"}},"children":["Get Started"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"documents","__idx":0},"children":["Documents"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload, store, retrieve, and download reusable source documents."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Documents is the Anesya resource for storing source files in your workspace before downstream processing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use it when you want a stable document ID that can later be reused by:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["list and search workflows"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["operational or audit flows around uploaded files"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do not need a reusable stored file, you can sometimes skip this step and send a file or URL directly to parsing or extract."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-documents-is-for","__idx":1},"children":["What documents is for"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Documents is the right entry point when you want to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["upload one local file to Anesya"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["keep a reusable file reference in the workspace"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["list previously uploaded files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["search documents by filename or metadata"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["download the stored source file later"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["trim a PDF before parsing or extraction"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The common workflow is:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n A[Upload file] --> B[Get document ID]\n B --> C[Create parsing]\n B --> D[Create extract]\n B --> E[Retrieve or download later]\n","diagramHtml":"

Upload file

Get document ID

Create parsing

Create extract

Retrieve or download later

","diagramHtmlDark":"

Upload file

Get document ID

Create parsing

Create extract

Retrieve or download later

"},"children":["flowchart LR\n A[Upload file] --> B[Get document ID]\n B --> C[Create parsing]\n B --> D[Create extract]\n B --> E[Retrieve or download later]\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-start","__idx":2},"children":["Quick start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The most common document workflow has three steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["upload one file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["keep the returned document ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["reuse that ID in parsing or extract"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"upload-a-document","__idx":3},"children":["Upload a document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/schema/documents/document_create"},"children":["Create document"]}," to store a new file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.anesya.app/v0/documents\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\" \\\n -F \"file=@invoice.pdf;type=application/pdf\" \\\n -F \"filename=invoice.pdf\" \\\n -F 'metadata={\"source\":\"api\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"300f339f-da71-4f9f-80f6-c25a63baae75\",\n \"filename\": \"invoice.pdf\",\n \"file_url\": \"/v0/documents/300f339f-da71-4f9f-80f6-c25a63baae75/download\",\n \"metadata\": {\n \"source\": \"api\"\n },\n \"page_count\": 3,\n \"created_at\": \"2025-06-12T14:56:10.682461Z\",\n \"updated_at\": \"2025-06-12T14:56:10.682461Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},". This is the document ID you can reuse later."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reuse-the-document-in-parsing","__idx":4},"children":["Reuse the document in parsing"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.anesya.app/v0/parsing\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"YOUR_DOCUMENT_ID\",\n \"model\": \"PIGALLE\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reuse-the-document-in-extract","__idx":5},"children":["Reuse the document in extract"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.anesya.app/v0/extract\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"YOUR_DOCUMENT_ID\",\n \"schema\": \"YOUR_SCHEMA_ID\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-get-back","__idx":6},"children":["What you get back"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The document resource returned by create, retrieve, and list contains:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"300f339f-da71-4f9f-80f6-c25a63baae75\",\n \"filename\": \"invoice.pdf\",\n \"file_url\": \"/v0/documents/300f339f-da71-4f9f-80f6-c25a63baae75/download\",\n \"metadata\": {\n \"source\": \"api\"\n },\n \"page_count\": 3,\n \"created_at\": \"2025-06-12T14:56:10.682461Z\",\n \"updated_at\": \"2025-06-12T14:56:10.682461Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-fields","__idx":7},"children":["Key fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it contains"},"children":["What it contains"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stable document identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filename"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stored file name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Relative download endpoint for this file"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom metadata object"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_count"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of pages in the stored document"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creation timestamp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last update timestamp"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoints","__idx":8},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The documents resource exposes four public actions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post-v0documents","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/documents"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload one new file and create a document resource."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"multipart-fields","__idx":10},"children":["Multipart fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["binary"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Source document file"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filename"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional filename override"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional metadata object"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"query-parameters","__idx":11},"children":["Query parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pdf_page_start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional first PDF page to keep"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pdf_page_end"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional last PDF page to keep"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This PDF trimming happens at upload time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is useful when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the original PDF is larger than the subset you need"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you want to reduce downstream parsing work"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["only a known page range matters"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-v0documents","__idx":12},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List documents in the workspace."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"query-parameters-1","__idx":13},"children":["Query parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page size"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search in filename and metadata values"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_after"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["date-time"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter lower bound"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_before"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["date-time"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter upper bound"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-v0documentsid","__idx":14},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve one document by its UUID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-v0documentsiddownload","__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}/download"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get the download URL for the stored file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Important behavior:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the documented response is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["clients that want the actual file should follow the redirect"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-format-details","__idx":16},"children":["Response format details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Documents has three main response shapes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-or-retrieve","__idx":17},"children":["Create or retrieve"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/documents"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}"]}," return one document object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-documents","__idx":18},"children":["List documents"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents"]}," returns a paginated resource:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": \"300f339f-da71-4f9f-80f6-c25a63baae75\",\n \"filename\": \"invoice.pdf\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"download-document","__idx":19},"children":["Download document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}/download"]}," does not return the normal document object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead, it redirects to the underlying file URL."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"search-and-filtering","__idx":20},"children":["Search and filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Document listing supports lightweight search and date filtering."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"search","__idx":21},"children":["Search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," query parameter to search in:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the document filename"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["metadata values"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.anesya.app/v0/documents?search=invoice\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"date-filtering","__idx":22},"children":["Date filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_after"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_before"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.anesya.app/v0/documents?created_at_after=2026-04-01T00:00:00Z&created_at_before=2026-04-30T23:59:59Z\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-documents-vs-direct-parsing-or-extract","__idx":23},"children":["When to use documents vs direct parsing or extract"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use documents first when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the file should be reused later"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you want a stable internal document ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the workflow may involve several downstream steps"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the source file should be discoverable in list views"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you want to trim a PDF once and reuse the trimmed version"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Skip documents and go directly to parsing or extract when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you only need one one-off processing call"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the file is already available as a public or pre-signed URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you do not need a stored document lifecycle"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":24},"children":["Best practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-use-documents-when-reuse-matters","__idx":25},"children":["1. Use documents when reuse matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the same file may be parsed again, extracted again, or audited later, upload it first and keep the document ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-use-metadata-intentionally","__idx":26},"children":["2. Use metadata intentionally"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Good metadata makes list and search workflows much easier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical metadata examples:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["source system"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["customer ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["import batch identifier"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["internal reference number"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-trim-pdfs-early-when-only-part-of-the-file-matters","__idx":27},"children":["3. Trim PDFs early when only part of the file matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you only need a subset of pages, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pdf_page_start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pdf_page_end"]}," at upload time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This avoids carrying an oversized document through the rest of the pipeline."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-treat-the-document-id-as-the-canonical-reusable-reference","__idx":28},"children":["4. Treat the document ID as the canonical reusable reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once a document is uploaded, reuse the UUID rather than re-uploading the same file repeatedly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-follow-redirects-for-download","__idx":29},"children":["5. Follow redirects for download"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you call the download endpoint programmatically, make sure your client follows ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}," redirects or handles the redirected URL explicitly."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-pitfalls","__idx":30},"children":["Common pitfalls"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"re-uploading-the-same-file-every-time","__idx":31},"children":["Re-uploading the same file every time"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the file is meant to be reused, upload it once and keep the document ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"forgetting-that-search-includes-metadata-values","__idx":32},"children":["Forgetting that search includes metadata values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If search results seem broader than expected, remember that metadata values are part of the search surface."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expecting-the-download-endpoint-to-return-json","__idx":33},"children":["Expecting the download endpoint to return JSON"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The documented behavior is a redirect, not a standard document object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"forgetting-pdf-trimming-is-applied-at-upload-time","__idx":34},"children":["Forgetting PDF trimming is applied at upload time"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you trim pages during upload, the stored document itself reflects that subset."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That is usually desirable, but it should be intentional."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":35},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized","__idx":36},"children":["401 Unauthorized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your API key is missing or invalid. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"404-not-found-on-retrieve-or-download","__idx":37},"children":["404 Not Found on retrieve or download"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The document ID does not exist, is not accessible in the current workspace context, or the file is missing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"upload-fails-with-validation-errors","__idx":38},"children":["Upload fails with validation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}," field is present"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the multipart request is correctly formed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the PDF trim parameters are valid if you used them"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"download-does-not-return-the-file-body","__idx":39},"children":["Download does not return the file body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your client may not be following redirects automatically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}," response correctly."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":40},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["API quickstart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/parsing"},"children":["Parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/extract"},"children":["Extract"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/extract"},"children":["Extract guide"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/agent-guide"},"children":["Anesya API Reference for Coding Agents"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/schema/documents/document_create"},"children":["API reference"]}]}]}]},"headings":[{"value":"Documents","id":"documents","depth":1},{"value":"What documents is for","id":"what-documents-is-for","depth":2},{"value":"Quick start","id":"quick-start","depth":2},{"value":"Upload a document","id":"upload-a-document","depth":3},{"value":"Reuse the document in parsing","id":"reuse-the-document-in-parsing","depth":3},{"value":"Reuse the document in extract","id":"reuse-the-document-in-extract","depth":3},{"value":"What you get back","id":"what-you-get-back","depth":2},{"value":"Key fields","id":"key-fields","depth":3},{"value":"Endpoints","id":"endpoints","depth":2},{"value":"POST /v0/documents","id":"post-v0documents","depth":3},{"value":"Multipart fields","id":"multipart-fields","depth":4},{"value":"Query parameters","id":"query-parameters","depth":4},{"value":"GET /v0/documents","id":"get-v0documents","depth":3},{"value":"Query parameters","id":"query-parameters-1","depth":4},{"value":"GET /v0/documents/{id}","id":"get-v0documentsid","depth":3},{"value":"GET /v0/documents/{id}/download","id":"get-v0documentsiddownload","depth":3},{"value":"Response format details","id":"response-format-details","depth":2},{"value":"Create or retrieve","id":"create-or-retrieve","depth":3},{"value":"List documents","id":"list-documents","depth":3},{"value":"Download document","id":"download-document","depth":3},{"value":"Search and filtering","id":"search-and-filtering","depth":2},{"value":"Search","id":"search","depth":3},{"value":"Date filtering","id":"date-filtering","depth":3},{"value":"When to use documents vs direct parsing or extract","id":"when-to-use-documents-vs-direct-parsing-or-extract","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"1. Use documents when reuse matters","id":"1-use-documents-when-reuse-matters","depth":3},{"value":"2. Use metadata intentionally","id":"2-use-metadata-intentionally","depth":3},{"value":"3. Trim PDFs early when only part of the file matters","id":"3-trim-pdfs-early-when-only-part-of-the-file-matters","depth":3},{"value":"4. Treat the document ID as the canonical reusable reference","id":"4-treat-the-document-id-as-the-canonical-reusable-reference","depth":3},{"value":"5. Follow redirects for download","id":"5-follow-redirects-for-download","depth":3},{"value":"Common pitfalls","id":"common-pitfalls","depth":2},{"value":"Re-uploading the same file every time","id":"re-uploading-the-same-file-every-time","depth":3},{"value":"Forgetting that search includes metadata values","id":"forgetting-that-search-includes-metadata-values","depth":3},{"value":"Expecting the download endpoint to return JSON","id":"expecting-the-download-endpoint-to-return-json","depth":3},{"value":"Forgetting PDF trimming is applied at upload time","id":"forgetting-pdf-trimming-is-applied-at-upload-time","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"401 Unauthorized","id":"401-unauthorized","depth":3},{"value":"404 Not Found on retrieve or download","id":"404-not-found-on-retrieve-or-download","depth":3},{"value":"Upload fails with validation errors","id":"upload-fails-with-validation-errors","depth":3},{"value":"Download does not return the file body","id":"download-does-not-return-the-file-body","depth":3},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Documents"}},"lastModified":"2026-04-22T15:07:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/tutorials/documents","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}