Optionaldelete?: undefinedList knowledge bases
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalcursor?: stringOptionalincludeDrafts?: "true" | "false"Optionallimit?: numberOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedCreate a knowledge base
Creates a knowledge base in your organization. To add content to it, add a source. Set draft to true to create a draft, which needs no title or description until you finish it. If your organization's Context document store can't be used, the request returns 503 with code contextStoreUnavailable and you can retry.
Optionalcookie?: undefinedOptionalheader?: { "Idempotency-Key"?: string }OptionalIdempotency-Key?: stringOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete a knowledge base
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedGet a knowledge base
Returns a knowledge base's metadata and state. knowledgeBaseId accepts the public ID (kb...) or the UUID, and you don't need to pass an organization. If you can't read the knowledge base, the request returns 404. To read the built entries, query sanity.context.entry documents with GROQ from your organization's document store.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedUpdate a knowledge base
Updates the title or the description, or finishes a draft (draft: false). Fields equal to their current value are ignored, so sending the current values changes nothing. Finishing a draft with no title returns 422 with code draftTitleRequired. How often a website or dataset syncs is set on the source, with PATCH .../sources/{sourceId}.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedStart a knowledge base build
Optionalcookie?: undefinedOptionalheader?: { "Idempotency-Key"?: string }OptionalIdempotency-Key?: stringOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedCancel a knowledge base build
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedList documents
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: {Optionalcursor?: stringOptionalids?: stringOptionallimit?: numberOptionalsource?: stringOptionalstate?: "active" | "missing" | "deleted"OptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete a document
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedGet a document
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedKeep a missing document
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedGet a document's markdown
Returns the markdown a document converted to: the text builds read, and the line numbers citations use. Set chunk or lines to get part of it, and format to markdown or plain to get the text alone instead of JSON. Until the document is converted, the request returns 409 with code documentNotConverted. With format=raw it returns the document as its source gave it, as an attachment, or 409 with code documentNotStored when the document was too large to keep.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: {Optionalchunk?: stringOptionalformat?: "json" | "raw" | "markdown" | "plain"Optionallines?: stringOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedRebuild an entry from its sources
Queues a rewrite of the entry at entryPath from its cited sources and the active instructions, and returns a job ID immediately. The response also lists the other entries built from any of the same sources. An instruction applies to every entry built from its sources, so those entries can change too. Returns 422 with code entryDocumentInvalid if the entry document was edited into a shape the API cannot read.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedCreate an instruction
Creates a standing instruction for how entries built from its documents are written. Every instruction applies to specific documents, set in scopeDocumentIds. To rebuild entries under the new instruction right away, pass their paths in rebuildPaths. The response includes the rebuild job ID, or null if the rebuild could not start. The instruction is saved either way. After the instruction is saved, a background check files issues for entries that contradict it. If you already checked the instruction for contradictions, set verified to skip the background check. If the requested rebuild does not start, the background check runs even when verified is set.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete an instruction
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: { rebuild?: "true" | "false" }Optionalrebuild?: "true" | "false"OptionalrequestBody?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedUpdate an instruction
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedDismiss an issue
Marks the issue as rejected. If the issue already left triage, the request returns it unchanged. Returns 422 with code issueDocumentInvalid if the issue document was edited into a shape the API cannot verify. Returns 409 with code issueTransitionConflict if another change to the issue happened at the same time. You can safely retry a 409.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedReopen an accepted conflict
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedResolve a conflict issue
Resolves a conflict issue by choosing one of its sides. Set resolution to the index of a side in content.sides. For a conflict on a single entry, index 0 is the entry's current content, so choosing it keeps the entry as it is. Choosing any other side rewrites the entry, and the returned jobId tracks the rewrite. The decision becomes a standing instruction for every future build, and resolvedBy records who made it. To change a decision, resolve the accepted conflict again. Other issue types, dismissed conflicts, and out-of-range indexes return 422 with code issueNotResolvable.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedAccept and apply issues
Accepts the issues in issueIds, then queues a job that applies them, rewrites the affected entries, and saves a new revision. Returns a job ID. IDs of issues that no longer exist are skipped. Returns 409 with code issueNotAutoApplicable, and accepts none of the issues, if any of them cannot be applied: a conflict (resolve it with POST .../issues/{issueId}/resolve), or an update_required issue whose scopePath is * or names an entry that no longer exists. Dismiss those instead.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedGet a job
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedList sources
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: { cursor?: string; limit?: number }Optionalcursor?: stringOptionallimit?: numberOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedAdd a source
Adds a source to a knowledge base. Set type to choose what it reads:
- `web`: a website, crawled from `url`
- `sanity-dataset`: the documents a GROQ query selects in a Sanity dataset
- `files`: files you upload with `POST .../sources/{sourceId}/uploads`, or text you send in `content`
A website or dataset starts its first sync right away. A `files` source syncs when you upload a file, or right away when you send `content`: one request stores the text, adds the source and starts its sync. For a website, set `dryRun` to `true` to preview the crawl without adding the source.
Adding a website that is already a source returns `409` with code `webSourceRootConflict`, and adding more websites than your limit allows returns `409` with code `webSourceRootLimitExceeded`. When the organization's knowledge bases already hold as many source chunks as its plan allows, returns `403` with code `planLimitReached` and adds nothing. Supports the `Idempotency-Key` header.
Optionalcookie?: undefinedOptionalheader?: { "Idempotency-Key"?: string }OptionalIdempotency-Key?: stringOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete a source
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedGet a source
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedUpdate a source
Changes a source's title, a website's crawl options, a dataset's query, or how often a website or dataset syncs on its own. New crawl options delete the documents whose path they leave out. When that would delete all of the source's documents, or five or more that are over a fifth of them, the request returns 409 with code sourceDeletionsUnconfirmed until you send it again with confirmDeletions set to true. New crawl options sent while the source syncs return 409 with code syncInProgress; send them again once the sync finishes. A new query queues a sync, which removes the documents the query no longer selects.
Crawl options on a source that isn't a website, a query on one that isn't a dataset, or a sync frequency on a `files` source, return `422` with code `sourceTypeMismatch`. Setting a sync frequency on a plan without scheduled syncs returns `403` with code `featureNotInPlan`; setting it to `null` always works.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedList a source's syncs
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: { cursor?: string; limit?: number }Optionalcursor?: stringOptionallimit?: numberOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedSync a source
Starts a sync of the source. A website or dataset is read again: its sync is queued, and starts once any sync of the source that is running ends, including the first one that started when it was added. Asking again while one waits queues nothing more. Follow it with the source's latestSync.
For a `files` source, set `uploadId` to the upload whose file the source should hold from now on; without it, the source reads its current file again. Its sync starts at once and returns a job ID to poll; the finished job's `result` names the sync and whether it is `held`. While a sync of a `files` source is running, including the first one, the request returns `409` with code `syncInProgress` and leaves the upload for a later request. An `uploadId` whose file never arrived returns `404` with code `uploadNotFound`, and an `uploadId` on a source that isn't `files` returns `422` with code `sourceTypeMismatch`.
Supports the `Idempotency-Key` header.
Optionalcookie?: undefinedOptionalheader?: { "Idempotency-Key"?: string }OptionalIdempotency-Key?: stringOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedGet a sync
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedConfirm a held sync's deletions
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedDiscard a held sync's deletions
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedUpload a file to a source
Returns a single-use signed URL for one file of a files source, valid for one hour. To add the file:
1. Send the file in a `PUT` request to `uploadUrl`.
2. Call `POST .../sources/{sourceId}/syncs` with the `uploadId`.
The file can be a single document or a zip, tar or gzip archive of them. It replaces the source's current file when it syncs. An upload no sync takes within 24 hours is deleted. A source that isn't `files` returns `422` with code `sourceTypeMismatch`. When the organization's knowledge bases already hold as many source chunks as its plan allows, returns `403` with code `planLimitReached`. Supports the `Idempotency-Key` header.
Optionalcookie?: undefinedOptionalheader?: { "Idempotency-Key"?: string }OptionalIdempotency-Key?: stringOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedSync every source
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete a conversation
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedRecord a conversation classification
Records the classification your own model produced for one thread. Send exactly one of these fields:
- `coreMetrics`: the classification result. The API sets `classifiedAt` and clears any recorded failure.
- `classificationError`: why classification failed. Any earlier result stays unchanged.
Requires the same access as recording a conversation. The last write wins, so a new classification replaces the previous one.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalpost?: undefinedRecord a conversation
Creates or updates the recorded conversation for one thread. threadId identifies the conversation within your organization, so saving with the same threadId updates the same conversation. Requires Context Editor access or higher.
Each save replaces the stored messages. `metadata`, `sharing`, and the model fields change only when you include them. `tokenUsage` is cumulative: send the usage for one generation call, and the API adds it to the conversation total. Usage is added only when the save changes the messages, so retries don't count it twice.
To report a failure, set `error` on the message where it happened: the tool result for a failed tool call, or the assistant message for a turn that failed instead of answering. The Insights dashboard highlights conversations with a failed turn and counts failed tool calls separately, because agents often recover from them.
The last write for a thread wins, so retries are safe. `sharing` records whether you share telemetry with Sanity: metrics only, or full transcripts.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedCreate an MCP endpoint
Creates an MCP endpoint with a title, a name, and the sources it serves. A source is a knowledge base, identified by its ID (kb…), or a dataset, identified as <projectId>.<datasetName>. An endpoint can serve any number of knowledge bases and at most one dataset, all at once. A GROQ filter is only kept when the endpoint has a dataset. The name must be unique in your organization, and you can't change it later. Duplicate sources with the same type and id are combined. The response includes the url agents connect to. To list or inspect endpoints, query sanity.context.mcp documents with GROQ from your organization's document store. Requires the sanity.context.mcp.create grant on the organization, which the Administrator and Developer roles have. Adding a dataset also requires full read access to the dataset and, on its project, the Administrator or Developer role or a custom role that can create datasets.
A taken name returns `409` with code `mcpEndpointNameConflict`. A knowledge base that doesn't exist in the organization returns `422` with code `mcpSourceKnowledgeBaseNotFound`, and an invalid GROQ filter returns `422` with code `invalidGroqFilter`.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedDelete an MCP endpoint
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedOptionalrequestBody?: undefinedOptionalget?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedUpdate an MCP endpoint
Updates the title, sources, instructions, or GROQ filter of the endpoint with that name or ID. To clear an optional field, set it to null. An endpoint can have at most one dataset source, and removing it clears the GROQ filter. You can't change the name, so the endpoint URL stays the same. Requires the sanity.context.mcp.update grant on the organization. Adding a dataset source requires full read access to the dataset and, on its project, the Administrator or Developer role or a custom role that can create datasets. Changing the GROQ filter requires the same access for the endpoint's dataset. Sending the current values changes nothing.
An unknown endpoint returns `404` with code `mcpEndpointNotFound`. A knowledge base that doesn't exist in the organization returns `422` with code `mcpSourceKnowledgeBaseNotFound`, and an invalid GROQ filter returns `422` with code `invalidGroqFilter`. If the endpoint changed while the update was in progress, the update returns `409` with code `mcpEndpointEditConflict` and changes nothing. You can safely retry it.
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: undefinedConnect to an MCP endpoint
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: {Optionalembeddings?: stringOptionalgroqFilter?: stringOptionalinstructions?: stringOptionalknowledgeBases?: stringOptionallinkResolver?: stringOptionalmode?: "groq" | "knowledge_base"Serves only one side of the endpoint for this request: knowledge_base serves its knowledge bases and groq serves its dataset. Omit it to serve every source the endpoint has. A request whose chosen side the endpoint doesn't have is refused. Deprecated: refused from API version v2026-11-03. Configure it on the MCP endpoint instead.
Optionalperspective?: stringOptionalworkspace?: stringOptionalrequestBody?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedGet an MCP endpoint's initial context
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: {Optionalembeddings?: stringOptionalgroqFilter?: stringOptionalheading_offset?: stringOptionalinstructions?: stringOptionalknowledgeBases?: stringOptionallinkResolver?: stringOptionalmode?: "groq" | "knowledge_base"Serves only one side of the endpoint for this request: knowledge_base serves its knowledge bases and groq serves its dataset. Omit it to serve every source the endpoint has. A request whose chosen side the endpoint doesn't have is refused. Deprecated: refused from API version v2026-11-03. Configure it on the MCP endpoint instead.
Optionalperspective?: stringOptionalworkspace?: stringOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefinedOptionaldelete?: undefinedCheck an MCP endpoint
Optionalcookie?: undefinedOptionalheader?: undefinedOptionalquery?: {Optionalembeddings?: stringOptionalgroqFilter?: stringOptionalinstructions?: stringOptionalknowledgeBases?: stringOptionallinkResolver?: stringOptionalmode?: "groq" | "knowledge_base"Serves only one side of the endpoint for this request: knowledge_base serves its knowledge bases and groq serves its dataset. Omit it to serve every source the endpoint has. A request whose chosen side the endpoint doesn't have is refused. Deprecated: refused from API version v2026-11-03. Configure it on the MCP endpoint instead.
Optionalperspective?: stringOptionalworkspace?: stringOptionalrequestBody?: undefinedOptionalhead?: undefinedOptionaloptions?: undefinedOptionalpatch?: undefinedOptionalpost?: undefinedOptionalput?: undefinedOptionaltrace?: undefined
This file was auto-generated by openapi-typescript. Do not make direct changes to the file.