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

# Upload Document

> Upload a new document to a space. Supports both file uploads (multipart/form-data) and raw markdown/text content (application/json).



## OpenAPI

````yaml api/openapi.json post /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:
    post:
      tags:
        - Documents
      summary: Upload Document
      description: >-
        Upload a new document to a space. Supports both file uploads
        (multipart/form-data) and raw markdown/text content (application/json).
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                spaceId:
                  type: string
                  description: The ID of the space to upload the document to
                  example: space_123
                filename:
                  type: string
                  minLength: 1
                  maxLength: 255
                embeddingModel:
                  type: string
                metadata:
                  type: string
              required:
                - spaceId
          application/json:
            schema:
              type: object
              properties:
                spaceId:
                  type: string
                  description: The ID of the space to upload the document to
                  example: space_123
                content:
                  type: string
                  minLength: 1
                  description: The raw markdown or text content to upload
                  example: |-
                    # My Document

                    Some markdown content...
                filename:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: >-
                    Optional filename for the document (defaults to
                    'document.md')
                  example: my-document.md
                embeddingModel:
                  type: string
                  description: The embedding model to use for this document
                metadata:
                  type: object
                  additionalProperties: {}
                  description: Optional metadata to attach to the document
              required:
                - spaceId
                - content
      responses:
        '201':
          description: Document uploaded 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
                required:
                  - document
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
        '404':
          description: Space not found
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK (Content)
          source: |-
            import { Orchata } from '@orchata-ai/sdk';

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

            // Upload raw content
            const { document } = await client.documents.upload({
              spaceId: 'space_123',
              content: '# My Document\n\nSome markdown content...',
              filename: 'my-doc.md',
              metadata: { category: 'guides' }
            });
        - lang: typescript
          label: TypeScript SDK (File)
          source: |-
            import { Orchata } from '@orchata-ai/sdk';

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

            // Upload a file (browser)
            const { document } = await client.documents.uploadFile({
              spaceId: 'space_123',
              file: fileInput.files[0]
            });
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Oai-Api-Key

````