API reference · Knowledge

Search documents

POSThttps://goblins-call-api.onrender.com/v1/knowledge/search

Returns what an agent with these documents would be handed for a question, best match first.

Needs a workspace API key.

Body

documentIdsstring[]Requiredup to 500

The documents to search. Only documents of your workspace that are ready are searched.

querystringRequired1–300 chars

The question, as a caller would ask it.

Response

hits[].kindenum

card for a question and answer taken from a document, section for a passage of its text.

hits[].similaritynumber

How close the match is in meaning, from 0 to 1.

Errors

400

The body failed validation. details lists each field and what is wrong with it.

Every request can also answer 401, 429 and 500: see Errors.

Notes

  • An empty hits means the agent would tell the caller it does not have that information.
  • The figures in the sample are placeholders.
curl -X POST "https://goblins-call-api.onrender.com/v1/knowledge/search" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documentIds": [
    "kd_4b1f0c9d2e7a6f53"
  ],
  "query": "How long does a refund take?"
}'
Response · 200 OK
{
  "hits": [
    {
      "kind": "card",
      "question": "How long does a refund take?",
      "text": "A refund for a cancelled order is paid within seven working days to the card that was used.",
      "documentId": "kd_4b1f0c9d2e7a6f53",
      "document": "Refund policy",
      "similarity": 0.71
    }
  ],
  "ms": 180
}