@sanity/client
Version:
Client for retrieving, creating and patching data from Sanity.io
5,346 lines • 214 kB
JSON
{
"openapi": "3.0.3",
"info": {
"title": "Sanity Context API",
"description": "Build knowledge bases from your content — file uploads, website crawls, and Sanity datasets — and read, triage, and steer what they produce.",
"version": "2026-05-26"
},
"components": {
"schemas": {
"EntryDoc": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.entry"]
},
"schemaVersion": {
"type": "number"
},
"revisionId": {
"type": "string"
},
"path": {
"type": "string"
},
"title": {
"type": "string"
},
"tldr": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"excludes": {
"type": "string"
},
"neighbors": {
"type": "array",
"items": {
"type": "string"
}
},
"centrality": {
"type": "string",
"enum": ["core", "standard", "peripheral"]
}
},
"required": ["scope", "excludes", "centrality"]
},
"body": {
"type": "string"
},
"topicHeadings": {
"type": "array",
"items": {
"type": "string"
}
},
"citations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceId": {
"type": "string"
},
"supports": {
"type": "string"
},
"spans": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceLineStart": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sourceLineEnd": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"quote": {
"type": "string"
}
},
"required": ["sourceLineStart", "sourceLineEnd", "quote"]
}
},
"claim": {
"type": "object",
"properties": {
"exact": {
"type": "string"
},
"prefix": {
"type": "string"
},
"suffix": {
"type": "string"
}
},
"required": ["exact"]
},
"groundingState": {
"type": "string",
"enum": ["drifted"]
},
"_key": {
"type": "string"
},
"_type": {
"type": "string",
"enum": ["sanity.context.citation"]
},
"filename": {
"type": "string"
},
"mime": {
"type": "string"
},
"excerpt": {
"type": "string"
}
},
"required": ["sourceId", "_key", "_type", "filename"]
}
},
"status": {
"type": "string",
"enum": ["virtual", "outlined", "filled", "stale", "generation_failed"]
},
"generatedAt": {
"type": "string"
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"revisionId",
"path",
"title",
"status",
"generatedAt"
],
"description": "A `sanity.context.entry` document, one outline node stored in the bound dataset. Not returned by any endpoint; published so GROQ reads against the dataset can be typed. The entries endpoints serve the validated wire view."
},
"InstructionDoc": {
"oneOf": [
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.instruction"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"statement": {
"type": "string",
"minLength": 1
},
"scopeSources": {
"nullable": true,
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"_key": {
"type": "string",
"minLength": 1
},
"sourceId": {
"type": "string",
"minLength": 1
},
"contentHash": {
"type": "string",
"minLength": 1
}
},
"required": ["_key", "sourceId", "contentHash"]
}
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"archivedAt": {
"nullable": true,
"type": "string"
},
"archivedReason": {
"nullable": true,
"type": "string"
},
"origin": {
"type": "string",
"enum": ["conflict"]
},
"sourceIssueId": {
"type": "string",
"minLength": 1
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"statement",
"scopeSources",
"status",
"archivedAt",
"archivedReason",
"origin",
"sourceIssueId"
]
},
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.instruction"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"statement": {
"type": "string",
"minLength": 1
},
"scopeSources": {
"nullable": true,
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"_key": {
"type": "string",
"minLength": 1
},
"sourceId": {
"type": "string",
"minLength": 1
},
"contentHash": {
"type": "string",
"minLength": 1
}
},
"required": ["_key", "sourceId", "contentHash"]
}
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"archivedAt": {
"nullable": true,
"type": "string"
},
"archivedReason": {
"nullable": true,
"type": "string"
},
"origin": {
"type": "string",
"enum": ["human"]
},
"sourceIssueId": {
"type": "string",
"nullable": true,
"enum": [null]
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"statement",
"scopeSources",
"status",
"archivedAt",
"archivedReason",
"origin",
"sourceIssueId"
]
}
],
"description": "A `sanity.context.instruction` document, a standing decision steering every build, stored in the bound dataset. Not returned by any endpoint; published so GROQ reads against the dataset can be typed. Write through the instructions endpoints, never with a raw client."
},
"IssueDoc": {
"oneOf": [
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.issue"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"description": "IssueContent"
},
"fingerprint": {
"type": "string",
"minLength": 1
},
"revisionId": {
"nullable": true,
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": ["open"]
},
"resolution": {
"type": "string",
"nullable": true,
"enum": [null]
},
"resolvedAt": {
"type": "string",
"nullable": true,
"enum": [null]
},
"resolvedBy": {
"type": "string",
"nullable": true,
"enum": [null]
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"content",
"fingerprint",
"revisionId",
"status",
"resolution",
"resolvedAt",
"resolvedBy"
]
},
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.issue"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"description": "IssueContent"
},
"fingerprint": {
"type": "string",
"minLength": 1
},
"revisionId": {
"nullable": true,
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": ["accepted"]
},
"resolvedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"resolvedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": ["user", "robot"]
}
},
"required": ["id", "kind"]
},
"resolution": {
"nullable": true,
"type": "string",
"enum": ["keep_existing", "accept_new", null]
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"content",
"fingerprint",
"revisionId",
"status",
"resolvedAt",
"resolvedBy",
"resolution"
]
},
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"knowledgeBaseId": {
"type": "string",
"minLength": 1
},
"_type": {
"type": "string",
"enum": ["sanity.context.issue"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"description": "IssueContent"
},
"fingerprint": {
"type": "string",
"minLength": 1
},
"revisionId": {
"nullable": true,
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": ["rejected"]
},
"resolvedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"resolvedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": ["user", "robot"]
}
},
"required": ["id", "kind"]
},
"resolution": {
"type": "string",
"nullable": true,
"enum": [null]
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"knowledgeBaseId",
"_type",
"schemaVersion",
"content",
"fingerprint",
"revisionId",
"status",
"resolvedAt",
"resolvedBy",
"resolution"
]
}
],
"description": "A `sanity.context.issue` document, a build finding awaiting triage, stored in the bound dataset. Not returned by any endpoint; published so GROQ reads and trigger filters can be typed. Status transitions flow through the issues endpoints, which own the state machine. One invariant the schema cannot express: only a `conflict` issue ever carries a non-null `resolution`."
},
"ConversationDoc": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_type": {
"type": "string",
"enum": ["sanity.context.conversation"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"organizationId": {
"type": "string",
"minLength": 1
},
"threadId": {
"type": "string",
"minLength": 1
},
"metadata": {
"nullable": true,
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 256
}
}
]
},
"description": "ConversationMetadata"
},
"startedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messagesUpdatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": ["user", "assistant", "system", "tool"]
},
"content": {
"default": null,
"nullable": true,
"type": "string",
"maxLength": 20000
},
"toolName": {
"default": null,
"nullable": true,
"type": "string"
},
"toolType": {
"default": null,
"nullable": true,
"type": "string",
"enum": ["call", "result", null]
}
},
"required": ["role", "content", "toolName", "toolType"],
"description": "ConversationMessage"
}
},
"modelProvider": {
"nullable": true,
"type": "string"
},
"modelId": {
"nullable": true,
"type": "string"
},
"tokenUsage": {
"nullable": true,
"type": "object",
"properties": {
"inputTokens": {
"type": "number"
},
"outputTokens": {
"type": "number"
},
"totalTokens": {
"type": "number"
}
},
"description": "ConversationTokenUsage"
},
"coreMetrics": {
"nullable": true,
"type": "object",
"properties": {
"successScore": {
"type": "number"
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
},
"contentGaps": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "ConversationCoreMetrics"
},
"classifiedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"classificationError": {
"nullable": true,
"type": "string"
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"_type",
"schemaVersion",
"organizationId",
"threadId",
"metadata",
"startedAt",
"messagesUpdatedAt",
"messages",
"modelProvider",
"modelId",
"tokenUsage",
"coreMetrics",
"classifiedAt",
"classificationError"
],
"description": "A `sanity.context.conversation` document, one agent conversation transcript with its classification, stored in the organization store. Not returned by any endpoint raw; published so GROQ reads can be typed. Write through the conversation ingest and classify endpoints, never with a raw client."
},
"McpDoc": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"minLength": 1
},
"_rev": {
"type": "string",
"minLength": 1
},
"_createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"_type": {
"type": "string",
"enum": ["sanity.context.mcp"]
},
"schemaVersion": {
"type": "number",
"enum": [1]
},
"organizationId": {
"type": "string",
"minLength": 1
},
"publicId": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1
},
"sources": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["knowledge-base"]
},
"id": {
"type": "string",
"minLength": 1
}
},
"required": ["type", "id"]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["dataset"]
},
"id": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9][a-z0-9_-]*$"
}
},
"required": ["type", "id"]
}
],
"description": "McpSource"
}
},
"instructions": {
"nullable": true,
"type": "string"
},
"groqFilter": {
"nullable": true,
"type": "string"
}
},
"required": [
"_id",
"_rev",
"_createdAt",
"_updatedAt",
"_type",
"schemaVersion",
"organizationId",
"publicId",
"title",
"name",
"sources",
"instructions",
"groqFilter"
],
"description": "A `sanity.context.mcp` document, an org-owned MCP endpoint configuration stored in the organization store. Not returned by any endpoint raw; published so GROQ reads and trigger filters can be typed. Write through the mcp endpoints, never with a raw client. The mcp endpoints serve the validated wire view."
}
}
},
"paths": {
"/{apiVersion}/context/knowledge-bases": {
"get": {
"operationId": "listKnowledgeBases",
"summary": "List knowledge bases",
"tags": ["knowledge-bases"],
"description": "Returns the organization's knowledge bases visible to the caller, cursor-paginated.",
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "cursor",
"required": false
},
{
"schema": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"in": "query",
"name": "limit",
"required": false
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "query",
"name": "organizationId",
"required": true
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "apiVersion",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicId": {
"type": "string"
},
"organizationId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"state": {
"type": "string",
"enum": ["created", "building", "ready", "review", "stale", "paused"]
},
"activeJobId": {
"nullable": true,
"type": "string"
},
"isBuilding": {
"type": "boolean"
},
"buildStageState": {
"nullable": true,
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"tldr",
"map",
"triage",
"plan",
"organize",
"arrange",
"write",
"review",
"polish"
]
},
"status": {
"type": "string",
"enum": ["pending", "running", "done", "failed"]
},
"units": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": ["sources", "groups", "entries", "rounds"]
},
"done": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["unit", "done"],
"additionalProperties": false
}
},
"required": ["id", "status"],
"additionalProperties": false
}
}
},
"required": ["jobId", "stages"],
"additionalProperties": false
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"lastChangedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"hasPendingChanges": {
"type": "boolean"
},
"pendingChanges": {
"nullable": true,
"type": "object",
"properties": {
"added": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"changed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"removed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["added", "changed", "removed"],
"additionalProperties": false
},
"pipelineOutdated": {
"type": "boolean"
},
"rebuildRecommended": {
"nullable": true,
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": ["reason", "at"],
"additionalProperties": false
},
"hasWebSource": {
"type": "boolean"
},
"hasDatasetSource": {
"type": "boolean"
},
"sourceUsage": {
"nullable": true,
"type": "object",
"properties": {
"used": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["used", "limit"],
"additionalProperties": false
},
"refreshEnabled": {
"type": "boolean"
},
"refreshFrequency": {
"type": "string",
"enum": ["weekly", "monthly"]
},
"refreshNextRunAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"refreshInFlight": {
"type": "boolean"
},
"openIssueCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"instructionCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"publicId",
"organizationId",
"title",
"description",
"state",
"activeJobId",
"isBuilding",
"buildStageState",
"lastCheckedAt",
"lastChangedAt",
"hasPendingChanges",
"pendingChanges",
"pipelineOutdated",
"rebuildRecommended",
"hasWebSource",
"hasDatasetSource",
"sourceUsage",
"refreshEnabled",
"refreshFrequency",
"refreshNextRunAt",
"refreshInFlight",
"openIssueCount",
"instructionCount",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "KnowledgeBase"
}
},
"nextCursor": {
"nullable": true,
"type": "string"
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false
}
}
}
}
}
},
"post": {
"operationId": "createKnowledgeBase",
"summary": "Create a knowledge base",
"tags": ["knowledge-bases"],
"description": "Creates a knowledge base bound to a Sanity dataset, where its content documents will be stored.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"organizationId": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": ["organizationId", "title", "description"]
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "apiVersion",
"required": true
}
],
"responses": {
"201": {
"description": "KnowledgeBase",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicId": {
"type": "string"
},
"organizationId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"state": {
"type": "string",
"enum": ["created", "building", "ready", "review", "stale", "paused"]
},
"activeJobId": {
"nullable": true,
"type": "string"
},
"isBuilding": {
"type": "boolean"
},
"buildStageState": {
"nullable": true,
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"tldr",
"map",
"triage",
"plan",
"organize",
"arrange",
"write",
"review",
"polish"
]
},
"status": {
"type": "string",
"enum": ["pending", "running", "done", "failed"]
},
"units": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": ["sources", "groups", "entries", "rounds"]
},
"done": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["unit", "done"],
"additionalProperties": false
}
},
"required": ["id", "status"],
"additionalProperties": false
}
}
},
"required": ["jobId", "stages"],
"additionalProperties": false
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"lastChangedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"hasPendingChanges": {
"type": "boolean"
},
"pendingChanges": {
"nullable": true,
"type": "object",
"properties": {
"added": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"changed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"removed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["added", "changed", "removed"],
"additionalProperties": false
},
"pipelineOutdated": {
"type": "boolean"
},
"rebuildRecommended": {
"nullable": true,
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": ["reason", "at"],
"additionalProperties": false
},
"hasWebSource": {
"type": "boolean"
},
"hasDatasetSource": {
"type": "boolean"
},
"sourceUsage": {
"nullable": true,
"type": "object",
"properties": {
"used": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["used", "limit"],
"additionalProperties": false
},
"refreshEnabled": {
"type": "boolean"
},
"refreshFrequency": {
"type": "string",
"enum": ["weekly", "monthly"]
},
"refreshNextRunAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"refreshInFlight": {
"type": "boolean"
},
"openIssueCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"instructionCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"publicId",
"organizationId",
"title",
"description",
"state",
"activeJobId",
"isBuilding",
"buildStageState",
"lastCheckedAt",
"lastChangedAt",
"hasPendingChanges",
"pendingChanges",
"pipelineOutdated",
"rebuildRecommended",
"hasWebSource",
"hasDatasetSource",
"sourceUsage",
"refreshEnabled",
"refreshFrequency",
"refreshNextRunAt",
"refreshInFlight",
"openIssueCount",
"instructionCount",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "KnowledgeBase"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}": {
"get": {
"operationId": "getKnowledgeBase",
"summary": "Get a knowledge base",
"tags": ["knowledge-bases"],
"description": "Returns the knowledge base object: metadata and state. Resolves from the id alone, the public id (`kb...`) or the uuid; access is decided against the knowledge base's own organization, and an id the caller cannot read returns 404. For the built content, use the outline or entries endpoints.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"200": {
"description": "KnowledgeBase",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicId": {
"type": "string"
},
"organizationId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"state": {
"type": "string",
"enum": ["created", "building", "ready", "review", "stale", "paused"]
},
"activeJobId": {
"nullable": true,
"type": "string"
},
"isBuilding": {
"type": "boolean"
},
"buildStageState": {
"nullable": true,
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"tldr",
"map",
"triage",
"plan",
"organize",
"arrange",
"write",
"review",
"polish"
]
},
"status": {
"type": "string",
"enum": ["pending", "running", "done", "failed"]
},
"units": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": ["sources", "groups", "entries", "rounds"]
},
"done": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["unit", "done"],
"additionalProperties": false
}
},
"required": ["id", "status"],
"additionalProperties": false
}
}
},
"required": ["jobId", "stages"],
"additionalProperties": false
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"lastChangedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"hasPendingChanges": {
"type": "boolean"
},
"pendingChanges": {
"nullable": true,
"type": "object",
"properties": {
"added": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"changed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"removed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["added", "changed", "removed"],
"additionalProperties": false
},
"pipelineOutdated": {
"type": "boolean"
},
"rebuildRecommended": {
"nullable": true,
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": ["reason", "at"],
"additionalProperties": false
},
"hasWebSource": {
"type": "boolean"
},
"hasDatasetSource": {
"type": "boolean"
},
"sourceUsage": {
"nullable": true,
"type": "object",
"properties": {
"used": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["used", "limit"],
"additionalProperties": false
},
"refreshEnabled": {
"type": "boolean"
},
"refreshFrequency": {
"type": "string",
"enum": ["weekly", "monthly"]
},
"refreshNextRunAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"refreshInFlight": {
"type": "boolean"
},
"openIssueCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"instructionCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"publicId",
"organizationId",
"title",
"description",
"state",
"activeJobId",
"isBuilding",
"buildStageState",
"lastCheckedAt",
"lastChangedAt",
"hasPendingChanges",
"pendingChanges",
"pipelineOutdated",
"rebuildRecommended",
"hasWebSource",
"hasDatasetSource",
"sourceUsage",
"refreshEnabled",
"refreshFrequency",
"refreshNextRunAt",
"refreshInFlight",
"openIssueCount",
"instructionCount",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "KnowledgeBase"
}
}
}
}
}
},
"patch": {
"operationId": "updateKnowledgeBase",
"summary": "Update a knowledge base",
"tags": ["knowledge-bases"],
"description": "Edits the name and description, or the recurring refresh controls (`refreshEnabled`, `refreshFrequency`). Refresh fields return 422 for knowledge bases with no web or dataset source. Disabling pauses the schedule; manual refresh still works.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"refreshEnabled": {
"type": "boolean"
},
"refreshFrequency": {
"type": "string",
"enum": ["weekly", "monthly"]
}
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"200": {
"description": "KnowledgeBase",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicId": {
"type": "string"
},
"organizationId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"state": {
"type": "string",
"enum": ["created", "building", "ready", "review", "stale", "paused"]
},
"activeJobId": {
"nullable": true,
"type": "string"
},
"isBuilding": {
"type": "boolean"
},
"buildStageState": {
"nullable": true,
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"stages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"tldr",
"map",
"triage",
"plan",
"organize",
"arrange",
"write",
"review",
"polish"
]
},
"status": {
"type": "string",
"enum": ["pending", "running", "done", "failed"]
},
"units": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": ["sources", "groups", "entries", "rounds"]
},
"done": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["unit", "done"],
"additionalProperties": false
}
},
"required": ["id", "status"],
"additionalProperties": false
}
}
},
"required": ["jobId", "stages"],
"additionalProperties": false
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"lastChangedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"hasPendingChanges": {
"type": "boolean"
},
"pendingChanges": {
"nullable": true,
"type": "object",
"properties": {
"added": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"changed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"removed": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["added", "changed", "removed"],
"additionalProperties": false
},
"pipelineOutdated": {
"type": "boolean"
},
"rebuildRecommended": {
"nullable": true,
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": ["reason", "at"],
"additionalProperties": false
},
"hasWebSource": {
"type": "boolean"
},
"hasDatasetSource": {
"type": "boolean"
},
"sourceUsage": {
"nullable": true,
"type": "object",
"properties": {
"used": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["used", "limit"],
"additionalProperties": false
},
"refreshEnabled": {
"type": "boolean"
},
"refreshFrequency": {
"type": "string",
"enum": ["weekly", "monthly"]
},
"refreshNextRunAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"refreshInFlight": {
"type": "boolean"
},
"openIssueCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"instructionCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"publicId",
"organizationId",
"title",
"description",
"state",
"activeJobId",
"isBuilding",
"buildStageState",
"lastCheckedAt",
"lastChangedAt",
"hasPendingChanges",
"pendingChanges",
"pipelineOutdated",
"rebuildRecommended",
"hasWebSource",
"hasDatasetSource",
"sourceUsage",
"refreshEnabled",
"refreshFrequency",
"refreshNextRunAt",
"refreshInFlight",
"openIssueCount",
"instructionCount",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "KnowledgeBase"
}
}
}
}
}
},
"delete": {
"operationId": "deleteKnowledgeBase",
"summary": "Delete a knowledge base",
"tags": ["knowledge-bases"],
"description": "Removes the knowledge base and everything it owns: sources, imports, and revisions. Content documents in the bound dataset are deleted best-effort, and stored source files are reclaimed by a separate cleanup.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"204": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "string",
"nullable": true,
"enum": [null]
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/build": {
"post": {
"operationId": "buildKnowledgeBase",
"summary": "Trigger a knowledge base build",
"tags": ["knowledge-bases"],
"description": "Queues a build over the current corpus and returns a job id right away. If a build is already running, you get that job instead of a second one.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"202": {
"description": "JobAccepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"required": ["jobId"],
"additionalProperties": false,
"description": "JobAccepted"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/build/cancel": {
"post": {
"operationId": "cancelKnowledgeBaseBuild",
"summary": "Cancel an in-progress build",
"tags": ["knowledge-bases"],
"description": "Cancels the running build and resets the knowledge base so it can be rebuilt.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cancelled": {
"type": "boolean"
}
},
"required": ["cancelled"],
"additionalProperties": false
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/refresh": {
"post": {
"operationId": "refreshKnowledgeBase",
"summary": "Trigger an incremental refresh",
"tags": ["knowledge-bases"],
"description": "Queues a refresh: recrawls each web source, diffs the corpus against the last build, and files change issues. Returns a job id, with `started: false` when a refresh was already in flight. Supports the `Idempotency-Key` header.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"202": {
"description": "RefreshAccepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"started": {
"type": "boolean"
}
},
"required": ["jobId", "started"],
"additionalProperties": false,
"description": "RefreshAccepted"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/sources": {
"get": {
"operationId": "listSources",
"summary": "List sources",
"tags": ["sources"],
"description": "The distilled units builds cite: the pages, files, and documents your imports expanded into. Read-only; add content via `/imports`. Cursor-paginated, filter by `status`.",
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "cursor",
"required": false
},
{
"schema": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"in": "query",
"name": "limit",
"required": false
},
{
"schema": {
"type": "string",
"enum": ["pending", "processing", "ready", "failed", "skipped"]
},
"in": "query",
"name": "status",
"required": false
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "query",
"name": "importId",
"required": false
},
{
"schema": {
"type": "string"
},
"in": "query",
"name": "ids",
"required": false
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"knowledgeBaseId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"filename": {
"type": "string"
},
"kind": {
"type": "string",
"enum": ["web", "file", "dataset"]
},
"sizeBytes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"enum": ["pending", "processing", "ready", "failed", "skipped"]
},
"tldr": {
"nullable": true,
"type": "string"
},
"topics": {
"nullable": true,
"type": "array",
"items": {
"type": "string"
}
},
"canonicalUrl": {
"nullable": true,
"type": "string"
},
"fetchedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"distilledAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"filename",
"kind",
"sizeBytes",
"status",
"tldr",
"topics",
"canonicalUrl",
"fetchedAt",
"distilledAt",
"createdAt"
],
"additionalProperties": false,
"description": "Source"
}
},
"nextCursor": {
"nullable": true,
"type": "string"
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}": {
"get": {
"operationId": "getSource",
"summary": "Get a single source",
"tags": ["sources"],
"description": "Returns one source with its metadata and processing status.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "sourceId",
"required": true
}
],
"responses": {
"200": {
"description": "Source",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"knowledgeBaseId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"filename": {
"type": "string"
},
"kind": {
"type": "string",
"enum": ["web", "file", "dataset"]
},
"sizeBytes": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"enum": ["pending", "processing", "ready", "failed", "skipped"]
},
"tldr": {
"nullable": true,
"type": "string"
},
"topics": {
"nullable": true,
"type": "array",
"items": {
"type": "string"
}
},
"canonicalUrl": {
"nullable": true,
"type": "string"
},
"fetchedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"distilledAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"filename",
"kind",
"sizeBytes",
"status",
"tldr",
"topics",
"canonicalUrl",
"fetchedAt",
"distilledAt",
"createdAt"
],
"additionalProperties": false,
"description": "Source"
}
}
}
}
}
},
"delete": {
"operationId": "deleteSource",
"summary": "Delete a source",
"tags": ["sources"],
"description": "Removes the source immediately. Entries are not modified here — citations to it are cleaned up by the next build or check for changes, where entries left without sources become removal proposals. Human-edited entries are never modified.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "sourceId",
"required": true
}
],
"responses": {
"204": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "string",
"nullable": true,
"enum": [null]
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/content": {
"get": {
"operationId": "getSourceContent",
"summary": "Read a source's distilled content",
"tags": ["sources"],
"description": "The distilled markdown builds cite, the same text the pipeline itself reads. Use it to verify an issue's claims against the sources its `citedSourceIds` name. Optional `startLine` and `endLine` (1-indexed, inclusive) fetch just a span. JSON by default; `?format=markdown` returns the raw text. 409 `sourceNotDistilled` until distillation has produced content.",
"parameters": [
{
"schema": {
"type": "string",
"enum": ["json", "markdown", "plain"]
},
"in": "query",
"name": "format",
"required": false,
"description": "Output representation. `json` (default) returns the structured resource; `markdown` / `plain` return the rendered, LLM-ready text."
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"in": "query",
"name": "startLine",
"required": false
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"in": "query",
"name": "endLine",
"required": false
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "sourceId",
"required": true
}
],
"responses": {
"200": {
"description": "SourceContent",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sourceId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"content": {
"type": "string"
},
"totalLines": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"slice": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"end": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["start", "end"],
"additionalProperties": false
}
},
"required": ["sourceId", "content", "totalLines", "slice"],
"additionalProperties": false,
"description": "SourceContent"
}
},
"text/markdown": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/entries/{entryPath}/rebuild": {
"post": {
"operationId": "rebuildEntry",
"summary": "Rebuild an entry from its sources",
"tags": ["entries"],
"description": "Queues a re-write of the entry at this path from its cited sources and the active instructions, and returns a job id right away. The response also names the other entries citing any of the same sources: a source-tied rule affects every page citing that source, so those may change too.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "entryPath",
"required": true
}
],
"responses": {
"202": {
"description": "RebuildEntryResponse",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"affectedEntries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"path": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": ["id", "path", "title"],
"additionalProperties": false,
"description": "RebuildAffectedEntry"
}
}
},
"required": ["jobId", "affectedEntries"],
"additionalProperties": false,
"description": "RebuildEntryResponse"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/imports": {
"get": {
"operationId": "listImports",
"summary": "List imports",
"tags": ["imports"],
"description": "Everything added to this knowledge base, one row per import: a file upload, web crawl, dataset bind, or inline text. Cursor-paginated. The sources each import produced live under `/sources`.",
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "cursor",
"required": false
},
{
"schema": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"in": "query",
"name": "limit",
"required": false
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"knowledgeBaseId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"nullable": true,
"type": "string"
},
"sizeBytes": {
"nullable": true,
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"enum": ["uploading", "processing", "complete", "failed"]
},
"sourceKind": {
"type": "string",
"enum": ["web", "file", "dataset"]
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"sourceCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalDistillableCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"distilledCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"unsupportedCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"statusDetail": {
"nullable": true,
"type": "string"
},
"error": {
"nullable": true,
"type": "string"
},
"crawlOptions": {
"nullable": true,
"type": "object",
"properties": {
"includePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"excludePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"maxDepth": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 9007199254740991
},
"sitemapOnly": {
"type": "boolean"
},
"ignoreQueryParameters": {
"type": "boolean"
},
"pageLimit": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 5000
}
},
"additionalProperties": false,
"description": "CrawlOptions"
},
"datasetSource": {
"nullable": true,
"type": "object",
"properties": {
"sanityProjectId": {
"type": "string"
},
"sanityDatasetId": {
"type": "string"
},
"query": {
"type": "string"
}
},
"required": ["sanityProjectId", "sanityDatasetId", "query"],
"additionalProperties": false,
"description": "DatasetSourceBinding"
},
"createdBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"completedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"name",
"sizeBytes",
"status",
"sourceKind",
"lastCheckedAt",
"sourceCount",
"totalDistillableCount",
"distilledCount",
"unsupportedCount",
"statusDetail",
"error",
"crawlOptions",
"datasetSource",
"createdBy",
"createdAt",
"completedAt"
],
"additionalProperties": false,
"description": "Import"
}
},
"nextCursor": {
"nullable": true,
"type": "string"
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false
}
}
}
}
}
},
"post": {
"operationId": "createImport",
"summary": "Create an import (text, crawl, or dataset)",
"tags": ["imports"],
"description": "Adds content, discriminated on `type`: `text` for inline content, `crawl` for a website, `dataset` for a GROQ-filtered Sanity dataset. Each variant queues processing and returns a job id to poll. For files, use `POST .../imports/uploads` instead. Re-adding an existing crawl url returns 409 `webSourceRootConflict`; exceeding the crawl root limit returns 409 `webSourceRootLimitExceeded`. Supports the `Idempotency-Key` header.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["text"]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 1000000
},
"contentType": {
"default": "text/markdown",
"type": "string",
"enum": ["text/markdown", "text/plain"]
}
},
"required": ["type", "title", "content"]
},
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"options": {
"type": "object",
"properties": {
"includePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"excludePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"maxDepth": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 9007199254740991
},
"sitemapOnly": {
"type": "boolean"
},
"ignoreQueryParameters": {
"type": "boolean"
},
"pageLimit": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 5000
}
},
"description": "CrawlOptions"
},
"type": {
"type": "string",
"enum": ["crawl"]
}
},
"required": ["url", "type"]
},
{
"type": "object",
"properties": {
"sanityProjectId": {
"type": "string",
"minLength": 1
},
"sanityDatasetId": {
"type": "string",
"minLength": 1
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"type": {
"type": "string",
"enum": ["dataset"]
}
},
"required": ["sanityProjectId", "sanityDatasetId", "query", "type"]
}
],
"description": "CreateImportInput"
}
}
},
"description": "CreateImportInput"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"202": {
"description": "JobAccepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"required": ["jobId"],
"additionalProperties": false,
"description": "JobAccepted"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/imports/{importId}": {
"get": {
"operationId": "getImport",
"summary": "Get a single import",
"tags": ["imports"],
"description": "Returns one import with its kind and processing status.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "importId",
"required": true
}
],
"responses": {
"200": {
"description": "Import",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"knowledgeBaseId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"nullable": true,
"type": "string"
},
"sizeBytes": {
"nullable": true,
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"enum": ["uploading", "processing", "complete", "failed"]
},
"sourceKind": {
"type": "string",
"enum": ["web", "file", "dataset"]
},
"lastCheckedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"sourceCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalDistillableCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"distilledCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"unsupportedCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"statusDetail": {
"nullable": true,
"type": "string"
},
"error": {
"nullable": true,
"type": "string"
},
"crawlOptions": {
"nullable": true,
"type": "object",
"properties": {
"includePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"excludePaths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"maxDepth": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 9007199254740991
},
"sitemapOnly": {
"type": "boolean"
},
"ignoreQueryParameters": {
"type": "boolean"
},
"pageLimit": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 5000
}
},
"additionalProperties": false,
"description": "CrawlOptions"
},
"datasetSource": {
"nullable": true,
"type": "object",
"properties": {
"sanityProjectId": {
"type": "string"
},
"sanityDatasetId": {
"type": "string"
},
"query": {
"type": "string"
}
},
"required": ["sanityProjectId", "sanityDatasetId", "query"],
"additionalProperties": false,
"description": "DatasetSourceBinding"
},
"createdBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"completedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"name",
"sizeBytes",
"status",
"sourceKind",
"lastCheckedAt",
"sourceCount",
"totalDistillableCount",
"distilledCount",
"unsupportedCount",
"statusDetail",
"error",
"crawlOptions",
"datasetSource",
"createdBy",
"createdAt",
"completedAt"
],
"additionalProperties": false,
"description": "Import"
}
}
}
}
}
},
"delete": {
"operationId": "deleteImport",
"summary": "Delete an import",
"tags": ["imports"],
"description": "Removes the import and every source it produced, and cancels its ingest if one is still running. Use it to discard something added by mistake.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "importId",
"required": true
}
],
"responses": {
"204": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "string",
"nullable": true,
"enum": [null]
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/imports/{importId}/download": {
"get": {
"operationId": "downloadImport",
"summary": "Get a download URL for an import",
"tags": ["imports"],
"description": "Mints a short-lived signed URL serving the import's original bytes as an attachment. Use it before `expiresAt`; the bytes never pass through this API. Only file and text imports carry original bytes; crawls and dataset binds return 409 `importInvalidState`.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "importId",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": ["url", "expiresAt"],
"additionalProperties": false
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/imports/uploads": {
"post": {
"operationId": "startUpload",
"summary": "Start a file-upload import",
"tags": ["imports"],
"description": "Creates a file-upload import and returns a single-use signed upload URL. PUT the file bytes to it, then call `POST .../imports/uploads/{importId}/complete` to start ingestion. The bytes never pass through this API. Supports the `Idempotency-Key` header.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"minLength": 1
},
"contentType": {
"type": "string",
"minLength": 1
}
},
"required": ["filename"]
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"201": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"importId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"uploadUrl": {
"type": "string",
"format": "uri"
}
},
"required": ["importId", "uploadUrl"],
"additionalProperties": false
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/imports/uploads/{importId}/complete": {
"post": {
"operationId": "completeUpload",
"summary": "Complete a file-upload import",
"tags": ["imports"],
"description": "Call after the file bytes are uploaded to the signed URL. Starts processing and returns a job id to poll.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"in": "path",
"name": "importId",
"required": true
}
],
"responses": {
"202": {
"description": "JobAccepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"required": ["jobId"],
"additionalProperties": false,
"description": "JobAccepted"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/jobs/{jobId}": {
"get": {
"operationId": "getJob",
"summary": "Get a job by id",
"tags": ["jobs"],
"description": "Returns the status of a job, such as a build or an import. Job ids come from the endpoint that queued the work.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "jobId",
"required": true
}
],
"responses": {
"200": {
"description": "Job",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": ["pending", "queued", "running", "succeeded", "failed", "cancelled"]
},
"startedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"completedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"result": {},
"error": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "status", "startedAt", "completedAt"],
"additionalProperties": false,
"description": "Job"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/issues/apply": {
"post": {
"operationId": "applyIssues",
"summary": "Apply accepted issues to a Context",
"tags": ["issues"],
"description": "Queues a job that applies accepted issues, rewrites the affected entries, and commits a new revision. Returns a job id. Issue ids that no longer exist are skipped.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"issueIds": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": ["issueIds"]
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"202": {
"description": "JobAccepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"required": ["jobId"],
"additionalProperties": false,
"description": "JobAccepted"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/issues/{issueId}/dismiss": {
"post": {
"operationId": "dismissIssue",
"summary": "Dismiss an issue",
"tags": ["issues"],
"description": "Marks the issue rejected. Idempotent: dismissing an issue that already left the queue returns it as-is. 422 `issueDocumentInvalid` when the document was hand-edited into an unverifiable shape; 409 `issueTransitionConflict` on a concurrent edit, safe to retry.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "issueId",
"required": true
}
],
"responses": {
"200": {
"description": "Issue",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"knowledgeBaseId": {
"type": "string"
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"additionalProperties": false,
"description": "IssueContent"
},
"status": {
"type": "string",
"enum": ["open", "accepted", "rejected"]
},
"resolution": {
"nullable": true,
"type": "string",
"enum": ["keep_existing", "accept_new"]
},
"resolvedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": ["user", "robot"]
}
},
"required": ["id", "kind"],
"additionalProperties": false,
"description": "IssueResolvedBy"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"resolvedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"content",
"status",
"resolution",
"resolvedBy",
"createdAt",
"resolvedAt"
],
"additionalProperties": false,
"description": "Issue"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/issues/{issueId}/resolve": {
"post": {
"operationId": "resolveIssue",
"summary": "Resolve a conflict issue",
"tags": ["issues"],
"description": "Settles a conflict with one of two choices: `keep_existing` or `accept_new` (rewrites the entry; the returned `jobId` tracks it). Only conflict issues are resolvable, and a dismissed issue must be reopened first. The decision becomes a standing instruction for every future build; `resolvedBy` records who decided.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["resolution"]
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "issueId",
"required": true
}
],
"responses": {
"200": {
"description": "ResolveIssueResponse",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"issue": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"knowledgeBaseId": {
"type": "string"
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"additionalProperties": false,
"description": "IssueContent"
},
"status": {
"type": "string",
"enum": ["open", "accepted", "rejected"]
},
"resolution": {
"nullable": true,
"type": "string",
"enum": ["keep_existing", "accept_new"]
},
"resolvedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": ["user", "robot"]
}
},
"required": ["id", "kind"],
"additionalProperties": false,
"description": "IssueResolvedBy"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"resolvedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"content",
"status",
"resolution",
"resolvedBy",
"createdAt",
"resolvedAt"
],
"additionalProperties": false,
"description": "Issue"
},
"jobId": {
"nullable": true,
"type": "string"
}
},
"required": ["issue", "jobId"],
"additionalProperties": false,
"description": "ResolveIssueResponse"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/issues/{issueId}/reopen": {
"post": {
"operationId": "reopenIssue",
"summary": "Reopen an accepted conflict",
"tags": ["issues"],
"description": "Returns an accepted conflict to triage, clearing its resolution and deleting the instruction it minted. Idempotent for issues that are not accepted conflicts.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "issueId",
"required": true
}
],
"responses": {
"200": {
"description": "Issue",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"knowledgeBaseId": {
"type": "string"
},
"content": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conflict",
"gap",
"update_required",
"add_entry",
"remove_entry",
"split_entry",
"merge_entry"
]
},
"severity": {
"type": "string",
"enum": ["critical", "suggestion"]
},
"scopePath": {
"type": "string"
},
"issue": {
"type": "string"
},
"suggestedFix": {
"type": "string"
},
"citedSourceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"claimKey": {
"type": "string"
},
"involvedScopes": {
"type": "array",
"items": {
"type": "string"
}
},
"currentClaim": {
"type": "string"
},
"alternativeClaim": {
"type": "string"
},
"currentAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"alternativeAuthority": {
"type": "string",
"enum": ["primary", "secondary", "community"]
},
"suggestedResolution": {
"type": "string",
"enum": ["keep_existing", "accept_new"]
}
},
"required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
"additionalProperties": false,
"description": "IssueContent"
},
"status": {
"type": "string",
"enum": ["open", "accepted", "rejected"]
},
"resolution": {
"nullable": true,
"type": "string",
"enum": ["keep_existing", "accept_new"]
},
"resolvedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": ["user", "robot"]
}
},
"required": ["id", "kind"],
"additionalProperties": false,
"description": "IssueResolvedBy"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"resolvedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"content",
"status",
"resolution",
"resolvedBy",
"createdAt",
"resolvedAt"
],
"additionalProperties": false,
"description": "Issue"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/instructions": {
"post": {
"operationId": "createInstruction",
"summary": "Author a human instruction",
"tags": ["instructions"],
"description": "Creates a standing rule that every future build honors. Tie it to one or more sources with `scopeSourceIds`, or leave it null to apply knowledge-base-wide. Pass `rebuildPaths` to immediately rebuild those entries under the new rule; the response carries the rebuild job id, or null when the rebuild could not start (the rule is saved either way). Pass `verified` after a completed synchronous contradiction check to skip the background one; if the requested rebuild fails to start, the background check runs anyway so the contradicting pages get filed as issues.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statement": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"scopeSourceIds": {
"nullable": true,
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"rebuildPaths": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verified": {
"type": "boolean"
}
},
"required": ["statement"],
"description": "CreateInstructionInput"
}
}
},
"description": "CreateInstructionInput"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
}
],
"responses": {
"201": {
"description": "CreateInstructionResponse",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"instruction": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"knowledgeBaseId": {
"type": "string"
},
"origin": {
"type": "string",
"enum": ["conflict", "human"]
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"statement": {
"type": "string"
},
"scopeSourceIds": {
"nullable": true,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"archivedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"archivedReason": {
"nullable": true,
"type": "string"
},
"sourceIssueId": {
"nullable": true,
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"updatedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"origin",
"status",
"statement",
"scopeSourceIds",
"archivedAt",
"archivedReason",
"sourceIssueId",
"createdBy",
"updatedBy",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Instruction"
},
"rebuildJobId": {
"nullable": true,
"type": "string"
}
},
"required": ["instruction", "rebuildJobId"],
"additionalProperties": false,
"description": "CreateInstructionResponse"
}
}
}
}
}
}
},
"/{apiVersion}/context/knowledge-bases/{knowledgeBaseId}/instructions/{instructionId}": {
"patch": {
"operationId": "updateInstruction",
"summary": "Edit an instruction",
"tags": ["instructions"],
"description": "Edits the statement or scope. The change applies from the next build. Any edit re-affirms the rule: an archived rule returns to active, re-anchored to the sources' current content.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statement": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"scopeSourceIds": {
"nullable": true,
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"description": "UpdateInstructionInput"
}
}
},
"description": "UpdateInstructionInput"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "instructionId",
"required": true
}
],
"responses": {
"200": {
"description": "Instruction",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"knowledgeBaseId": {
"type": "string"
},
"origin": {
"type": "string",
"enum": ["conflict", "human"]
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"statement": {
"type": "string"
},
"scopeSourceIds": {
"nullable": true,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"archivedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"archivedReason": {
"nullable": true,
"type": "string"
},
"sourceIssueId": {
"nullable": true,
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"updatedBy": {
"nullable": true,
"type": "object",
"properties": {
"id": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
}
},
"required": ["id", "displayName"],
"additionalProperties": false,
"description": "Actor"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"knowledgeBaseId",
"origin",
"status",
"statement",
"scopeSourceIds",
"archivedAt",
"archivedReason",
"sourceIssueId",
"createdBy",
"updatedBy",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Instruction"
}
}
}
}
}
},
"delete": {
"operationId": "deleteInstruction",
"summary": "Delete an instruction",
"tags": ["instructions"],
"description": "Deletes the rule. Builds stop honoring it from the next run.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "knowledgeBaseId",
"required": true
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "instructionId",
"required": true
}
],
"responses": {
"204": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "string",
"nullable": true,
"enum": [null]
}
}
}
}
}
}
},
"/{apiVersion}/context/organizations/{organizationId}/conversations/{threadId}": {
"put": {
"operationId": "saveConversation",
"summary": "Record a conversation",
"tags": ["conversations"],
"description": "Upserts the conversation telemetry for one thread. `threadId` identifies the conversation within your organization — reuse means the same conversation. Messages replace the stored transcript wholesale; `metadata` and model fields only overwrite when present. Last write per thread wins — retries are safe.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": ["user", "assistant", "system", "tool"]
},
"content": {
"default": null,
"nullable": true,
"type": "string",
"maxLength": 20000
},
"toolName": {
"default": null,
"nullable": true,
"type": "string"
},
"toolType": {
"default": null,
"nullable": true,
"type": "string",
"enum": ["call", "result"]
}
},
"required": ["role"],
"description": "ConversationMessage"
}
},
"modelProvider": {
"type": "string"
},
"modelId": {
"type": "string"
},
"tokenUsage": {
"type": "object",
"properties": {
"inputTokens": {
"type": "number"
},
"outputTokens": {
"type": "number"
},
"totalTokens": {
"type": "number"
}
},
"description": "ConversationTokenUsage"
},
"metadata": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 256
}
}
]
},
"description": "ConversationMetadata"
}
},
"required": ["messages"],
"description": "SaveConversationInput"
}
}
},
"description": "SaveConversationInput"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"in": "path",
"name": "threadId",
"required": true
}
],
"responses": {
"200": {
"description": "Conversation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"threadId": {
"type": "string"
},
"metadata": {
"nullable": true,
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 256
}
}
]
},
"description": "ConversationMetadata"
},
"startedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messagesUpdatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": ["user", "assistant", "system", "tool"]
},
"content": {
"default": null,
"nullable": true,
"type": "string",
"maxLength": 20000
},
"toolName": {
"default": null,
"nullable": true,
"type": "string"
},
"toolType": {
"default": null,
"nullable": true,
"type": "string",
"enum": ["call", "result"]
}
},
"required": ["role", "content", "toolName", "toolType"],
"additionalProperties": false,
"description": "ConversationMessage"
}
},
"modelProvider": {
"nullable": true,
"type": "string"
},
"modelId": {
"nullable": true,
"type": "string"
},
"tokenUsage": {
"nullable": true,
"type": "object",
"properties": {
"inputTokens": {
"type": "number"
},
"outputTokens": {
"type": "number"
},
"totalTokens": {
"type": "number"
}
},
"additionalProperties": false,
"description": "ConversationTokenUsage"
},
"coreMetrics": {
"nullable": true,
"type": "object",
"properties": {
"successScore": {
"type": "number"
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
},
"contentGaps": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "ConversationCoreMetrics"
},
"classifiedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"classificationError": {
"nullable": true,
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"threadId",
"metadata",
"startedAt",
"messagesUpdatedAt",
"messages",
"modelProvider",
"modelId",
"tokenUsage",
"coreMetrics",
"classifiedAt",
"classificationError",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Conversation"
}
}
}
}
}
},
"patch": {
"operationId": "classifyConversation",
"summary": "Record a classification verdict",
"tags": ["conversations"],
"description": "Records the classification your own model produced for one thread: exactly one of `coreMetrics` (a verdict — the server stamps `classifiedAt` and clears any recorded failure) or `classificationError` (why classification failed; an earlier verdict stays untouched). No revision guard — like the ingest upsert the writer is an automated classifier, so last write wins and a re-classification simply overwrites.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"coreMetrics": {
"type": "object",
"properties": {
"successScore": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
},
"contentGaps": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
}
},
"required": ["successScore", "sentiment", "contentGaps"]
},
"classificationError": {
"type": "string",
"maxLength": 500
}
},
"description": "ClassifyConversationInput"
}
}
},
"description": "ClassifyConversationInput"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"in": "path",
"name": "threadId",
"required": true
}
],
"responses": {
"200": {
"description": "Conversation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"threadId": {
"type": "string"
},
"metadata": {
"nullable": true,
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 256
}
}
]
},
"description": "ConversationMetadata"
},
"startedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messagesUpdatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": ["user", "assistant", "system", "tool"]
},
"content": {
"default": null,
"nullable": true,
"type": "string",
"maxLength": 20000
},
"toolName": {
"default": null,
"nullable": true,
"type": "string"
},
"toolType": {
"default": null,
"nullable": true,
"type": "string",
"enum": ["call", "result"]
}
},
"required": ["role", "content", "toolName", "toolType"],
"additionalProperties": false,
"description": "ConversationMessage"
}
},
"modelProvider": {
"nullable": true,
"type": "string"
},
"modelId": {
"nullable": true,
"type": "string"
},
"tokenUsage": {
"nullable": true,
"type": "object",
"properties": {
"inputTokens": {
"type": "number"
},
"outputTokens": {
"type": "number"
},
"totalTokens": {
"type": "number"
}
},
"additionalProperties": false,
"description": "ConversationTokenUsage"
},
"coreMetrics": {
"nullable": true,
"type": "object",
"properties": {
"successScore": {
"type": "number"
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
},
"contentGaps": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "ConversationCoreMetrics"
},
"classifiedAt": {
"nullable": true,
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"classificationError": {
"nullable": true,
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"threadId",
"metadata",
"startedAt",
"messagesUpdatedAt",
"messages",
"modelProvider",
"modelId",
"tokenUsage",
"coreMetrics",
"classifiedAt",
"classificationError",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Conversation"
}
}
}
}
}
}
}
},
"servers": [
{
"url": "https://api.sanity.io",
"description": "Production"
}
],
"tags": [
{
"name": "knowledge-bases",
"description": "Knowledge bases: create, configure, build"
},
{
"name": "entries",
"description": "Knowledge pages: rebuild actions and serving reads"
},
{
"name": "issues",
"description": "Build findings awaiting triage; the API owns transitions"
},
{
"name": "instructions",
"description": "Standing rules steering every build"
},
{
"name": "conversations",
"description": "Agent conversation telemetry: ingest and classification"
},
{
"name": "jobs",
"description": "Background job (build / ingest) status"
},
{
"name": "imports",
"description": "Source intake: uploads, web crawls, dataset binds"
},
{
"name": "sources",
"description": "The distilled units builds cite, produced by imports"
}
]
}