VocalDocscontracts 1.65.0

Add a query to the retrieval-quality corpus

POST /v1/knowledge-bases/{knowledge_base_id}/eval-queries

PropertyValue
Operationcreate_knowledge_eval_query
GroupKnowledge bases
Scopeknowledge:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited knowledge.eval_query.create (mutation)
Released in1.53.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Adds a labelled question with the Documents that answer it, or expect_empty, at revision 1 (1.53.0). Every issue is a detail of 422 validation_failed (KnowledgeEvalQueryIssueCode). The answer carries query null, as every write does.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the knowledge:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/knowledge-bases/kb_.../eval-queries" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "query": "<query>" }'

Parameters

NameInTypeRequiredDescription
knowledge_base_idpathKnowledgeBaseIdyesThe id of a Knowledge base: kb_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: KnowledgeEvalQueryCreateRequest.

FieldTypeRequiredDescription
expect_emptybooleannoFalse when omitted.
filterKnowledgeFilterInputno
querystringyes
relevant_documentsarray of KnowledgeDocumentIdnoNone when omitted.
tagsarray of KnowledgeEvalQueryTagnosnake_case labels that group the queries, such as lab_visits.

Responses

StatusContent typeShapeError codes
201application/jsonKnowledgeEvalQuery
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeknowledge_base_archived, idempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is KnowledgeEvalQuery.

FieldTypeRequiredDescription
created_atTimestampyes
expect_emptybooleanyesTrue when no passage should score at or above min_score for the query.
filterKnowledgeFilter or nullyesThe filter the query is run under, as a binding would fix it; null for none.
idKnowledgeEvalQueryIdyes
knowledge_base_idKnowledgeBaseIdyes
object"knowledge_eval_query"yes
querystring or nullyesThe question as a caller would ask it: the content class text, null unless the read names include=text, and null in the answer of a write.
relevant_documentsarray of KnowledgeDocumentIdyesThe Documents that answer the query; empty when expect_empty.
revisionintegeryesCounts writes; returned as the ETag and required in If-Match.
tagsarray of KnowledgeEvalQueryTagyessnake_case labels that group the queries, such as lab_visits.
updated_atTimestampyes