Knowledge bases

The documents an agent can look things up in, mid-call.

A knowledge base is a set of documents an agent can search while it is talking to someone. Uploading does not make a document searchable straight away. It is chunked, embedded and indexed in the background, which is why every document carries a status. Poll until it reads Indexed.

The search endpoint asks exactly the question an agent asks mid-call and returns the same passages, which is how you check what an agent would have found before you put it on the phone.

List knowledge bases#

Knowledge bases the key can reach, newest first.

GET/api/v1/knowledge-bases

Query parameters

searchstring: Match name or description.

Responses

The knowledge bases.

Request

curl -X GET "https://voice.evryhealth.com/api/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "knowledgeBases": [
      {
        "id": "3c90…",
        "name": "Plan documents 2026",
        "description": "Summary of benefits, formulary, prior-auth rules.",
        "documentCount": 41,
        "isOrgShared": true
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Create a knowledge base#

An empty knowledge base. `chunking` controls how documents are split before they are embedded; leave it out unless you have a reason.

POST/api/v1/knowledge-bases

Body

application/json

name: string; required
description: string
chunking: { size: number, overlap: number }

Responses

The created knowledge base.

Request

curl -X POST "https://voice.evryhealth.com/api/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan documents 2026",
    "description": "Summary of benefits and formulary."
  }'

Response201

{
  "data": {
    "id": "3c90…",
    "name": "Plan documents 2026",
    "documentCount": 0
  },
  "meta": {
    "requestId": "req_…"
  }
}

Get a knowledge base#

One knowledge base, with how many documents it holds.

GET/api/v1/knowledge-bases/{knowledgeBaseId}

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.

Responses

The knowledge base.

Request

curl -X GET "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "id": "3c90…",
    "name": "Plan documents 2026",
    "documentCount": 41
  },
  "meta": {
    "requestId": "req_…"
  }
}

Update a knowledge base#

Rename it, change its description, or share it across the organization.

PATCH/api/v1/knowledge-bases/{knowledgeBaseId}

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.

Body

application/json

name: string
description: string
isOrgShared: boolean

Responses

The updated knowledge base.

Request

curl -X PATCH "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isOrgShared": true
  }'

Response200

{
  "data": {
    "id": "3c90…",
    "isOrgShared": true
  },
  "meta": {
    "requestId": "req_…"
  }
}

Delete a knowledge base#

Removes the documents, the stored files and the search index entries. A deleted knowledge base stops being searchable, not just listed.

DELETE/api/v1/knowledge-bases/{knowledgeBaseId}

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.

Responses

Deleted.

Request

curl -X DELETE "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_…"
  }
}

List documents#

Documents and their indexing status. Only an `Indexed` document is searchable; this is the endpoint to poll after an upload.

GET/api/v1/knowledge-bases/{knowledgeBaseId}/documents

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.

Query parameters

searchstring: Match the file name, file type or uploader's name.
statusstring: Processing, Indexed or Failed.

Responses

The documents.

Request

curl -X GET "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "documents": [
      {
        "id": "88fa…",
        "fileName": "formulary-2026.pdf",
        "fileType": "application/pdf",
        "fileSizeBytes": 2481923,
        "status": "Indexed",
        "processingError": null
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Upload documents#

`multipart/form-data` with one or more `files` parts. Returns what was stored and what was refused, because failing the whole request over one oversized file would lose the rest. A stored document is not searchable until it has been indexed.

POST/api/v1/knowledge-bases/{knowledgeBaseId}/documents

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.

Body

multipart/form-data

files: file[]; required

Responses

What was stored, and what was not.

Request

curl -X POST "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -d '{
    "files": [
      "formulary-2026.pdf"
    ]
  }'

Response201

{
  "data": {
    "documents": [
      {
        "id": "88fa…",
        "fileName": "formulary-2026.pdf",
        "status": "Processing"
      }
    ],
    "rejected": [
      {
        "fileName": "recording.mov",
        "reason": "File type is not supported"
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Delete a document#

Removes the file, its chunks in the index, and the row.

DELETE/api/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}

Path parameters

knowledgeBaseIdstringrequired: Knowledge base id.
documentIdstringrequired: Document id.

Responses

Deleted.

Request

curl -X DELETE "https://voice.evryhealth.com/api/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_…"
  }
}

Search#

Ask what an agent asks. A POST rather than a GET because the question is natural language, may be long, and may carry PHI, and a question in a URL ends up in access logs. Ids the key cannot reach are dropped rather than refused, so searching everything works without knowing what everything is.

POST/api/v1/knowledge-bases/search

Body

application/json

query: string; required
knowledgeBaseIds: string[]
topK: number

Responses

Passages, best first.

Request

curl -X POST "https://voice.evryhealth.com/api/v1/knowledge-bases/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Is a prior authorization needed for a 90-day supply?",
    "topK": 3
  }'

Response200

{
  "data": {
    "searched": [
      "3c90…"
    ],
    "results": [
      {
        "knowledgeBaseId": "3c90…",
        "fileName": "formulary-2026.pdf",
        "content": "A 90-day supply of a tier 2 drug requires prior authorization when…",
        "score": 0.83,
        "pageNumber": 14,
        "highlights": [
          "prior authorization"
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}