Documents

Creating a document is a two-step flow: create an empty document, then generate its content.

Create a Document

Method: POST

Path: /sessions/{session_id}/documents

Description: Create an empty document for the session. This does not generate the letter body — call Generate document content next.

Request

POST /sessions/1234567890/documents
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "document_tab_type": "DOCUMENT",
  "generation_method": "TEMPLATE",
  "template_id": "66455a5f0b0a1c8d018c6896",
  "voice_style": "GOLDILOCKS",
  "brain": "LEFT",
  "content_type": "MARKDOWN"
}

Request Fields:

• document_tab_type (string, optional): Document tab. Defaults to DOCUMENT.
• generation_method (string, required): How the document will be generated. Typical partner value is TEMPLATE.
• template_id (string, optional): The ID of the template to use. Required when generation_method is TEMPLATE.
• voice_style (string, optional): One of GOLDILOCKS, DETAILED, BRIEF, SUPER_DETAILED, MY_VOICE.
• brain (string, optional): LEFT or RIGHT. If omitted, Heidi uses the linked user's saved preference.
• content_type (string, optional): MARKDOWN or HTML.

Response

{
  "id": "string",
  "session_id": "string",
  "name": "string",
  "template_id": "string",
  "brain": "string",
  "voice_style": "string",
  "content_type": "string",
  "content": "string"
}

Get List of Documents

Method: GET

Path: /sessions/{session_id}/documents

Description: Retrieve a list of all documents associated with a specific session.

Request

GET /sessions/1234567890/documents
Authorization: Bearer <your_token>

Response

{
  "documents": [
    {
      "id": "string",
      "session_id": "string",
      "index": 0,
      "name": "string",
      "template_id": "string",
      "content": "string",
      "generation_type": "TEMPLATE",
      "brain": "LEFT"
    }
  ]
}

Get a document

Method: GET

Path: /sessions/{session_id}/documents/{document_id}

Description: Retrieve a single document.

Request

GET /sessions/1234567890/documents/66455a5f0b0a1c8d018c6896
Authorization: Bearer <your_token>

Response

{
  "id": "66455a5f0b0a1c8d018c6896",
  "session_id": "1234567890",
  "name": "Referral letter",
  "template_id": "66455a5f0b0a1c8d018c6896",
  "content": "Document text...",
  "generation_type": "TEMPLATE",
  "brain": "LEFT",
  "voice_style": "GOLDILOCKS",
  "content_type": "MARKDOWN"
}

Generate document content

Method: POST

Path: /sessions/{session_id}/documents/{document_id}/content

Description: Generates (or regenerates) the document body. This is a stream, same shape as consult-note generation. If the request body is omitted, Heidi uses the generation details stored on the document at create time.

Request

POST /sessions/1234567890/documents/66455a5f0b0a1c8d018c6896/content
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "generation_method": "TEMPLATE",
  "template_id": "66455a5f0b0a1c8d018c6896",
  "voice_style": "GOLDILOCKS",
  "content_type": "MARKDOWN"
}

Response

{ "data": "Document text..." }

Update a document

Method: PATCH

Path: /sessions/{session_id}/documents/{document_id}

Description: Update document fields such as name or content.

Request

PATCH /sessions/1234567890/documents/66455a5f0b0a1c8d018c6896
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "name": "Referral letter",
  "content": "Updated document text..."
}

Request Fields:

• name (string, optional): Document display name.
• content (string, optional): Document body.
• generation_type (string, optional): Stored document generation type (TEMPLATE, DICTATION, ASK_AI, and similar). This is not generation_method — create and generate-content use generation_method.

Delete a document

Method: DELETE

Path: /sessions/{session_id}/documents/{document_id}

Request

DELETE /sessions/1234567890/documents/66455a5f0b0a1c8d018c6896
Authorization: Bearer <your_token>

Response

{
  "is_success": true
}