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

# Create or Update Document

> Create a new document on a session (omit `document_id` → `201`), or update an existing one (include `document_id` → `200`) — for example to save a doctor's edits to generated notes. Every response includes a presigned **PUT** URL: upload the document content (markdown) to that URL to store it.


Create a document on a session (omit `document_id` → `201`) or update one (include `document_id` → `200`) — e.g. to save a doctor's edits. The response includes a presigned **PUT** URL — upload the markdown content there:

```bash theme={null}
curl -X PUT "<presigned_url>" -H "Content-Type: text/markdown" --data-binary @note.md
```


## OpenAPI

````yaml POST /voice/api/v1/documents
openapi: 3.0.1
info:
  title: EkaScribe Protocol API (MedScribeAlliance v0.1)
  version: '0.1'
  description: >
    Session-based medical voice capture API implementing the MedScribeAlliance
    Protocol v0.1. Discover service capabilities, create a session, stream audio
    chunks, then end the session to trigger asynchronous transcription and
    structured-template extraction.
servers:
  - url: https://api.eka.care
    description: Production server
  - url: https://api.dev.eka.care
    description: Development server
security: []
paths:
  /voice/api/v1/documents:
    post:
      tags:
        - documents
      summary: Create or Update Document
      description: >
        Create a new document on a session (omit `document_id` → `201`), or
        update an existing one (include `document_id` → `200`) — for example to
        save a doctor's edits to generated notes. Every response includes a
        presigned **PUT** URL: upload the document content (markdown) to that
        URL to store it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
            example:
              session_id: ses_abc123def456
              template_id: clinical_notes_template
              type: custom
              document_name: Edited clinical note
              status: success
      responses:
        '201':
          description: Document created (also `200` when updating an existing document)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentEnvelopeResponse'
              example:
                status: success
                data:
                  document_id: doc_9f8e7d6c
                  session_id: ses_abc123def456
                  template_id: clinical_notes_template
                  document_name: Edited clinical note
                  type: markdown
                  document_type: custom
                  status: success
                  errors: []
                  warnings: []
                  usage_information: {}
                  presigned_url: https://s3.amazonaws.com/...&X-Amz-Signature=...
                  created_at: '2026-06-06T14:21:07Z'
                  updated_at: '2026-06-06T14:25:12Z'
                  publish: {}
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - auth: []
components:
  schemas:
    CreateDocumentRequest:
      type: object
      required:
        - session_id
      properties:
        session_id:
          type: string
          description: The session this document belongs to.
          example: ses_abc123def456
        document_id:
          type: string
          description: Omit to create a new document; include to update an existing one.
        template_id:
          type: string
          description: Template the document is associated with, if any.
        type:
          type: string
          enum:
            - context
            - transcript
            - custom
            - notes
            - integration
          default: custom
          description: Document category.
        document_name:
          type: string
          description: Human-readable document name.
        status:
          type: string
          default: in-progress
          description: Document status, e.g. `in-progress` or `success`.
        errors:
          type: array
          items: {}
        warnings:
          type: array
          items: {}
        usage_information:
          type: object
          additionalProperties: true
    DocumentEnvelopeResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/Document'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: invalid_audio_format
            message:
              type: string
              description: Human-readable error message.
              example: Audio format 'audio/mp3' is not supported
            details:
              type: object
              additionalProperties: true
              description: Additional error context.
    Document:
      type: object
      properties:
        document_id:
          type: string
        session_id:
          type: string
        template_id:
          type: string
        document_name:
          type: string
        type:
          type: string
          example: markdown
          description: Content format of the document.
        document_type:
          type: string
          description: Document category (`template`, `custom`, `transcript`, ...).
        status:
          type: string
          example: success
        errors:
          type: array
          items: {}
        warnings:
          type: array
          items: {}
        usage_information:
          type: object
          additionalProperties: true
        presigned_url:
          type: string
          description: >
            Presigned S3 URL. On Create/Update it is a **PUT** URL to upload
            content; on Get it is a **GET** URL to download content.
        created_at:
          type: string
        updated_at:
          type: string
        publish:
          type: object
          additionalProperties: true
          description: >-
            Publish status per integration, when the document has been
            published.
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````