Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.
PUT
/
api
/
documents
TypeScript SDK
import { Orchata } from '@orchata-ai/sdk';const client = new Orchata({ apiKey: 'oai_your_api_key' });// Create or update - idempotent operationconst { document, created } = await client.documents.upsert({ spaceId: 'space_123', filename: 'to-do.md', content: '# To-Do List\n\n- [x] First task\n- [ ] Second task'});console.log(created ? 'Created new document' : 'Updated existing document');
Whether a new document was created (true) or existing updated (false)
Was this page helpful?
⌘I
{"docsConfig":{"theme":"linden","$schema":"https://mintlify.com/docs.json","name":"Orchata","colors":{"primary":"#FA8565","light":"#FA8565","dark":"#FA8565"},"logo":{"light":"https://cdn.orchata.ai/img/orchata-logo-light.svg","dark":"https://cdn.orchata.ai/img/orchata-logo-dark.svg"},"favicon":"/favicon.ico","background":{"decoration":"grid","color":{"light":"#FDF5DF","dark":"#1C1827"}},"navbar":{"links":[{"href":"mailto:support@orchata.ai","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.orchata.ai"}},"footer":{"socials":{"github":"https://github.com/orchata-ai"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Back to Site","icon":"home","href":"https://orchata.ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"orchatalabs","hasAudioNarration":false,"actualSubdomain":"orchatalabs","customDomains":["orchata.ai"],"gitSource":{"type":"github","owner":"orchata-ai","repo":"orchata-rag","deployBranch":"develop","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6ae940c687cae518f465a8c7:success","clientVersion":"0.0.4111","searchFilterCounts":[{"language":"default","tag":"API Reference","count":22},{"language":"default","tag":"Endpoints","count":21},{"language":"default","tag":"Guides","count":18},{"language":"default","tag":"Documents","count":10},{"language":"default","tag":"Spaces","count":6},{"language":"default","tag":"Getting Started","count":5},{"language":"default","tag":"AI Tool Setup","count":4},{"language":"default","tag":"TypeScript SDK","count":4},{"language":"default","tag":"MCP Server","count":3},{"language":"default","tag":"Admin","count":3}]},"assistantConfig":{"enableStarterQuestions":false},"basePath":"/docs","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/documents/upsert-document","slug":"/api-reference/documents/upsert-document","pageMetadata":{"title":"Upsert Document","description":"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.","deprecated":null,"version":null,"openapi":"api/openapi.json put /api/documents","href":"/api-reference/documents/upsert-document","autogeneratedByOpenApi":true,"hidden":false},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Upsert Document","description":"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.","deprecated":null,"version":null,"openapi":"api/openapi.json put /api/documents","href":"/api-reference/documents/upsert-document","autogeneratedByOpenApi":true,"hidden":false}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Documents"],"summary":"Upsert Document","description":"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.","x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Orchata } from '@orchata-ai/sdk';\n\nconst client = new Orchata({ apiKey: 'oai_your_api_key' });\n\n// Create or update - idempotent operation\nconst { document, created } = await client.documents.upsert({\n spaceId: 'space_123',\n filename: 'to-do.md',\n content: '# To-Do List\\n\\n- [x] First task\\n- [ ] Second task'\n});\n\nconsole.log(created ? 'Created new document' : 'Updated existing document');"}],"requestBody":"ede8f7de-340a-4a90-967c-61a2bef269e9","responses":{"200":"2e6334a2-9e3e-4388-aa4c-c8dc9ce854d9","401":"ca5c82af-470e-4c97-80a4-94a2f729c0e0","403":"e17a02df-73d9-4b39-89f1-9bfdeb1b1bd4","404":"594cad6a-e0ef-4387-9ada-e840fe4c7336"},"method":"put","type":"path","servers":["27616fde-a7f5-4ae5-a362-1fb86892a734"],"security":["c7c83795-2758-4207-b371-e5b1dceae23c"],"path":"/api/documents","baseUrlOptions":["https://api.orchata.ai"],"title":"Upsert Document","codeSamples":[{"label":"TypeScript SDK","lang":"typescript","source":"import { Orchata } from '@orchata-ai/sdk';\n\nconst client = new Orchata({ apiKey: 'oai_your_api_key' });\n\n// Create or update - idempotent operation\nconst { document, created } = await client.documents.upsert({\n spaceId: 'space_123',\n filename: 'to-do.md',\n content: '# To-Do List\\n\\n- [x] First task\\n- [ ] Second task'\n});\n\nconsole.log(created ? 'Created new document' : 'Updated existing document');"}],"requiredOnlyExamples":false,"requestExampleType":"codeSamples","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"description":"Upsert document request","content":{"application/json":{"schema":{"type":"object","properties":{"spaceId":{"type":"string","description":"The ID of the space","example":"space_123","isRequired":true,"uniqueKey":"spaceId","typeLabel":"string"},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Filename to create or update","example":"my-notes.md","isRequired":true,"uniqueKey":"filename","typeLabel":"string"},"content":{"type":"string","minLength":1,"maxLength":10000000,"description":"The document content (max 10MB)","example":"# My Notes\n\nSome content...","isRequired":true,"uniqueKey":"content","typeLabel":"string"},"metadata":{"type":"object","additionalProperties":{"oneOf":[{}],"uniqueKey":"metadata.additionalProperties","typeLabel":"any"},"description":"Optional metadata to attach to the document","uniqueKey":"metadata","typeLabel":"object"}},"required":["spaceId","filename","content"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"spaceId":"space_123","filename":"my-notes.md","content":"# My Notes\n\nSome content...","metadata":{}}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"2e6334a2-9e3e-4388-aa4c-c8dc9ce854d9":{"description":"Document created or updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","isRequired":true,"uniqueKey":"document.id","typeLabel":"string"},"orgId":{"type":"string","isRequired":true,"uniqueKey":"document.orgId","typeLabel":"string"},"spaceId":{"type":"string","isRequired":true,"uniqueKey":"document.spaceId","typeLabel":"string"},"filename":{"type":"string","isRequired":true,"uniqueKey":"document.filename","typeLabel":"string"},"mimeType":{"type":"string","isRequired":true,"uniqueKey":"document.mimeType","typeLabel":"string"},"fileSize":{"type":"string","isRequired":true,"uniqueKey":"document.fileSize","typeLabel":"string"},"storageUrl":{"type":"string","isRequired":true,"uniqueKey":"document.storageUrl","typeLabel":"string"},"status":{"type":"string","isRequired":true,"uniqueKey":"document.status","typeLabel":"string"},"errorMessage":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"document.errorMessage.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"document.errorMessage.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"document.errorMessage","typeLabel":"string | null"},"embeddingModel":{"type":"string","isRequired":true,"uniqueKey":"document.embeddingModel","typeLabel":"string"},"indexingType":{"type":"string","isRequired":true,"uniqueKey":"document.indexingType","typeLabel":"string"},"createdAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"document.createdAt","typeLabel":"string\u003cdate-time>"},"updatedAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"document.updatedAt","typeLabel":"string\u003cdate-time>"},"metadata":{"oneOf":[{}],"uniqueKey":"document.metadata","typeLabel":"any"}},"required":["id","orgId","spaceId","filename","mimeType","fileSize","storageUrl","status","errorMessage","embeddingModel","indexingType","createdAt","updatedAt"],"isRequired":true,"uniqueKey":"document","typeLabel":"object"},"created":{"type":"boolean","description":"Whether a new document was created (true) or existing updated (false)","isRequired":true,"uniqueKey":"created","typeLabel":"boolean"}},"required":["document","created"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"document":{"id":"\u003cstring>","orgId":"\u003cstring>","spaceId":"\u003cstring>","filename":"\u003cstring>","mimeType":"\u003cstring>","fileSize":"\u003cstring>","storageUrl":"\u003cstring>","status":"\u003cstring>","errorMessage":"\u003cstring>","embeddingModel":"\u003cstring>","indexingType":"\u003cstring>","createdAt":"2023-11-07T05:31:56Z","updatedAt":"2023-11-07T05:31:56Z","metadata":"\u003cunknown>"},"created":true}}},"exampleType":"generated"}},"exampleType":"generated"},"ca5c82af-470e-4c97-80a4-94a2f729c0e0":{"description":"Authentication required","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"e17a02df-73d9-4b39-89f1-9bfdeb1b1bd4":{"description":"Insufficient permissions","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"594cad6a-e0ef-4387-9ada-e840fe4c7336":{"description":"Space not found","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}}},"security":{"c7c83795-2758-4207-b371-e5b1dceae23c":{"ApiKey":{"type":"apiKey","in":"header","name":"Oai-Api-Key","scopes":[]}}},"servers":{"27616fde-a7f5-4ae5-a362-1fb86892a734":{"url":"https://api.orchata.ai","description":"Orchata API Server"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"Oai-Api-Key","scopes":[]},"schema":{"title":"Oai-Api-Key","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKey","name":"Oai-Api-Key"}],"title":"ApiKey"}]},"originalFileLocation":"api/openapi.json"},"subdomain":"orchatalabs","siteName":"Orchata","title":"Upsert Document - Orchata","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-02-10T14:43:26.086Z","originalFileLocation":"api-reference/documents/upsert-document.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Orchata\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Upsert Document - Orchata\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Orchata\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://orchata.ai/docs/api-reference/documents/upsert-document\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://orchatalabs.mintlify.site/docs/_mintlify/api/og/v2?division=Documents\u0026amp;title=Upsert+Document\u0026amp;description=Create+or+update+a+document+by+filename.+If+a+document+with+the+given+filename+exists+in+the+space%2C+updates+it.+Otherwise+creates+a+new+document.+Embeddings+are\u0026amp;theme=733c0f40f2f162a3cf9276b1\u0026amp;signature=95a66d682c1aace544f8b5b9aedf141fa88ba84fae5c705ea88beac8e9ced3fd\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Upsert Document - Orchata\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://orchatalabs.mintlify.site/docs/_mintlify/api/og/v2?division=Documents\u0026amp;title=Upsert+Document\u0026amp;description=Create+or+update+a+document+by+filename.+If+a+document+with+the+given+filename+exists+in+the+space%2C+updates+it.+Otherwise+creates+a+new+document.+Embeddings+are\u0026amp;theme=733c0f40f2f162a3cf9276b1\u0026amp;signature=95a66d682c1aace544f8b5b9aedf141fa88ba84fae5c705ea88beac8e9ced3fd\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/orchatalabs/UANI6yfg0lJWC1cq/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Orchata\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FA8565\">\u003clink data-mint-head rel=\"canonical\" href=\"https://orchata.ai/docs/api-reference/documents/upsert-document\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/api-reference/documents/upsert-document.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://orchata.ai/#organization\",\"name\":\"Orchata\",\"url\":\"https://orchata.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://cdn.orchata.ai/img/orchata-logo-light.svg\"}},{\"@type\":\"WebSite\",\"@id\":\"https://orchata.ai/docs#website\",\"name\":\"Orchata\",\"url\":\"https://orchata.ai/docs\",\"publisher\":{\"@id\":\"https://orchata.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://orchata.ai/docs/api-reference/documents/upsert-document#webpage\",\"url\":\"https://orchata.ai/docs/api-reference/documents/upsert-document\",\"name\":\"Upsert Document\",\"description\":\"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\",\"dateModified\":\"2026-02-10T14:43:26.086Z\",\"isPartOf\":{\"@id\":\"https://orchata.ai/docs#website\"},\"breadcrumb\":{\"@id\":\"https://orchata.ai/docs/api-reference/documents/upsert-document#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://orchata.ai/docs/api-reference/documents/upsert-document#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://orchata.ai/docs/api-reference/admin/get-platform-analytics\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documents\",\"item\":\"https://orchata.ai/docs/api-reference/documents/list-documents\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Upsert Document\",\"item\":\"https://orchata.ai/docs/api-reference/documents/upsert-document\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://orchata.ai/docs/api-reference/documents/upsert-document#apireference\",\"headline\":\"Upsert Document\",\"name\":\"Upsert Document\",\"description\":\"Create or update a document by filename. If a document with the given filename exists in the space, updates it. Otherwise creates a new document. Embeddings are generated synchronously - the document is immediately queryable.\",\"url\":\"https://orchata.ai/docs/api-reference/documents/upsert-document\",\"mainEntityOfPage\":{\"@id\":\"https://orchata.ai/docs/api-reference/documents/upsert-document#webpage\"},\"dateModified\":\"2026-02-10T14:43:26.086Z\",\"publisher\":{\"@id\":\"https://orchata.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://orchata.ai/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Orchata\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Orchata\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/api-reference/documents/upsert-document.md","siteName":"Orchata","nav":{"global":{"anchors":[{"anchor":"Back to Site","icon":"home","href":"https://orchata.ai"}]},"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API Reference","groups":[{"group":"API Documentation","pages":[{"title":"API Reference","href":"/api-reference/introduction","hidden":false}]},{"group":"Endpoints","pages":[{"group":"Admin","pages":[{"title":"Get Platform Analytics","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/admin/analytics","href":"/api-reference/admin/get-platform-analytics"},{"title":"Get Documents Over Time","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/admin/analytics/documents","href":"/api-reference/admin/get-documents-over-time"},{"title":"Get Users Over Time","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/admin/analytics/users","href":"/api-reference/admin/get-users-over-time"}]},{"group":"Spaces","pages":[{"title":"List Spaces","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/spaces","href":"/api-reference/spaces/list-spaces"},{"title":"Create Space","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/spaces","href":"/api-reference/spaces/create-space"},{"title":"Get Space","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/spaces/{id}","href":"/api-reference/spaces/get-space"},{"title":"Delete Space","deprecated":null,"version":null,"openapi":"api/openapi.json delete /api/spaces/{id}","href":"/api-reference/spaces/delete-space"},{"title":"Update Space","deprecated":null,"version":null,"openapi":"api/openapi.json patch /api/spaces/{id}","href":"/api-reference/spaces/update-space"},{"title":"Get Space Limits","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/spaces/{id}/limits","href":"/api-reference/spaces/get-space-limits"}]},{"group":"Documents","pages":[{"title":"List Documents","description":"Retrieve a paginated list of documents in a space with optional status filtering","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/documents","href":"/api-reference/documents/list-documents"},{"title":"Upsert Document","deprecated":null,"version":null,"openapi":"api/openapi.json put /api/documents","href":"/api-reference/documents/upsert-document"},{"title":"Upload Document","description":"Upload a new document to a space. Supports both file uploads (multipart/form-data) and raw markdown/text content (application/json).","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/documents","href":"/api-reference/documents/upload-document"},{"title":"Batch Upload Documents","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/documents/batch","href":"/api-reference/documents/batch-upload-documents"},{"title":"Get Document by Filename","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/documents/by-filename","href":"/api-reference/documents/get-document-by-filename"},{"title":"Get Document","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/documents/{id}","href":"/api-reference/documents/get-document"},{"title":"Delete Document","deprecated":null,"version":null,"openapi":"api/openapi.json delete /api/documents/{id}","href":"/api-reference/documents/delete-document"},{"title":"Update Document","deprecated":null,"version":null,"openapi":"api/openapi.json patch /api/documents/{id}","href":"/api-reference/documents/update-document"},{"title":"Get Processed Document Content","deprecated":null,"version":null,"openapi":"api/openapi.json get /api/documents/{id}/content","href":"/api-reference/documents/get-processed-document-content"},{"title":"Append to Document","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/documents/{id}/append","href":"/api-reference/documents/append-to-document"}]},{"group":"Queries","pages":[{"title":"Query Spaces","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/query","href":"/api-reference/queries/query-spaces"},{"title":"Smart Query - Discover Relevant Spaces","deprecated":null,"version":null,"openapi":"api/openapi.json post /api/query/smart","href":"/api-reference/queries/smart-query--discover-relevant-spaces"}]}]}]}]},"basePath":"","title":"Upsert Document - Orchata","buildId":"dpl_6PxPD4Fj1JDU9BJxEHvfdUmxKThw","deploymentId":"dpl_6PxPD4Fj1JDU9BJxEHvfdUmxKThw","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CASS2Vpq.js","utils-4k9fyWRu.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-UU-UueZb.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-BgJ0LOYq.js","snippetPresets-CMgzlMR-.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BzEJegkK.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CZuQIZdk.js","shallow-Bw5arfMA.js","getApiPlaygroundDisplay-Ds834aVN.js","CodeSnippet-CKzmjw9L.js","CodeSnippets-BRpgomdp.js","Page-DvEUoD2H.js","getPastedJson-B0N-Tn76.js","icon-DASMs9nC.js","MethodPill-BA6DBLqx.js","DuplicateIcon-BMT5qfbJ.js","createIcon-CNfwVWPx.js","DynamicMarkdown-JYyBNlrJ.js","SectionHeading-BbZnmz8a.js","axios-vUo_bRtp.js","Markdown-LUU0YLpA.js","clsx-Di4ek5Ae.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-VEVWQCR4.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CPszyu99.js"]}