Answer questions from your documents

Create the documents#

POST /documents takes either a JSON body with the text inline, or a multipart/form-data file upload. Create one document per topic.

curl -X POST https://core-api.heysadie.ai/documents \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Opening hours",
    "filename": "opening-hours.txt",
    "content": "Riverside Bistro is open midday to 10pm, Tuesday to Sunday. We are closed on Mondays and on public holidays. The kitchen stops taking orders at 9:15pm."
  }'

curl -X POST https://core-api.heysadie.ai/documents \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "name=Cancellation policy" \
  -F "[email protected]"

The response is the document record:

{
  "success": true,
  "data": {
    "id": "0195f1e2-0000-0000-0000-000000000000",
    "name": "Opening hours",
    "sizeBytes": 172,
    "createdAt": "2026-08-17T09:12:04.000Z",
    "updatedAt": "2026-08-17T09:12:04.000Z",
    "usedByCount": 0,
    "usedByAssistantIds": []
  },
  "metadata": {
    "timestamp": "2026-08-17T09:12:04.000Z",
    "version": "1.0",
    "path": "/documents"
  }
}

Keep data.id for each document. usedByCount is 0 and usedByAssistantIds is empty because the document exists but nothing uses it yet; that is what the next step fixes.

Write the content the way you would answer the question out loud. Short declarative sentences, one fact each, no tables or column layouts: the assistant reads this text and speaks from it, so anything that only makes sense visually is wasted.

Attach them to the assistant#

Attaching takes a single field, because the attachment carries no content: the document exists, the assistant exists, and this creates the link between them. Repeat it once per document.

curl -X POST https://core-api.heysadie.ai/assistants/ASSISTANT_ID/documents \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documentId": "0195f1e2-0000-0000-0000-000000000000" }'

Then read the attachments back, rather than assuming what you just created:

curl https://core-api.heysadie.ai/assistants/ASSISTANT_ID/documents \
  -H "Authorization: ApiKey YOUR_API_KEY"

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "0195f1e2-0000-0000-0000-000000000000",
        "name": "Opening hours",
        "sizeBytes": 172,
        "attachedAt": "2026-08-17T09:31:47.000Z",
        "enabled": true
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-08-17T09:40:02.000Z",
    "version": "1.0",
    "path": "/assistants/ASSISTANT_ID/documents"
  }
}

enabled is the field to check: a disabled attachment is simply not used on that assistant's calls, and it is the reversible way to take a seasonal menu or an expired promotion out of service without detaching anything.

Tell the assistant to answer from them#

Attached documents turn lookup on. Without the Knowledge Base tool on the assistant, that is the original lookup. Link the tool to narrow when it runs. Control when the assistant looks up covers the per-assistant sentence and the tenant-wide default.

The prompt still decides what to do with the answer, and what to do when the answer is not there. That second half is what stops an assistant inventing a price.

curl -X POST https://core-api.heysadie.ai/prompts \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bistro front desk",
    "type": "voice",
    "prompt": "You answer the phone for Riverside Bistro. Be warm and brief. Answer questions about hours, prices, and our policies from the documents attached to you, and quote them exactly rather than paraphrasing a number or a date. If the answer is not in your documents, say you will check and offer to take a message or put the caller through. Never guess, and never state a price, a date, or a policy you cannot find."
  }'

type: "voice" is the default and is the type that fills the assistant's promptId slot. The response carries the prompt's id, name, type and timestamps.

Now point the assistant at it:

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "promptId": "PROMPT_ID" }'

Ask it something only the documents know#

Dial the assistant's number and ask a question whose answer appears nowhere except your document: "how late does the kitchen take orders?" rather than "are you open on Sundays?", because the second is guessable and the first is not. A correct, specific answer is the whole test. Then hang up.

Read the transcript back:

curl "https://core-api.heysadie.ai/calls?assistantId=ASSISTANT_ID&limit=1" \
  -H "Authorization: ApiKey YOUR_API_KEY"

data.calls[0].transcript is the conversation as text, and summary is the platform's summary of it. Both are produced after the call ends, so if they are still null, wait a moment and run the request again. GET /calls/{id} returns the same call with its full payload, including messages turn by turn. See Calls.

Read the assistant's answer against your document, word for word. If the wording came from your text, the knowledge base is working. If the assistant hedged or improvised, check these in order:

• Is the attachment enabled? GET /assistants/{id}/documents from step 2 answers it.
• Does the document actually contain the answer? GET /documents/{id}/content returns the stored text; a truncated or reformatted upload is a common surprise.
• Do the instructions tell it to look? A prompt that never mentions the documents leaves the model to decide, and it will sometimes decide not to. If it looks the knowledge base up for questions you already handle with another tool, set when-to-call text. See Control when the assistant looks up.
• Was the question answerable at all? If the fact is genuinely absent, an assistant that offers to take a message is behaving exactly as instructed. Pair the knowledge base with a transfer reason so those callers reach a person.

More checks, including prompt and tool behaviour, are in Calls and assistant behavior.