Skip to content
engage-ai

API reference

Knowledge

FAQs, policies and documents, plus retrieval inspection

For concepts and a walkthrough, read Knowledge base.

List knowledge documents

GET/knowledge/documents
Auth
Session token or API key

Query parameters

  • cursorstring
  • limitinteger

    Max 100

Response fields 200
  • itemsKnowledgeDocument[]required
  • nextCursorstring | nullrequired

    Opaque. Pass back verbatim as cursor. Null means the end.

  • hasMorebooleanrequired

KnowledgeDocument

  • idstring (uuid)required
  • organizationIdstring (uuid)required
  • sourceTypestringrequired
  • titlestringrequired
  • contentstringrequired
  • contentHashstringrequired

    Unchanged content is not re-embedded.

  • localestringrequired
  • statusenumrequired

    PENDING is normal immediately after a write; indexing is asynchronous.

    One of PENDING, INDEXING, INDEXED, FAILED, STALE

  • priorityintegerrequired

    Min -9007199254740991

  • channelScopestring[]required
  • indexedAtstring (date-time) | nullrequired

Responses

  • 200A page of documents.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl "https://api.getengageai.app/knowledge/documents" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "items": [
    {
      "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "organizationId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "sourceType": "string",
      "title": "Returns policy",
      "content": "Unworn items can be returned within 30 days of delivery for a full refund.",
      "contentHash": "string",
      "locale": "en-GB",
      "status": "PENDING",
      "priority": 0,
      "channelScope": [
        "string"
      ],
      "indexedAt": "2026-10-16T09:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Create or update a knowledge document

POST/knowledge/documents

Returns immediately with status PENDING; chunking and embedding happen on a queue, because a dashboard save should not wait seconds for an embedding call. The document is findable by lexical search in the meantime.

Auth
Session token or API key
Body
application/json

Request body

  • sourceTypeenum

    Products use PRODUCT and are written through /products instead.

    One of FAQ, POLICY, DOCUMENT, WEBPAGE, MANUAL · Default "MANUAL"

  • sourceRefstring

    Your stable identifier for this document. Supplying it makes repeat writes an upsert rather than a duplicate — use it for anything synced from another system.

    Max 512 characters

  • titlestringrequired

    Max 512 characters

  • contentstringrequired

    Plain text. Chunked on semantic boundaries and embedded automatically.

    Max 200000 characters

  • localestring

    Max 16 characters

  • priorityinteger

    Breaks retrieval ties. How a business pins official policy above an older FAQ.

    Min -100 · Max 100

  • channelScopestring[]

    Provider keys this applies to. Empty or omitted means every channel.

  • tagsstring[]
Response fields 201
  • idstring (uuid)required
  • organizationIdstring (uuid)required
  • sourceTypestringrequired
  • titlestringrequired
  • contentstringrequired
  • contentHashstringrequired

    Unchanged content is not re-embedded.

  • localestringrequired
  • statusenumrequired

    PENDING is normal immediately after a write; indexing is asynchronous.

    One of PENDING, INDEXING, INDEXED, FAILED, STALE

  • priorityintegerrequired

    Min -9007199254740991

  • channelScopestring[]required
  • indexedAtstring (date-time) | nullrequired

KnowledgeDocument

  • idstring (uuid)required
  • organizationIdstring (uuid)required
  • sourceTypestringrequired
  • titlestringrequired
  • contentstringrequired
  • contentHashstringrequired

    Unchanged content is not re-embedded.

  • localestringrequired
  • statusenumrequired

    PENDING is normal immediately after a write; indexing is asynchronous.

    One of PENDING, INDEXING, INDEXED, FAILED, STALE

  • priorityintegerrequired

    Min -9007199254740991

  • channelScopestring[]required
  • indexedAtstring (date-time) | nullrequired

Responses

  • 201The stored document.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X POST "https://api.getengageai.app/knowledge/documents" \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "POLICY",
    "title": "Returns policy",
    "content": "Unworn items can be returned within 30 days of delivery for a full refund. Worn footwear cannot be returned unless faulty.",
    "locale": "en-GB"
  }'
Response · 201
{
  "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "organizationId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "sourceType": "string",
  "title": "Returns policy",
  "content": "Unworn items can be returned within 30 days of delivery for a full refund.",
  "contentHash": "string",
  "locale": "en-GB",
  "status": "PENDING",
  "priority": 0,
  "channelScope": [
    "string"
  ],
  "indexedAt": "2026-10-16T09:30:00.000Z"
}

Delete a knowledge document

DELETE/knowledge/documents/{id}
Auth
Session token or API key

Path parameters

  • idstring (uuid)required
Response fields 200
  • deletedtruerequired

Responses

  • 200Deleted.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X DELETE "https://api.getengageai.app/knowledge/documents/$ID" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "deleted": true
}

Preview the context a question would retrieve

POST/knowledge/preview

Runs the exact retrieval the reply engine runs, without generating anything. Use it to answer "why did it say that?" before it has said anything, and to check whether a gap is missing knowledge or a retrieval problem.

Auth
Session token or API key
Body
application/json

Request body

  • querystringrequired

    A customer question, as they would phrase it.

    Max 2000 characters

  • topKinteger

    Default 8 · Max 20

Response fields 200
  • querystringrequired
  • resultsobject[]required
  • results[].chunkIdstring (uuid)required
  • results[].documentIdstring (uuid)required
  • results[].titlestringrequired
  • results[].relevancenumberrequired

    Raw similarity, 0-1. This is the number to read when judging a match.

  • results[].ranknumberrequired

    Fused reciprocal-rank score that decided the ordering. Scale-free and tiny by construction — useful for sorting, not for judging relevance.

  • results[].sourceenumrequired

    Which strategy found it. HYBRID means both did.

    One of SEMANTIC, LEXICAL, HYBRID, PINNED

  • results[].excerptstringrequired

RetrievalPreview

  • querystringrequired
  • resultsobject[]required
  • results[].chunkIdstring (uuid)required
  • results[].documentIdstring (uuid)required
  • results[].titlestringrequired
  • results[].relevancenumberrequired

    Raw similarity, 0-1. This is the number to read when judging a match.

  • results[].ranknumberrequired

    Fused reciprocal-rank score that decided the ordering. Scale-free and tiny by construction — useful for sorting, not for judging relevance.

  • results[].sourceenumrequired

    Which strategy found it. HYBRID means both did.

    One of SEMANTIC, LEXICAL, HYBRID, PINNED

  • results[].excerptstringrequired

Responses

  • 200What the model would be given, in order.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X POST "https://api.getengageai.app/knowledge/preview" \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "can I return boots I have worn?",
    "topK": 5
  }'
Response · 200
{
  "query": "waterproof boots",
  "results": [
    {
      "chunkId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "documentId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "title": "Returns policy",
      "relevance": 0.5,
      "rank": 0.5,
      "source": "SEMANTIC",
      "excerpt": "string"
    }
  ]
}