> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge source writes

> Current administrator operations for knowledge source documents, removal, restoration, and settings.

These four existing write routes require an authenticated administrator, the account's `orchestration_studio` feature, and the route's individual default-off deployment switch. Account membership and the account-owned crawl are resolved before source or document state is changed. A deployment switch enables only that route family; it is not an account permission or a replacement for administrator authorization. Anonymous and foreign-account requests receive 401, an agent receives 403, a suspended account receives 401, a trial-locked write receives 402, and a feature-off or route-switch-off request receives 404. Unknown and mismatched source/document IDs receive 404.

The `KNOWLEDGE_SOURCE_EXCLUSION_ENABLED`, `KNOWLEDGE_SOURCE_REMOVAL_ENABLED`, and `KNOWLEDGE_SOURCE_SETTINGS_ENABLED` variables are deployment controls. Each is off unless its value is exactly `on`. These APIs do not reveal deployment environment values. Source URLs, document titles, and other crawl metadata can contain customer-controlled content; treat them as untrusted. Responses and source events do not include document bodies, chunk text, embeddings, credentials, or provider-delivery claims.

## Exclude or keep one document

`PATCH /api/v1/accounts/{account_id}/knowledge_sources/{knowledge_source_id}/documents/{id}` accepts `excluded`, `kept`, or both. At least one recognized key is required. Each value can be a JSON boolean or the literal string `true` or `false`; other types and strings return 422. `excluded` changes whether the document is used in answers. `kept` controls purge retention and clears a pending purge reminder when set. The `kept` response property appears only when that key was sent.

The source identifier is an account-owned crawl, not an independent source model ID. The document must belong to a crawl for the same source URL in the same account; another account's crawl/document, a document fetched by a different source, or an unknown ID returns 404. Exclusion changes write one `exclude` or `include` source event with flags, timestamps, and actor identifiers. Keeping uses its own `keep` event. Repeating an existing state writes no new event. If both keys are supplied, exclusion and keep are handled separately and are not one atomic bulk transaction.

## Remove or restore a source

`POST /api/v1/accounts/{account_id}/knowledge_sources/{id}/remove` soft-excludes that source URL from answers. It does not delete crawls, documents, or chunks. A state change records the removal flags, timestamp, actor and one internal `remove` event. Repeating remove returns the current state without a duplicate event.

`POST /api/v1/accounts/{account_id}/knowledge_sources/{id}/restore` clears those flags and records one internal `restore` event when the state changes. Restoring a source that has never been removed is a successful no-op and creates neither a settings row nor an event. If a page is later fetched by a different active source, that page follows its current crawl ownership and may be served through that source.

These event actions are account-owned internal records. Their names do not promise public webhook delivery. The response contains only `source_url` and `removed`.

## Update settings

`PATCH /api/v1/accounts/{account_id}/knowledge_sources/{id}/settings` accepts either or both of:

* `priority`: a JSON integer from 0 through 3.
* `recrawl_interval_hours`: a JSON integer from 24 through 8760, or `null` to clear it.

Numeric strings, fractional numbers, out-of-range values, or a body without a recognized setting return 422. Partial updates preserve the other setting and removal flags. Each changed value writes one internal source event (`set_priority` or `set_cadence`) under the source settings lock. Repeating the same values writes no event.

This only stores the cadence. It does not turn on scheduled paid crawling or start a fetch. The source is resolved through an account-owned crawl, and only that account's settings and events can change.

## Related current reads and inactive missing-surface inventory

The seven existing case/source reads remain documented once on the [Orchestration Studio read API](/api-reference/orchestration-studio). The five current proposal operations and three current model operations remain on [Knowledge proposals](/api-reference/knowledge-proposals) and [Model settings](/api-reference/model-settings). The inactive ENG-5858 inventory records requested proposal, source, gap, and topic actions with their current route reuse or missing status. It is proposal evidence only: it grants no route, role, scope, event delivery, SDK access, or MCP exposure. Missing bulk limits and per-item outcomes remain open runtime work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.