Attach a workspace knowledge source
Idempotent direct-library attachment. Accepts this workspace source or the target agent’s own source; never another agent’s source. It does not transfer ownership or publish. Archived sources cannot be newly attached. A new membership changes the agent’s publication ETag because the direct library is the next-publish knowledge input.
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Path parameters
Headers
Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.
Response headers
true when this response replays a stored Idempotency-Key result. The status and body equal the original.
Response
Fallback means available as bounded prompt context when the source is in the direct agent library; it is not indexed retrieval. Reads do not start ingestion. content_sha256 describes ingested source bytes, not necessarily the local input file after extraction. A URL source is refreshed by reingest and keeps its key. File and text content is immutable: for new content create a new source with a new name and a versioned key such as “<key>:v2”, add it to each required agent library, publish those agents, then archive the old source. Names and keys stay taken by archived sources; deleting a source that no snapshot or published version has cited frees them; a duplicate name returns conflict (details.reason=name_taken). Keep old source revisions while publications refer to them. A URL reingest refreshes its source revision. Agent retirement is not available through this API. owner is immutable. Agent ownership controls library membership and lifecycle; it is not a permission. Access follows the key capabilities. Shared attachment does not transfer ownership. name is unique within its owner scope (the workspace library, or one agent library), so two agents can each own a same-named document.
Open response vocabulary. Preserve unknown values; never assume they mean success.