> ## Documentation Index
> Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert Document

> 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.



## OpenAPI

````yaml api/openapi.json put /api/documents
openapi: 3.1.0
info:
  version: '0.1'
  title: Orchata API
servers:
  - url: https://api.orchata.ai
    description: Orchata API Server
security:
  - ApiKey: []
paths:
  /api/documents:
    put:
      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.
      requestBody:
        description: Upsert document request
        content:
          application/json:
            schema:
              type: object
              properties:
                spaceId:
                  type: string
                  description: The ID of the space
                  example: space_123
                filename:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Filename to create or update
                  example: my-notes.md
                content:
                  type: string
                  minLength: 1
                  maxLength: 10000000
                  description: The document content (max 10MB)
                  example: |-
                    # My Notes

                    Some content...
                metadata:
                  type: object
                  additionalProperties: {}
                  description: Optional metadata to attach to the document
              required:
                - spaceId
                - filename
                - content
      responses:
        '200':
          description: Document created or updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    type: object
                    properties:
                      id:
                        type: string
                      orgId:
                        type: string
                      spaceId:
                        type: string
                      filename:
                        type: string
                      mimeType:
                        type: string
                      fileSize:
                        type: string
                      storageUrl:
                        type: string
                      status:
                        type: string
                      errorMessage:
                        type:
                          - string
                          - 'null'
                      embeddingModel:
                        type: string
                      indexingType:
                        type: string
                      metadata: {}
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                    required:
                      - id
                      - orgId
                      - spaceId
                      - filename
                      - mimeType
                      - fileSize
                      - storageUrl
                      - status
                      - errorMessage
                      - embeddingModel
                      - indexingType
                      - createdAt
                      - updatedAt
                  created:
                    type: boolean
                    description: >-
                      Whether a new document was created (true) or existing
                      updated (false)
                required:
                  - document
                  - created
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
        '404':
          description: Space not found
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: >-
            import { Orchata } from '@orchata-ai/sdk';


            const client = new Orchata({ apiKey: 'oai_your_api_key' });


            // Create or update - idempotent operation

            const { 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');
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Oai-Api-Key

````