{ "openapi": "3.0.4", "info": { "title": "TKP API", "description": "REST API for searching and managing knowledge libraries and resources. Protected endpoints accept a personal Access Token or OAuth 2.0 with the `api:use` scope.", "version": "0.9.0" }, "servers": [ { "url": "https://tkp.example/api", "description": "API Server" } ], "paths": { "/v1/auth/check": { "get": { "tags": [ "Auth" ], "summary": "Verify authentication and return the access context", "description": "Returns the workspace, user, grant type, enabled interfaces, global abilities, and effective library rights.", "operationId": "getAccessContext", "responses": { "200": { "description": "Access context for the current grant.", "content": { "application/json": { "schema": { "required": [ "tenant", "user", "grant_type", "interfaces", "abilities", "libraries" ], "properties": { "tenant": { "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Workspace" }, "slug": { "type": "string", "example": "acme-workspace" } }, "type": "object" }, "user": { "description": "The user who owns the active access grant.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Workspace Owner" }, "email": { "type": "string", "format": "email", "example": "owner@example.test" } }, "type": "object", "nullable": true }, "grant_type": { "type": "string", "enum": [ "access_token", "connected_app" ] }, "interfaces": { "type": "array", "items": { "type": "string", "enum": [ "api", "mcp" ] } }, "abilities": { "description": "Abilities stored on the active grant. Effective access is further limited by the owning user.", "type": "array", "items": { "type": "string", "enum": [ "library.create", "library.delete", "library.all.read", "library.all.resource.create", "library.all.update", "library.all.resource.delete" ] }, "example": [ "library.create", "library.all.read" ] }, "libraries": { "type": "array", "items": { "$ref": "#/components/schemas/LibrarySummary" } } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/assets/{asset}": { "get": { "tags": [ "Assets" ], "summary": "Download the binary payload of an asset", "description": "Streams the canonical payload of an asset. Accepts either an API-enabled bearer credential or a signed URL from `POST /v1/assets/{asset}/view-urls` with the default `content` representation. Without a bearer credential, `signature`, `expires`, and `tenant_id` must all be present and valid.", "operationId": "downloadAsset", "parameters": [ { "name": "asset", "in": "path", "description": "Opaque asset identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/AssetId" } }, { "name": "signature", "in": "query", "description": "HMAC signature from a view-url response.", "required": false, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "description": "Unix expiry timestamp from a view-url response.", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Tenant ID encoded in a signed view URL.", "required": false, "schema": { "type": "integer" } }, { "name": "disposition", "in": "query", "description": "Content-Disposition behavior. When the URL was signed with a `disposition` value, this parameter must match the signed value.", "required": false, "schema": { "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } } ], "responses": { "200": { "description": "Asset binary as a stream. The `Content-Type` is the asset's actual MIME type (e.g. `image/png`, `image/jpeg`); `application/octet-stream` is used only as a fallback for unknown types.", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "inline; filename=\"asset-image-ast_abc.png\"" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/assets/{asset}/representations/scene": { "get": { "tags": [ "Assets" ], "summary": "Download a scene representation of a video asset", "description": "Returns the stored five-frame PNG collage for the half-open scene interval containing the timestamp. This derived representation is available only for video assets and accepts an API-enabled bearer credential or a matching signed URL.", "operationId": "downloadAssetSceneRepresentation", "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AssetId" } }, { "name": "timestamp_seconds", "in": "query", "required": true, "schema": { "type": "number", "format": "float", "minimum": 0 } }, { "name": "signature", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } } ], "responses": { "200": { "description": "Five-frame scene collage.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/assets/{asset}/representations/frame": { "get": { "tags": [ "Assets" ], "summary": "Download a frame representation of a video asset", "description": "Extracts or returns a cached PNG frame at the requested timestamp. This derived representation is available only for video assets and accepts an API-enabled bearer credential or a matching signed URL.", "operationId": "downloadAssetFrameRepresentation", "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AssetId" } }, { "name": "timestamp_seconds", "in": "query", "required": true, "schema": { "type": "number", "format": "float", "minimum": 0 } }, { "name": "signature", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } } ], "responses": { "200": { "description": "Exact PNG video frame.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/assets/{asset}/view-urls": { "post": { "tags": [ "Assets" ], "summary": "Issue a short-lived public URL for an asset representation", "description": "Creates a signed URL for the canonical asset content or a derived scene or frame representation. `content` is the default and works for every downloadable asset. `scene` and `frame` require a video asset and `timestamp_seconds`. Signed query parameters cannot be changed afterwards.", "operationId": "issueAssetViewUrl", "parameters": [ { "name": "asset", "in": "path", "description": "Opaque asset identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/AssetId" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "representation": { "description": "`content` returns the asset payload. `scene` and `frame` select derived video representations.", "type": "string", "default": "content", "enum": [ "content", "scene", "frame" ] }, "timestamp_seconds": { "description": "Required for `scene` and `frame`; prohibited for `content`.", "type": "number", "format": "float", "minimum": 0 }, "ttl_minutes": { "type": "integer", "default": 15, "maximum": 60, "minimum": 1 }, "disposition": { "description": "Content-Disposition to apply. The value is signed; changing it afterwards invalidates the URL.", "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Signed view URL.", "content": { "application/json": { "schema": { "required": [ "url", "representation", "expires_in_minutes" ], "properties": { "url": { "type": "string", "format": "uri" }, "representation": { "type": "string", "enum": [ "content", "scene", "frame" ] }, "expires_in_minutes": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries": { "get": { "tags": [ "Libraries" ], "summary": "List libraries accessible in the authenticated context", "description": "Returns libraries for which the current context has read access, including the exact per-library `access` array. Results are cursor-paginated.", "operationId": "listLibraries", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of libraries to return per page.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 500, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor returned in the previous page `next_cursor`. Omit on the first request.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of libraries accessible to the current grant.", "content": { "application/json": { "schema": { "required": [ "items", "limit", "next_cursor", "truncated" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LibrarySummary" } }, "limit": { "type": "integer", "example": 50 }, "next_cursor": { "description": "Opaque cursor for the next page, or null when no more pages are available. `truncated` is true exactly when `next_cursor` is not null.", "type": "string", "nullable": true }, "truncated": { "description": "True when more pages are available. Equivalent to `next_cursor != null`.", "type": "boolean", "example": false } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] }, "post": { "tags": [ "Libraries" ], "summary": "Create a new library", "description": "Creates a new library in the authenticated tenant. The caller must have the global `library.create` ability. Creating a library does not automatically grant access to it.", "operationId": "createLibrary", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLibraryRequest" } } } }, "responses": { "201": { "description": "Library created.", "headers": { "Location": { "description": "Absolute URL of the created library. Requires authentication.", "schema": { "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/libraries/lib_s50vofoljazr" } } }, "content": { "application/json": { "schema": { "required": [ "id", "name", "overview", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/LibraryId" }, "name": { "type": "string", "example": "Technical Documentation" }, "overview": { "type": "string", "example": "Product manuals, RFCs, and engineering specifications.", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}": { "get": { "tags": [ "Libraries" ], "summary": "Show detailed metadata of a library", "description": "Returns metadata for a single library that the current grant can read.", "operationId": "showLibrary", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "responses": { "200": { "description": "Library metadata.", "content": { "application/json": { "schema": { "required": [ "id", "name", "overview", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/LibraryId" }, "name": { "type": "string", "example": "Testdaten" }, "overview": { "type": "string", "example": "Technical AI research and academic administration records paired with corporate brand media and engineering assets.", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] }, "delete": { "tags": [ "Libraries" ], "summary": "Delete a library", "description": "Deletes a library and all of its resources. The workspace-wide `library.delete` ability is sufficient; library read or update access is not required.", "operationId": "deleteLibrary", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "responses": { "204": { "description": "Library deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/directory": { "get": { "tags": [ "Libraries" ], "summary": "List subfolders and files in a library directory", "description": "Lists the immediate children of the given library path. Defaults to the library root `/`. Results are cursor-paginated by `limit` and `cursor`.", "operationId": "listLibraryDirectory", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "path", "in": "query", "description": "Absolute directory path starting with `/`. Defaults to `/`. Path handling is case-sensitive; `.` and `..` segments are not supported; trailing slashes are ignored except for the root.", "required": false, "schema": { "$ref": "#/components/schemas/LibraryPath" } }, { "name": "limit", "in": "query", "description": "Maximum number of items to return per section (e.g. up to limit folders and up to limit files separately). When only one section has more data, its cursor advances first; the merged `next_cursor` resumes from that point on the next request.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor returned in the previous page `next_cursor`. Omit on the first request. The cursor encodes the position across both folders and files; ordering is folders-then-files, each sorted by name ascending.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Directory listing with cursor pagination metadata. `truncated` is true exactly when `next_cursor` is not null.", "content": { "application/json": { "schema": { "required": [ "folders", "files", "limit", "next_cursor", "truncated" ], "properties": { "folders": { "type": "array", "items": { "required": [ "name", "overview", "organization_locked", "is_archive" ], "properties": { "name": { "type": "string", "example": "marketing" }, "overview": { "type": "string", "example": "Brand assets and campaign materials.", "nullable": true }, "organization_locked": { "type": "boolean" }, "is_archive": { "type": "boolean" }, "archive_description": { "type": "string", "nullable": true }, "original_mime_type": { "type": "string", "nullable": true } }, "type": "object" } }, "files": { "type": "array", "items": { "required": [ "id", "title", "slug", "filename", "mime_type", "organization_locked" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string", "example": "Whitebox Retrieval with LlamaIndex" }, "slug": { "description": "URL-friendly slug without file extension.", "type": "string", "example": "whitebox-retrieval-llamaindex" }, "filename": { "description": "Virtual filename (slug with extension) used as a path segment.", "type": "string", "example": "whitebox-retrieval-llamaindex.md" }, "mime_type": { "type": "string", "example": "text/markdown" }, "organization_locked": { "type": "boolean" } }, "type": "object" } }, "limit": { "type": "integer", "example": 100 }, "next_cursor": { "description": "Opaque cursor for the next page, or null when no more pages are available. `truncated` is true exactly when `next_cursor` is not null.", "type": "string", "nullable": true }, "truncated": { "description": "True when more folders or files are available. Equivalent to `next_cursor != null`.", "type": "boolean", "example": false } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] }, "post": { "tags": [ "Libraries" ], "summary": "Create a directory at the given path", "description": "Creates a new directory at the provided absolute path. The caller needs the library `update` ability.", "operationId": "createLibraryDirectory", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDirectoryRequest" } } } }, "responses": { "201": { "description": "Directory created.", "headers": { "Location": { "description": "Relative URL to show the directory contents.", "schema": { "type": "string", "format": "uri-reference", "example": "/v1/libraries/lib_mmlongbenchdoc/directory?path=/marketing/campaigns" } } }, "content": { "application/json": { "schema": { "required": [ "id", "name", "overview", "parent_id", "organization_locked", "is_archive" ], "properties": { "id": { "type": "string", "example": "nod_abc123" }, "name": { "type": "string", "example": "campaigns" }, "overview": { "type": "string", "example": "Campaign materials.", "nullable": true }, "parent_id": { "type": "string", "example": "nod_parent1", "nullable": true }, "organization_locked": { "type": "boolean" }, "is_archive": { "type": "boolean" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/files": { "post": { "tags": [ "Libraries" ], "summary": "Upload a single file to a library inbox", "description": "Uploads a file to the `.inbox` folder of this library. A byte-identical upload of a file that already exists in the library (same content hash and MIME type) does not create a second resource: the existing resource gains an additional location in the folder tree and the response is returned with status 200 and `duplicate: true`. Otherwise a new resource is created and the response is returned with status 201.", "operationId": "uploadLibraryFile", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadLibraryFileRequest" } } } }, "responses": { "201": { "description": "New file uploaded and attached to the library inbox.", "headers": { "Location": { "description": "Absolute URL to download the resource. Requires authentication.", "schema": { "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/resources/res_fqgountdqko3" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedLibraryFile" } } } }, "200": { "description": "The uploaded file already exists in this library; the existing resource gained an additional location and no new resource was created.", "headers": { "Location": { "description": "Absolute URL to download the existing resource. Requires authentication.", "schema": { "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/resources/res_fqgountdqko3" } } }, "content": { "application/json": { "schema": { "required": [ "duplicate" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/UploadedLibraryFile" }, { "properties": { "duplicate": { "description": "Always true on this response: the file was a byte-identical duplicate of an existing resource in this library.", "type": "boolean", "example": true } }, "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/files/{resource}": { "delete": { "tags": [ "Libraries" ], "summary": "Delete a resource from a library", "description": "Permanently deletes the library-owned resource and its derived artifacts.", "operationId": "deleteLibraryFile", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } ], "responses": { "204": { "description": "Resource deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/hints": { "post": { "tags": [ "Libraries" ], "summary": "Submit a hint for agentic review", "description": "Submits a free-text hint for asynchronous, evidence-based review. The caller needs update access to the library. A submitted hint is untrusted input and does not directly change knowledge-base content.", "operationId": "submitLibraryHint", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitLibraryHintRequest" } } } }, "responses": { "201": { "description": "Hint accepted for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HintSubmitResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/nodes:merge": { "post": { "tags": [ "Libraries" ], "summary": "Merge a source directory into a target directory", "description": "Merges the contents of `source` into `target`. Both parameters must be absolute library paths and the caller needs the library `update` ability.", "operationId": "mergeLibraryDirectories", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeDirectoriesRequest" } } } }, "responses": { "200": { "description": "Directories merged successfully.", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Directories merged successfully." } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/nodes:move": { "post": { "tags": [ "Libraries" ], "summary": "Move or rename an item in the library", "description": "Moves the item at `source` to `target`. Both parameters must be absolute library paths and the caller needs the library `update` ability.", "operationId": "moveLibraryItem", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveItemRequest" } } } }, "responses": { "200": { "description": "Item moved successfully.", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Library item moved successfully." } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/nodes": { "get": { "tags": [ "Libraries" ], "summary": "Inspect a library node (file or directory) by path", "description": "Resolves a library path and returns metadata for the corresponding file or directory. Use this endpoint to inspect items by their library path. The response shape depends on the resolved `type`.", "operationId": "showLibraryNode", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "path", "in": "query", "description": "Absolute, case-sensitive library path starting with `/`. Defaults to the library root `/`. Must not contain `.` or `..` segments. A trailing slash is ignored except for the root.", "required": false, "schema": { "$ref": "#/components/schemas/LibraryPath" } } ], "responses": { "200": { "description": "Node metadata. The concrete shape is discriminated by `type`; see the `LibraryNode` oneOf schemas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryNode" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/nodes/{node}:archive": { "post": { "tags": [ "Libraries" ], "summary": "Archive or unarchive a library folder", "description": "Marks a folder as an archive, meaning the folder and all its descendants form one fixed object that represents an original document (for example an E-Mail). When archiving, the archive description and original MIME type may be set in the same request. The caller needs the library `update` ability. Only a user may change an archive.", "operationId": "archiveLibraryNode", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "node", "in": "path", "description": "Opaque library node identifier of the folder.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryNodeId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveNodeRequest" } } } }, "responses": { "200": { "description": "Archive state updated.", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Folder archived." } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/nodes/{node}:lock": { "post": { "tags": [ "Libraries" ], "summary": "Protect or unprotect a library node", "description": "Sets whether a folder or file may be moved, renamed, or deleted. The caller needs the library `update` ability. Only a user may change protection.", "operationId": "lockLibraryNode", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "node", "in": "path", "description": "Opaque library node identifier of the folder.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryNodeId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockNodeRequest" } } } }, "responses": { "200": { "description": "Protection state updated.", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Item protected." } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/resources/{resource}": { "get": { "tags": [ "Libraries" ], "summary": "Show a resource in a library", "description": "Returns metadata for a resource owned by the given library. The caller must have read access to the library.", "operationId": "showLibraryResource", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } ], "responses": { "200": { "description": "Resource metadata. Follows the `LibraryFileNode` schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryFileNode" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/libraries/{library}/tree": { "get": { "tags": [ "Libraries" ], "summary": "Get the recursive tree structure of a library", "description": "Returns the recursive tree starting at `path` up to `max_depth` levels and at most `max_nodes` nodes. When the tree is larger than `max_nodes`, `truncated` is true and additional nodes are not included; callers can fall back to the directory listing endpoint to paginate through the remaining children.", "operationId": "showLibraryTree", "parameters": [ { "name": "library", "in": "path", "description": "Opaque library identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/LibraryId" } }, { "name": "path", "in": "query", "description": "Root path of the subtree to return. Absolute, case-sensitive path starting with `/`. Defaults to `/`. Must not contain `.` or `..` segments; trailing slashes are ignored except for the root.", "required": false, "schema": { "$ref": "#/components/schemas/LibraryPath" } }, { "name": "max_depth", "in": "query", "description": "Maximum depth of nested folders to include. Defaults to 5.", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 20, "minimum": 0 } }, { "name": "max_nodes", "in": "query", "description": "Maximum total number of nodes (folders + files) to return. Defaults to 500.", "required": false, "schema": { "type": "integer", "default": 500, "maximum": 1000, "minimum": 1 } } ], "responses": { "200": { "description": "Recursive library tree rooted at the requested path. `truncated` is true when the tree was cut at `max_nodes`; callers can fall back to the directory listing endpoint to paginate through the remaining children.", "content": { "application/json": { "schema": { "required": [ "type", "name", "overview", "organization_locked", "is_archive", "children", "truncated", "max_depth", "max_nodes" ], "properties": { "type": { "type": "string", "enum": [ "directory" ] }, "name": { "type": "string", "example": "/" }, "overview": { "type": "string", "nullable": true }, "organization_locked": { "type": "boolean" }, "is_archive": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryTreeNode" } }, "truncated": { "description": "True when the tree was cut at `max_nodes`. Indicates that more nodes exist beyond the returned subtree.", "type": "boolean", "example": false }, "max_depth": { "type": "integer", "example": 5 }, "max_nodes": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/mcp/uploads/{upload}": { "post": { "tags": [ "Libraries" ], "summary": "Complete a short-lived MCP file upload", "description": "Uploads the file through the signed, single-use capability URL returned by create_library_file_upload. This endpoint does not accept a bearer token; the signature and bound upload session authorize the request.", "operationId": "completeMcpLibraryFileUpload", "parameters": [ { "name": "upload", "in": "path", "description": "Opaque upload-session identifier embedded in the signed capability URL.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadLibraryFileRequest" } } } }, "responses": { "201": { "description": "File uploaded and attached to the library inbox." }, "200": { "description": "The uploaded file already exists in this library; the existing resource gained an additional location and the payload carries `duplicate: true`." }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "description": "The upload session has expired or was already consumed." }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/search/nodes": { "get": { "tags": [ "Search" ], "summary": "Search library nodes across libraries", "description": "Searches folders and archives of the library navigation trees with hybrid lexical and semantic retrieval. Each hit returns the node's path and overview, so it locates where information lives rather than the matching document content itself; use the resource search for content-level hits. Folders match through their own and their direct children's names and overviews; archives also match through their description and original MIME type. Omit library_ids to search every accessible library. Omit strategy to use balanced lexical and semantic retrieval.", "operationId": "searchNodes", "parameters": [ { "name": "query", "in": "query", "description": "Natural-language search query.", "required": true, "schema": { "type": "string", "example": "bank correspondence", "maxLength": 2000, "minLength": 1 } }, { "name": "strategy", "in": "query", "description": "Usually omit this parameter. Balanced is the recommended default; lexical can be faster for exact folder names, while semantic deliberately focuses conceptual similarity.", "required": false, "schema": { "type": "string", "default": "balanced", "enum": [ "balanced", "lexical", "semantic" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 100, "minimum": 1 } }, { "name": "library_ids[]", "in": "query", "description": "Optional readable library IDs. Omit to search every accessible library. Repeat the bracketed query parameter for multiple IDs.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryId" }, "maxItems": 25, "uniqueItems": true } } ], "responses": { "200": { "description": "Search results. When no nodes match, `results` is an empty array.", "content": { "application/json": { "schema": { "required": [ "notice", "results", "count", "strategy" ], "properties": { "notice": { "type": "string", "example": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NodeSearchResult" } }, "count": { "type": "integer", "example": 1 }, "strategy": { "type": "string", "example": "balanced", "enum": [ "balanced", "lexical", "semantic" ] } }, "type": "object" }, "examples": { "empty": { "summary": "Empty search", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [], "count": 0, "strategy": "balanced" } }, "hit": { "summary": "Search with a folder hit", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [ { "node": { "id": "nod_qv0z1x9c2b3a", "library": { "id": "lib_s50vofoljazr", "name": "Examples" }, "type": "folder", "path": "/finances/bank", "name": "bank", "overview": "Statements and correspondence with the bank." } } ], "count": 1, "strategy": "balanced" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/notes/{note}": { "get": { "tags": [ "Search" ], "summary": "Get a single note by ID", "description": "Returns a note directly by its ID, e.g. from an earlier `search_notes` or knowledge-graph result, without searching again. Notes are read-only from the API; they are created, revised, and removed only by the agentic refinement process behind hint submissions.", "operationId": "showNote", "parameters": [ { "name": "note", "in": "path", "description": "Opaque note identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/NoteId" } } ], "responses": { "200": { "description": "Note metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteGetResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/search/notes": { "get": { "tags": [ "Search" ], "summary": "Search notes across libraries", "description": "Searches the knowledge graph of curated notes distilled from resources. Use it first for identity, people, relationships, contradictions, or durable additional context. Notes are read-only from the API; they are created, revised, and removed only by the agentic refinement process behind hint submissions. Omit library_ids to search every accessible library. Omit strategy to use balanced lexical and semantic retrieval.", "operationId": "searchNotes", "parameters": [ { "name": "query", "in": "query", "description": "Natural-language search query.", "required": true, "schema": { "type": "string", "example": "camper wiring amperage", "maxLength": 2000, "minLength": 1 } }, { "name": "strategy", "in": "query", "description": "Usually omit this parameter. Balanced is the recommended default; lexical can be faster for exact terms, while semantic deliberately focuses conceptual similarity.", "required": false, "schema": { "type": "string", "default": "balanced", "enum": [ "balanced", "lexical", "semantic" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 100, "minimum": 1 } }, { "name": "library_ids[]", "in": "query", "description": "Optional readable library IDs. Omit to search every accessible library. Repeat the bracketed query parameter for multiple IDs.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryId" }, "maxItems": 25, "uniqueItems": true } }, { "name": "resource_ids[]", "in": "query", "description": "Optional accessible resource IDs. Narrows results to notes that reference at least one of these resources. Repeat the bracketed query parameter for multiple IDs.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceId" }, "maxItems": 25, "uniqueItems": true } } ], "responses": { "200": { "description": "Search results. When no notes match, `results` is an empty array.", "content": { "application/json": { "schema": { "required": [ "notice", "results", "count", "strategy" ], "properties": { "notice": { "type": "string", "example": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NoteSearchResult" } }, "count": { "type": "integer", "example": 1 }, "strategy": { "type": "string", "example": "balanced", "enum": [ "balanced", "lexical", "semantic" ] } }, "type": "object" }, "examples": { "empty": { "summary": "Empty search", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [], "count": 0, "strategy": "balanced" } }, "hit": { "summary": "Search with a note hit", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [ { "note": { "id": "nte_qv0z1x9c2b3a", "library": { "id": "lib_s50vofoljazr", "name": "Examples" }, "type": "fact", "markdown": "The camper wiring standard uses a 12V circuit rated for 30A. `res_mrhwii851gvk#page=12`", "resource_ids": [ "res_mrhwii851gvk" ] } } ], "count": 1, "strategy": "balanced" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}": { "get": { "tags": [ "Resources" ], "summary": "Download the original source file of a resource", "description": "Streams the original uploaded file. The request may use an API-enabled bearer credential or a short-lived signed URL obtained from `POST /v1/resources/{resource}/view-urls`.", "operationId": "downloadResource", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "signature", "in": "query", "description": "HMAC signature from a view-url response. When present, no bearer token is required.", "required": false, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "description": "Unix expiry timestamp from a view-url response.", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Tenant ID encoded in a signed view URL.", "required": false, "schema": { "type": "integer" } }, { "name": "disposition", "in": "query", "description": "Content-Disposition behavior. When the URL was signed with a `disposition` value, this parameter must match the signed value; a different value invalidates the signature. For bearer-token requests the value is applied directly.", "required": false, "schema": { "type": "string", "default": "attachment", "enum": [ "inline", "attachment" ] } } ], "responses": { "200": { "description": "Original source file as a binary stream. The `Content-Type` is the resource's actual MIME type.", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"camper-wiring.pdf\"" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/resources/{resource}/pages/{page_number}": { "get": { "tags": [ "Resources" ], "summary": "Download a rendered PDF page as a PNG image", "description": "Streams the rendered preview image of a single page for PDF resources. Accepts either a bearer token or a signed URL. Without a bearer token, `signature`, `expires`, and `tenant_id` must all be present and valid; partial signed-URL credentials are rejected with 401. The signature is bound to the HTTP method, path, resource id, page number, tenant id, expiry, and (when present) `disposition`. The response uses the asset's actual MIME type.", "operationId": "downloadResourcePage", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "page_number", "in": "path", "description": "1-indexed page number.", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "signature", "in": "query", "description": "HMAC signature from a view-url response.", "required": false, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "description": "Unix expiry timestamp from a view-url response.", "required": false, "schema": { "type": "integer" } }, { "name": "tenant_id", "in": "query", "description": "Tenant ID encoded in a signed view URL.", "required": false, "schema": { "type": "integer" } }, { "name": "disposition", "in": "query", "description": "Content-Disposition behavior. When the URL was signed with a `disposition` value, this parameter must match the signed value.", "required": false, "schema": { "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } } ], "responses": { "200": { "description": "Rendered page image as a binary stream. The `Content-Type` is the asset's actual MIME type (typically `image/png`).", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "inline; filename=\"camper-wiring-page-1.png\"" } } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/resources/{resource}/pages/{page_number}/representations/region": { "get": { "tags": [ "Resources" ], "summary": "Download an exact normalized region of a rendered page", "operationId": "downloadResourcePageRegion", "parameters": [ { "name": "resource", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "page_number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "bbox[]", "in": "query", "description": "Normalized [left, top, right, bottom] coordinates. Repeat the bracketed query parameter in that order.", "required": true, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "number", "maximum": 1, "minimum": 0 }, "maxItems": 4, "minItems": 4 } } ], "responses": { "200": { "description": "Exact page-region PNG.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] }, {} ] } }, "/v1/resources/{resource}/view-urls": { "post": { "tags": [ "Resources" ], "summary": "Issue a short-lived public URL for accessing a resource", "description": "Returns a signed URL that grants unauthenticated access to `GET /v1/resources/{resource}` for the configured lifetime. The `disposition` value, if provided, is included in the signed URL and applied as `Content-Disposition` on download; changing it afterwards invalidates the signature. When `disposition` is omitted, the download defaults to `attachment` and is explicitly signed.", "operationId": "issueResourceViewUrl", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "ttl_minutes": { "type": "integer", "default": 15, "maximum": 60, "minimum": 1 }, "disposition": { "description": "Content-Disposition to apply on download. When omitted, the download defaults to `attachment` and is explicitly signed. The value is signed; changing it afterwards invalidates the URL.", "type": "string", "enum": [ "inline", "attachment" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Signed view URL.", "content": { "application/json": { "schema": { "required": [ "url", "expires_in_minutes" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/resources/res_fqgountdqko3?signature=...&expires=...&tenant_id=1" }, "expires_in_minutes": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}/knowledge-graph": { "get": { "tags": [ "Resources" ], "summary": "Show the notes and related resources in a resource's knowledge graph", "description": "Returns the notes (`nte_...`) that reference this resource, and other resources that are related because they are referenced together with this resource in at least one shared note. Notes are read-only from the API; they are created, revised, and removed only by the agentic refinement process behind hint submissions.", "operationId": "showResourceKnowledgeGraph", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } ], "responses": { "200": { "description": "The resource's knowledge graph. Both arrays are empty when the resource is not referenced by any note.", "content": { "application/json": { "schema": { "required": [ "notes", "related_resources" ], "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/NoteSearchResult" } }, "related_resources": { "type": "array", "items": { "required": [ "id", "title" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "examples": { "empty": { "summary": "No knowledge graph yet", "value": { "notes": [], "related_resources": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}/pages/{page_number}/view-urls": { "post": { "tags": [ "Resources" ], "summary": "Issue a short-lived public URL for accessing a rendered PDF page", "description": "Returns a signed URL that grants unauthenticated access to `GET /v1/resources/{resource}/pages/{page_number}`. The `disposition` value, if provided, is included in the signed URL and applied as `Content-Disposition` on download; changing it afterwards invalidates the signature. When `disposition` is omitted, the download defaults to `inline` and is explicitly signed.", "operationId": "issueResourcePageViewUrl", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "page_number", "in": "path", "description": "1-indexed page number.", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "ttl_minutes": { "type": "integer", "default": 15, "maximum": 60, "minimum": 1 }, "disposition": { "description": "Content-Disposition to apply on download. When omitted, the download defaults to `inline` and is explicitly signed. The value is signed; changing it afterwards invalidates the URL.", "type": "string", "enum": [ "inline", "attachment" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Signed view URL.", "content": { "application/json": { "schema": { "required": [ "url", "expires_in_minutes" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_in_minutes": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}/pages/{page_number}/representations/region/view-urls": { "post": { "tags": [ "Resources" ], "summary": "Issue a short-lived signed URL for an exact page region", "operationId": "issueResourcePageRegionViewUrl", "parameters": [ { "name": "resource", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "page_number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "bbox" ], "properties": { "bbox": { "type": "array", "items": { "type": "number", "maximum": 1, "minimum": 0 }, "maxItems": 4, "minItems": 4 }, "ttl_minutes": { "type": "integer", "maximum": 60, "minimum": 1 }, "disposition": { "type": "string", "enum": [ "inline", "attachment" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Signed page-region URL." }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}/questions": { "post": { "tags": [ "Resources" ], "summary": "Start an asynchronous high-recall scan of one resource", "description": "Starts an expensive asynchronous scan of every locatable processed and enriched unit in one known resource or scope. Use it for simple but laborious questions only when the complete result can reasonably fit in about 500 words, such as collecting mentioned entities or summarizing distributed evidence. The result identifies only the scanned resource or scope; investigate primary content separately for precise citations. Returns a request_id and poll_after_seconds; do not poll before that delay has elapsed. Repeated identical requests reuse the existing run instead of starting a new scan. acknowledge_cost must be true.", "operationId": "startResourceQuestion", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueResourceQuestionRequest" } } } }, "responses": { "202": { "description": "The scan was accepted (or an identical in-flight run was reused). The `Location` header points to the canonical poll URL.", "headers": { "Location": { "schema": { "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/resources/res_example/questions/rqa_abc123" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceQuestionStartResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/resources/{resource}/questions/{run}": { "get": { "tags": [ "Resources" ], "summary": "Poll an asynchronous resource scan for its status and answer", "description": "Polls an ask_resource request for its compact answer. Never call this endpoint again before the returned poll_after_seconds delay has elapsed. A completed request has submitted every locatable processed unit in the selected resource scope to analysis, but model extraction can still miss information. source_reference identifies only the scanned resource or scope, not a verified location for each claim; inspect primary content before resolving precise citations. Returns 202 Accepted while the run is still queued or running, and 200 OK once it reaches a terminal status (completed, completed_with_gaps, failed, or cancelled). The body always carries the `status` field.", "operationId": "getResourceQuestion", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "run", "in": "path", "description": "Opaque resource question run identifier returned by the start endpoint. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceQuestionRunId" } }, { "name": "cursor", "in": "query", "description": "Opaque findings continuation cursor. Omit for the first fixed-size page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run reached a terminal status. The body carries the final answer, coverage, and any error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceQuestionAnswerResponse" } } } }, "202": { "description": "The run is still queued or running. The body carries progress information; poll again after poll_after_seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceQuestionAnswerResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] }, "delete": { "tags": [ "Resources" ], "summary": "Cancel a queued or running resource scan", "description": "Cancels a queued or running ask_resource request. Cancellation is idempotent and prevents pending work or late model results from being used. A provider request already in flight may continue until its hard timeout. Cancelling an already-terminal run returns cancelled: false; cancelling an already-cancelled run returns cancelled: true.", "operationId": "cancelResourceQuestion", "parameters": [ { "name": "resource", "in": "path", "description": "Opaque resource identifier. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, { "name": "run", "in": "path", "description": "Opaque resource question run identifier returned by the start endpoint. Clients must not parse or construct this value.", "required": true, "schema": { "$ref": "#/components/schemas/ResourceQuestionRunId" } } ], "responses": { "200": { "description": "The cancellation request was processed. `cancelled` is true when the run was cancelled by this call (or was already cancelled), and false when the run had already reached a different terminal status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceQuestionCancelResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/v1/search/resources": { "get": { "tags": [ "Search" ], "summary": "Search resources across libraries", "description": "Performs a scoped search and returns ranked candidates, not verified matches. A high rank or single result does not confirm relevance, identity, or the query premise. Named identities require explicit evidence and cannot be established from visual resemblance alone. Each result includes its library and canonical library-relative path. These fields describe origin and organization only; co-retrieval or proximity does not establish identity or a relationship. Omit strategy to use balanced retrieval over all enriched content, including OCR, transcripts, and descriptions. Use visual_enhanced deliberately when relevant visual details may not have been captured during enrichment.", "operationId": "searchResources", "parameters": [ { "name": "query", "in": "query", "description": "Natural-language search query.", "required": true, "schema": { "type": "string", "example": "camper wiring diagram", "maxLength": 2000, "minLength": 1 } }, { "name": "strategy", "in": "query", "description": "Usually omit this parameter. Balanced combines lexical and semantic retrieval across enriched multimodal content. Visual enhanced adds slower direct visual matching; lexical, semantic, and visual deliberately isolate one signal.", "required": false, "schema": { "type": "string", "default": "balanced", "enum": [ "balanced", "visual_enhanced", "lexical", "semantic", "visual" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 100, "minimum": 1 } }, { "name": "library_ids[]", "in": "query", "description": "Optional readable library IDs. Omit to search every accessible library; do not infer a narrower scope from one result. Repeat the bracketed query parameter for multiple IDs.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryId" }, "maxItems": 25, "uniqueItems": true } }, { "name": "resource_ids[]", "in": "query", "description": "Optional accessible resource IDs. Repeat the bracketed query parameter for multiple IDs.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceId" }, "maxItems": 25, "uniqueItems": true } }, { "name": "output_format", "in": "query", "description": "\"detailed\" (default) returns title, abstract, and relevant assets. \"compact\" omits abstract and assets, returning only id, library, path, mime_type, title, and overview for lightweight discovery.", "required": false, "schema": { "type": "string", "default": "detailed", "enum": [ "detailed", "compact" ] } } ], "responses": { "200": { "description": "Search results. When no resources match, `results` is an empty array.", "content": { "application/json": { "schema": { "required": [ "notice", "results", "count", "strategy" ], "properties": { "notice": { "type": "string", "example": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "count": { "type": "integer", "example": 1 }, "strategy": { "type": "string", "example": "balanced", "enum": [ "balanced", "visual_enhanced", "lexical", "semantic", "visual" ] } }, "type": "object" }, "examples": { "empty": { "summary": "Empty search", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [], "count": 0, "strategy": "balanced" } }, "hit": { "summary": "Search with a resource hit", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [ { "resource": { "id": "res_fqgountdqko3", "library": { "id": "lib_s50vofoljazr", "name": "Examples" }, "paths": [ "/research/camper-wiring.pdf" ], "mime_type": "application/pdf", "title": "Camper wiring", "abstract": "A brief technical description of the camper wiring standard.", "assets": [ { "id": "ast_abc123xyz789", "type": "text", "asset_index": 0, "markdown": "Relevant excerpt...", "trace": [ "res_fqgountdqko3#page=12&bbox=0.1,0.2,0.3,0.4" ] } ] } } ], "count": 1, "strategy": "balanced" } }, "compact": { "summary": "Compact search (output_format=compact)", "value": { "notice": "Search results are ranked candidates, not verified matches. Relevance, identity, and the query premise must be confirmed from explicit evidence.", "results": [ { "resource": { "id": "res_fqgountdqko3", "library": { "id": "lib_s50vofoljazr", "name": "Examples" }, "paths": [ "/research/camper-wiring.pdf" ], "mime_type": "application/pdf", "title": "Camper wiring", "overview": "Technical wiring documentation for campers." } } ], "count": 1, "strategy": "balanced" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "accessToken": [] }, { "oauth": [ "api:use" ] } ] } }, "/health/live": { "get": { "tags": [ "Health" ], "summary": "Process liveness probe", "description": "Returns 200 as soon as the PHP process can handle requests. Use this for Kubernetes liveness probes; no external dependencies are checked. Also reports the deployed platform version, which every service in a release shares; this is not the API version.", "operationId": "liveCheck", "responses": { "200": { "description": "Process is alive.", "content": { "application/json": { "schema": { "required": [ "status", "version" ], "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "0.1.0" } }, "type": "object" } } } } }, "security": [] } }, "/health/ready": { "get": { "tags": [ "Health" ], "summary": "Readiness probe including infrastructure dependencies", "description": "Checks database, cache (Redis), and queue (Horizon) connectivity. Returns 200 only when all required dependencies are reachable; otherwise 503 with a `checks` object describing each failing dependency.", "operationId": "readyCheck", "responses": { "200": { "description": "All dependencies are reachable.", "content": { "application/json": { "schema": { "required": [ "status", "checks" ], "properties": { "status": { "type": "string", "example": "ok" }, "checks": { "required": [ "database", "cache", "queue" ], "properties": { "database": { "type": "string", "example": "ok" }, "cache": { "type": "string", "example": "ok" }, "queue": { "type": "string", "example": "ok" } }, "type": "object" } }, "type": "object" } } } }, "503": { "description": "At least one dependency is unavailable.", "content": { "application/json": { "schema": { "required": [ "status", "checks" ], "properties": { "status": { "type": "string", "example": "unavailable" }, "checks": { "required": [ "database", "cache", "queue" ], "properties": { "database": { "type": "string", "example": "ok" }, "cache": { "type": "string", "example": "failed" }, "queue": { "type": "string", "example": "ok" } }, "type": "object" } }, "type": "object" } } } } }, "security": [] } } }, "components": { "schemas": { "CreateLibraryRequest": { "description": "Body for creating a new library in the authenticated tenant.", "required": [ "name" ], "properties": { "name": { "description": "Human-readable library name.", "type": "string", "example": "Technical Documentation", "maxLength": 255, "minLength": 1 }, "overview": { "description": "Optional short description of the library purpose.", "type": "string", "example": "Product manuals, RFCs, and engineering specifications.", "nullable": true, "maxLength": 2000 } }, "type": "object" }, "LibraryFileNode": { "description": "A file node in a library. The `download_url` requires a bearer token or a signed URL obtained from the `view-urls` endpoints.", "required": [ "type", "id", "title", "abstract", "overview", "mime_type", "hash", "organization_locked", "download_url", "ingestion_status" ], "properties": { "type": { "type": "string", "enum": [ "file" ] }, "id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string", "example": "Whitebox Retrieval with LlamaIndex" }, "slug": { "description": "URL-friendly slug without file extension. Present when the file has exactly one location in the library tree, or when the node was addressed by path (then the slug of the requested path).", "type": "string", "example": "whitebox-retrieval-llamaindex", "nullable": true }, "abstract": { "type": "string", "nullable": true }, "overview": { "type": "string", "nullable": true }, "mime_type": { "type": "string", "example": "text/markdown" }, "hash": { "oneOf": [ { "$ref": "#/components/schemas/ResourceHash" }, { "type": "object", "nullable": true, "enum": [ null ] } ], "description": "Content hash of the original file. Multiple resources may have identical hashes." }, "organization_locked": { "description": "Whether this file may be moved, renamed, or deleted by users or the librarian.", "type": "boolean" }, "archive": { "description": "Containing archive, when this file is part of one.", "type": "object", "nullable": true }, "download_url": { "description": "Absolute URL to download the original file via `GET /v1/resources/{resource}`. Requires a bearer token or a signed URL.", "type": "string", "format": "uri", "example": "https://tkp.example/api/v1/resources/res_fqgountdqko3" }, "ingestion_status": { "$ref": "#/components/schemas/IngestionStatus" } }, "type": "object" }, "LibraryDirectoryNode": { "required": [ "type", "id", "name", "overview", "parent_id", "organization_locked", "is_archive" ], "properties": { "type": { "type": "string", "enum": [ "directory" ] }, "id": { "oneOf": [ { "$ref": "#/components/schemas/LibraryNodeId" }, { "type": "object", "nullable": true, "enum": [ null ] } ], "example": "nod_abc123" }, "name": { "type": "string", "example": "marketing" }, "overview": { "type": "string", "nullable": true }, "parent_id": { "oneOf": [ { "$ref": "#/components/schemas/LibraryNodeId" }, { "type": "object", "nullable": true, "enum": [ null ] } ] }, "organization_locked": { "type": "boolean" }, "is_archive": { "type": "boolean" }, "archive_description": { "type": "string", "nullable": true }, "original_mime_type": { "type": "string", "nullable": true } }, "type": "object" }, "LibraryNode": { "description": "A library node is either a file or a directory. The `type` field discriminates the concrete shape.", "discriminator": { "propertyName": "type", "mapping": { "file": "#/components/schemas/LibraryFileNode", "directory": "#/components/schemas/LibraryDirectoryNode" } }, "oneOf": [ { "$ref": "#/components/schemas/LibraryFileNode" }, { "$ref": "#/components/schemas/LibraryDirectoryNode" } ] }, "LibraryTreeFile": { "required": [ "type", "name", "title", "id", "mime_type", "organization_locked" ], "properties": { "type": { "type": "string", "enum": [ "file" ] }, "name": { "type": "string", "example": "whitebox-retrieval-llamaindex.md" }, "title": { "type": "string", "example": "Whitebox Retrieval with LlamaIndex" }, "id": { "$ref": "#/components/schemas/ResourceId" }, "mime_type": { "type": "string", "example": "text/markdown" }, "organization_locked": { "type": "boolean" } }, "type": "object" }, "LibraryTreeDirectory": { "required": [ "type", "name", "overview", "organization_locked", "is_archive", "children" ], "properties": { "type": { "type": "string", "enum": [ "directory" ] }, "name": { "type": "string", "example": "marketing" }, "overview": { "type": "string", "nullable": true }, "organization_locked": { "type": "boolean" }, "is_archive": { "type": "boolean" }, "archive_description": { "type": "string", "nullable": true }, "original_mime_type": { "type": "string", "nullable": true }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryTreeNode" } } }, "type": "object" }, "LibraryTreeNode": { "description": "A node in the recursive library tree structure.", "discriminator": { "propertyName": "type", "mapping": { "directory": "#/components/schemas/LibraryTreeDirectory", "file": "#/components/schemas/LibraryTreeFile" } }, "oneOf": [ { "$ref": "#/components/schemas/LibraryTreeDirectory" }, { "$ref": "#/components/schemas/LibraryTreeFile" } ] }, "LibraryId": { "description": "Opaque library identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^lib_[A-Za-z0-9_]+$", "example": "lib_s50vofoljazr" }, "ResourceId": { "description": "Opaque resource identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^res_[A-Za-z0-9_]+$", "example": "res_fqgountdqko3" }, "AssetId": { "description": "Opaque asset identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^ast_[A-Za-z0-9_]+$", "example": "ast_abc123xyz789" }, "NoteId": { "description": "Opaque note identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^nte_[A-Za-z0-9_]+$", "example": "nte_qv0z1x9c2b3a" }, "HintId": { "description": "Opaque hint identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^hnt_[A-Za-z0-9_]+$", "example": "hnt_pxr8k1v2m0zq" }, "LibraryNodeId": { "description": "Opaque library node (directory) identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^nod_[A-Za-z0-9_]+$" }, "ResourceHash": { "description": "Lowercase hexadecimal SHA-256 digest of the original file.", "type": "string", "pattern": "^[a-f0-9]{64}$" }, "LibraryPath": { "description": "Absolute, case-sensitive library path. Must start with `/`. Must not contain `.` or `..` segments. A trailing slash is ignored. Additional path constraints are validated server-side and are not fully expressible by this schema pattern.", "type": "string", "pattern": "^/", "maxLength": 2048, "minLength": 1 }, "LibraryReference": { "description": "Compact library origin included in knowledge search results.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/LibraryId" }, "name": { "type": "string", "example": "Examples" } }, "type": "object" }, "IngestionStatus": { "description": "Current ingestion lifecycle state. Poll while `not_started` or `running`. `completed`, `completed_with_warnings`, `partial`, and `failed` are terminal. `completed` and `completed_with_warnings` both mean the resource is published for search; `completed_with_warnings` additionally signals that some enrichment steps degraded to fallback output, so parts of the resource are indexed with reduced quality.", "type": "string", "enum": [ "not_started", "partial", "running", "failed", "completed_with_warnings", "completed" ] }, "LibraryAbility": { "description": "An independent ability granted for this library. Abilities do not imply one another.", "type": "string", "enum": [ "read", "resource.create", "update", "resource.delete" ] }, "LibrarySummary": { "description": "Library summary as returned by `/v1/auth/check` and `/v1/libraries`. The same shape is used in both endpoints to keep them consistent.", "required": [ "id", "name", "overview", "access" ], "properties": { "id": { "$ref": "#/components/schemas/LibraryId" }, "name": { "type": "string", "example": "MMLongBench-Doc" }, "overview": { "type": "string", "example": "A collection of long documents for benchmarking.", "nullable": true }, "access": { "description": "Effective abilities for this library after intersecting user, grant, and requested scope.", "type": "array", "items": { "$ref": "#/components/schemas/LibraryAbility" }, "example": [ "read", "resource.create" ] } }, "type": "object" }, "UploadedLibraryFile": { "description": "Metadata of an uploaded library file. The shape mirrors `Resource::toUploadMetadata()`. On a duplicate upload the slug describes the additional inbox location of the existing resource.", "required": [ "id", "title", "slug", "mime_type", "hash", "organization_locked", "ingestion_status" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string", "example": "Whitebox Retrieval with LlamaIndex", "nullable": true }, "slug": { "description": "URL-friendly slug of the inbox location, without file extension.", "type": "string", "example": "whitebox-retrieval-llamaindex" }, "mime_type": { "type": "string", "example": "text/markdown" }, "hash": { "$ref": "#/components/schemas/ResourceHash" }, "overview": { "type": "string", "nullable": true }, "abstract": { "type": "string", "nullable": true }, "organization_locked": { "type": "boolean", "example": false }, "archive": { "description": "Containing archive, when the inbox location is part of one.", "type": "object", "nullable": true }, "ingestion_status": { "$ref": "#/components/schemas/IngestionStatus" }, "duplicate": { "description": "True when the upload was byte-identical to an existing resource in this library and only attached a new location. Present only on duplicate responses.", "type": "boolean", "example": true } }, "type": "object" }, "SearchResultAsset": { "description": "A single asset hit within a search result. The shape mirrors `Resource::toSearchResult()`.", "required": [ "id", "type", "asset_index", "markdown" ], "properties": { "id": { "$ref": "#/components/schemas/AssetId" }, "type": { "type": "string", "example": "text", "enum": [ "text", "table", "image", "audio", "video" ] }, "asset_index": { "type": "integer", "example": 0, "minimum": 0 }, "markdown": { "type": "string", "example": "Relevant excerpt..." }, "trace": { "description": "One or more citation fragments resolving this excerpt to human-inspectable locations in the resource. Each entry is `#page={n}&bbox={left},{top},{right},{bottom}` (bounding box normalized 0-1) for paginated content, `#frame={timestamp}` for one exact video frame, `#t={start},{end}` (seconds, positive duration) for audio/video intervals, or `#line={start}-{end}` for verbatim text/markdown. More than one entry means the excerpt is backed by multiple locations.", "type": "array", "items": { "type": "string", "example": "res_mrhwii851gvk#page=12&bbox=0.1,0.2,0.3,0.4" }, "nullable": true } }, "type": "object" }, "SearchResult": { "description": "A single resource search hit. The shape mirrors `Resource::toSearchResult()`. The `output_format` request parameter selects between `detailed` (title, abstract, assets) and `compact` (title, overview, no assets). Scores and strategy are reserved for future extensions; clients must tolerate their absence until they are introduced.", "required": [ "resource" ], "properties": { "resource": { "required": [ "id", "library", "paths", "mime_type", "title" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "library": { "$ref": "#/components/schemas/LibraryReference" }, "paths": { "description": "All absolute paths of this resource inside the returned library, including the virtual filename. A resource may stand at more than one location. This is not a storage path.", "type": "array", "items": { "$ref": "#/components/schemas/LibraryPath" }, "example": [ "/research/camper-wiring.pdf" ] }, "mime_type": { "type": "string", "example": "application/pdf" }, "title": { "type": "string", "example": "Camper wiring" }, "overview": { "description": "Present only with output_format=compact.", "type": "string", "example": "Technical wiring documentation for campers.", "nullable": true }, "abstract": { "description": "Present only with output_format=detailed.", "type": "string", "example": "A brief technical description of the camper wiring standard.", "nullable": true }, "archives": { "description": "Containing archives of the paths above, when any path is part of an archive. Present only when at least one location is archived.", "type": "array", "items": { "type": "object" } }, "assets": { "description": "Present only with output_format=detailed.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultAsset" } } }, "type": "object" } }, "type": "object" }, "NoteSearchResult": { "description": "A single note search hit. The shape mirrors `Note::toSearchResult()`.", "required": [ "note" ], "properties": { "note": { "required": [ "id", "library", "type", "markdown", "resource_ids" ], "properties": { "id": { "$ref": "#/components/schemas/NoteId" }, "library": { "$ref": "#/components/schemas/LibraryReference" }, "type": { "type": "string", "example": "fact", "enum": [ "fact", "assumption", "addendum" ] }, "markdown": { "type": "string", "example": "The camper wiring standard uses a 12V circuit rated for 30A. `res_mrhwii851gvk#page=12`" }, "resource_ids": { "description": "Resources referenced by this note, extracted from its inline resource references.", "type": "array", "items": { "$ref": "#/components/schemas/ResourceId" } } }, "type": "object" } }, "type": "object" }, "NodeSearchResult": { "description": "A single library node search hit. The shape mirrors `LibraryNode::toSearchResult()`.", "required": [ "node" ], "properties": { "node": { "required": [ "id", "library", "type", "path", "name", "overview" ], "properties": { "id": { "$ref": "#/components/schemas/LibraryNodeId" }, "library": { "$ref": "#/components/schemas/LibraryReference" }, "type": { "type": "string", "example": "folder", "enum": [ "folder", "archive" ] }, "path": { "$ref": "#/components/schemas/LibraryPath" }, "name": { "type": "string", "example": "bank" }, "overview": { "type": "string", "example": "Statements and correspondence with the bank.", "nullable": true }, "archive_description": { "description": "Present only for archive hits.", "type": "string", "example": "A scanned letter with its attachments.", "nullable": true }, "original_mime_type": { "description": "Present only for archive hits.", "type": "string", "example": "message/rfc822", "nullable": true } }, "type": "object" } }, "type": "object" }, "NoteGetResult": { "description": "A single note fetched directly by ID. The shape mirrors `Note::toGetResult()`. Notes are read-only from the API; they are created, revised, and removed only by the agentic refinement process behind hint submissions.", "required": [ "id", "type", "markdown", "library_id", "resource_ids", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/NoteId" }, "type": { "type": "string", "example": "fact", "enum": [ "fact", "assumption", "addendum" ] }, "markdown": { "type": "string", "example": "The camper wiring standard uses a 12V circuit rated for 30A. `res_mrhwii851gvk#page=12`" }, "library_id": { "$ref": "#/components/schemas/LibraryId" }, "resource_ids": { "description": "Resources referenced by this note, extracted from its inline resource references.", "type": "array", "items": { "$ref": "#/components/schemas/ResourceId" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "HintSubmitResult": { "description": "Confirmation that a hint was accepted for agentic review. The hint itself is not immediately visible from the API; it is picked up asynchronously by the library's agentic review process.", "required": [ "id", "status", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/HintId" }, "status": { "type": "string", "example": "submitted", "enum": [ "submitted", "accepted", "rejected", "processed", "failed" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Problem": { "description": "RFC 9457 Problem Details error response. All API operation errors except health-probe responses use this shape and the `application/problem+json` media type.", "required": [ "type", "title", "status" ], "properties": { "type": { "description": "A URI identifying the problem type.", "type": "string", "format": "uri", "example": "https://tkp.example/problems/validation-error" }, "title": { "description": "Short human-readable summary of the problem type.", "type": "string", "example": "Validation Error" }, "status": { "description": "HTTP status code.", "type": "integer", "example": 422 }, "detail": { "description": "Human-readable explanation specific to this occurrence.", "type": "string", "example": "The given data was invalid.", "nullable": true }, "instance": { "description": "Request path identifying the occurrence. Query parameters are intentionally omitted so signed capabilities and other sensitive values are never reflected.", "type": "string", "example": "/api/v1/libraries", "nullable": true }, "code": { "description": "Optional stable error code for client-side handling.", "type": "string", "example": "RESEARCH_EXECUTION_FAILED", "nullable": true }, "trace_id": { "description": "Optional correlation id for tracing across services.", "type": "string", "example": "01HQXYZ...", "nullable": true }, "errors": { "description": "Validation field errors (only present for validation errors). Keys are field names; values are arrays of error messages.", "type": "object", "example": { "question": [ "The question field is required." ] }, "nullable": true, "additionalProperties": true } }, "type": "object" }, "ResourceQuestionRunId": { "description": "Opaque resource question run identifier. Clients must not parse or construct this value.", "type": "string", "pattern": "^rqa_[A-Za-z0-9_]+$", "example": "rqa_abc123xyz789" }, "ResourceQuestionStartResponse": { "description": "Acknowledgement that an asynchronous resource scan was started or reused. The shape mirrors the ask_resource MCP tool output. Poll the Location URL (or GET /v1/resources/{resource}/questions/{run}) after poll_after_seconds.", "required": [ "request_id", "status", "resource_id", "scope_reference", "reused", "poll_after_seconds", "elapsed_seconds", "cost_notice" ], "properties": { "request_id": { "$ref": "#/components/schemas/ResourceQuestionRunId" }, "status": { "type": "string", "example": "queued", "enum": [ "queued", "running", "completed", "completed_with_gaps" ] }, "resource_id": { "$ref": "#/components/schemas/ResourceId" }, "scope_reference": { "type": "string", "example": "#page=2-3", "nullable": true }, "reused": { "description": "True when an identical in-flight run was reused instead of starting a new scan.", "type": "boolean", "example": false }, "poll_after_seconds": { "description": "Minimum delay before polling; null when the reused request is already terminal.", "type": "integer", "example": 5, "nullable": true }, "elapsed_seconds": { "description": "Wall-clock seconds since the original request began; frozen at completion for terminal requests.", "type": "integer", "example": 0 }, "cost_notice": { "type": "string" } }, "type": "object" }, "ResourceQuestionAnswerResponse": { "description": "The current state of an asynchronous resource scan. The shape mirrors the get_resource_answer MCP tool output. Returned by GET /v1/resources/{resource}/questions/{run} with 202 while non-terminal and 200 once terminal. The body always carries the `status` field.", "required": [ "request_id", "status", "resource_id", "question", "scope_reference", "progress", "answer", "findings", "finding_count", "next_cursor", "model_generated", "source_reference", "poll_after_seconds", "coverage", "limitations", "usage", "processing_seconds", "elapsed_seconds", "error", "reuse_notice" ], "properties": { "request_id": { "$ref": "#/components/schemas/ResourceQuestionRunId" }, "status": { "type": "string", "example": "completed", "enum": [ "queued", "running", "completed", "completed_with_gaps", "failed", "cancelled" ] }, "resource_id": { "$ref": "#/components/schemas/ResourceId" }, "question": { "type": "string", "example": "List every vehicle brand mentioned in the document." }, "scope_reference": { "type": "string", "example": "#page=2-3", "nullable": true }, "progress": { "required": [ "total_windows", "completed_windows", "partial_windows", "failed_windows", "queued_windows", "running_windows", "phase", "last_progress_at" ], "properties": { "total_windows": { "type": "integer", "example": 4 }, "completed_windows": { "type": "integer", "example": 4 }, "partial_windows": { "type": "integer", "example": 0 }, "failed_windows": { "type": "integer", "example": 0 }, "queued_windows": { "type": "integer", "example": 0 }, "running_windows": { "type": "integer", "example": 0 }, "phase": { "type": "string", "example": "finished", "enum": [ "preparing", "extracting", "reducing", "synthesizing", "finished" ] }, "last_progress_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "answer": { "description": "The compact answer once the run reaches a terminal success status; null while in progress, failed, or cancelled.", "type": "string", "nullable": true }, "findings": { "type": "array", "items": { "required": [ "statement", "source_references", "evidence_basis" ], "properties": { "statement": { "type": "string" }, "source_references": { "type": "array", "items": { "type": "string" } }, "evidence_basis": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "finding_count": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "nullable": true }, "model_generated": { "type": "boolean", "example": true }, "source_reference": { "description": "Identifies only the scanned resource or scope, not a verified location for each claim.", "type": "string", "example": "#page=2-3" }, "poll_after_seconds": { "description": "Minimum delay before polling again; null when the request is terminal.", "type": "integer", "example": 5, "nullable": true }, "coverage": { "required": [ "scope_reference", "resource_revision", "resource_revision_current", "total_evidence_units", "submitted_evidence_units", "unsubmitted_evidence_units", "excluded_evidence_units", "completed_windows", "partial_windows", "failed_windows", "gap_reasons", "complete" ], "properties": { "scope_reference": { "type": "string", "example": "#page=2-3", "nullable": true }, "resource_revision": { "type": "string" }, "resource_revision_current": { "description": "False when the resource or its interpretation constraints changed after this result was created.", "type": "boolean", "example": true }, "total_evidence_units": { "type": "integer", "example": 12 }, "submitted_evidence_units": { "type": "integer", "example": 12 }, "unsubmitted_evidence_units": { "type": "integer", "example": 0 }, "excluded_evidence_units": { "type": "integer", "example": 0 }, "completed_windows": { "type": "integer", "example": 4 }, "partial_windows": { "type": "integer", "example": 0 }, "failed_windows": { "type": "integer", "example": 0 }, "gap_reasons": { "type": "array", "items": { "type": "string", "enum": [ "output_limit", "provider_timeout", "invalid_model_output", "provider_error" ] } }, "complete": { "description": "True when the run completed with the current resource revision and no partial, failed, or unsubmitted evidence units; otherwise gaps must be assumed.", "type": "boolean", "example": true } }, "type": "object" }, "limitations": { "description": "Caveats that temper how the answer may be used, such as partial coverage or a stale resource revision.", "type": "array", "items": { "type": "string" } }, "usage": { "description": "Accumulated model usage for the run, as reported by the backing agents.", "type": "object", "additionalProperties": true }, "processing_seconds": { "description": "Accumulated active processing time in seconds, excluding queue waits.", "type": "integer", "example": 18 }, "elapsed_seconds": { "description": "Wall-clock seconds since the request began; updates while running and remains fixed after completion.", "type": "integer", "example": 23 }, "error": { "description": "Present only when the run failed or was cancelled; null otherwise.", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "resource_revision_changed", "evidence_preparation_failed", "answer_synthesis_failed", "internal_error", "request_cancelled" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "type": "object", "nullable": true }, "reuse_notice": { "description": "When the scan was expensive, a notice encouraging durable findings to be submitted as a hint; null otherwise.", "type": "string", "nullable": true } }, "type": "object" }, "ResourceQuestionCancelResponse": { "description": "Cancellation result for DELETE /v1/resources/{resource}/questions/{run}. The shape mirrors the cancel_resource_answer MCP tool output.", "required": [ "request_id", "status", "cancelled" ], "properties": { "request_id": { "$ref": "#/components/schemas/ResourceQuestionRunId" }, "status": { "type": "string", "example": "cancelled", "enum": [ "queued", "running", "completed", "completed_with_gaps", "failed", "cancelled" ] }, "cancelled": { "description": "True when the run was cancelled by this call (or was already cancelled); false when it had already reached a different terminal status.", "type": "boolean", "example": true } }, "type": "object" }, "ArchiveNodeRequest": { "description": "Body for archiving or unarchiving a library node and, when archiving, setting its archive description and original MIME type. `archive_description` and `original_mime_type` are ignored when `archived` is `false` (unarchiving clears them).", "required": [ "archived" ], "properties": { "archived": { "description": "Whether the folder becomes an archive. Unarchiving clears the archive description and original MIME type.", "type": "boolean", "example": true }, "archive_description": { "description": "Technical description of how the represented object is split into files and folders, and how the contents should be interpreted.", "type": "string", "example": "A single E-Mail. The body is stored as message.pdf, all attachments are kept in the attachments folder.", "nullable": true, "maxLength": 2000 }, "original_mime_type": { "description": "Media type of the original object this archive represents, e.g. message/rfc822 for an E-Mail.", "type": "string", "example": "message/rfc822", "nullable": true, "maxLength": 255 } }, "type": "object" }, "CreateDirectoryRequest": { "description": "Body for creating a library directory at the given path. The root `/` already exists and cannot be created; `path` must point to a non-existing directory.", "required": [ "path" ], "properties": { "path": { "description": "Absolute library path of the new directory (e.g. `/marketing/campaigns`). Must start with `/`, must not contain `.` or `..` segments, and must not be the root `/`.", "type": "string", "pattern": "^/", "example": "/marketing/campaigns", "maxLength": 2048, "minLength": 2 }, "overview": { "description": "Optional human-readable overview for the new directory.", "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" }, "IssueResourceQuestionRequest": { "description": "Start an asynchronous high-recall scan of one resource. Mirrors the ask_resource MCP tool parameters; the resource identifier comes from the path, not the body.", "required": [ "question", "acknowledge_cost" ], "properties": { "question": { "description": "A concrete, primarily extractive question whose complete answer fits in about 500 words without exhaustive quotations or reproducing substantial portions of the resource.", "type": "string", "example": "List every vehicle brand mentioned in the document.", "maxLength": 4000, "minLength": 1 }, "scope_reference": { "description": "Optional citation fragment such as #page=2-3, #page=2&bbox=..., #t=30,90, #frame=42.5, or #line=10-80. A full reference is also accepted but must address the path resource. Omit to scan the whole processed resource.", "type": "string", "example": "#page=2-3", "nullable": true, "maxLength": 500 }, "acknowledge_cost": { "description": "Must be true to acknowledge that high-recall scanning can be slow and expensive.", "type": "boolean", "example": true } }, "type": "object" }, "LockNodeRequest": { "description": "Body for protecting or unprotecting a library node. A protected item cannot be moved, renamed, or deleted.", "required": [ "locked" ], "properties": { "locked": { "description": "Whether the item becomes protected.", "type": "boolean", "example": true } }, "type": "object" }, "MergeDirectoriesRequest": { "description": "Body for merging the contents of a source directory into a target directory. `source` and `target` must both be absolute library paths. The following conflicts are rejected with 422 or 409: `source === target`; merging the root `/`; merging a directory into its own subtree; reserved paths such as `/.inbox`. Conflicting target files are overwritten by the corresponding source files.", "required": [ "source", "target" ], "properties": { "source": { "$ref": "#/components/schemas/LibraryPath" }, "target": { "$ref": "#/components/schemas/LibraryPath" } }, "type": "object" }, "MoveItemRequest": { "description": "Body for moving or renaming a library item. `source` and `target` must both be absolute library paths. The following conflicts are rejected with 422 or 409: `source === target`; moving the root `/`; moving a directory into its own subtree; moving onto an existing target path; reserved paths such as `/.inbox`.", "required": [ "source", "target" ], "properties": { "source": { "$ref": "#/components/schemas/LibraryPath" }, "target": { "$ref": "#/components/schemas/LibraryPath" } }, "type": "object" }, "SubmitLibraryHintRequest": { "description": "A free-text hint for the agentic librarian to review, e.g. a correction to an asset or a request to save an analysis as a note.", "required": [ "markdown" ], "properties": { "markdown": { "description": "The hint content, in markdown. May reference resources with a backtick-wrapped `res_xxx`.", "type": "string", "example": "The image on page 3 shows skis, not a snowboard. Please correct the description." } }, "type": "object" }, "UploadLibraryFileRequest": { "description": "Multipart upload for a single library-owned resource.", "required": [ "file" ], "properties": { "file": { "description": "The binary file to upload.", "type": "string", "format": "binary" } }, "type": "object" } }, "responses": { "Unauthorized": { "description": "Unauthenticated. A valid bearer token is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "summary": "Unauthenticated error", "value": { "type": "https://tkp.example/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Authentication required. Provide an API-enabled bearer credential or a valid signed URL.", "instance": "/api/v1/libraries" } } } } } }, "Forbidden": { "description": "Forbidden. The access grant may not perform this action.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Forbidden error", "value": { "type": "https://tkp.example/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "The access grant may not perform this action.", "instance": "/api/v1/libraries" } } } } } }, "NotFound": { "description": "Not Found. The requested resource does not exist or is not accessible.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "summary": "Not found error", "value": { "type": "https://tkp.example/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource does not exist or is not accessible.", "instance": "/api/v1/resources/res_fqgountdqko3" } } } } } }, "Conflict": { "description": "Conflict. The request would create a duplicate or inconsistent state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "summary": "Conflict error", "value": { "type": "https://tkp.example/problems/conflict", "title": "Conflict", "status": 409, "detail": "Moving a directory into its own subtree is not allowed.", "instance": "/api/v1/libraries/lib_s50vofoljazr/nodes:move" } } } } } }, "ValidationError": { "description": "Validation failed. The `errors` object lists each invalid field with messages.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation": { "summary": "Validation error", "value": { "type": "https://tkp.example/problems/validation-error", "title": "Validation Error", "status": 422, "detail": "The query field is required.", "instance": "/api/v1/search/resources", "errors": { "query": [ "The query field is required." ] } } }, "unsupported_file_type": { "summary": "Unsupported file format on upload", "value": { "type": "https://tkp.example/problems/validation-error", "title": "Validation Error", "status": 422, "detail": "The file extension and detected MIME type must match a supported resource format.", "instance": "/api/v1/libraries/lib_s50vofoljazr/files", "errors": { "file": [ "The file extension and detected MIME type must match a supported resource format." ] } } } } } } }, "PayloadTooLarge": { "description": "The uploaded file exceeds the maximum allowed size.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "summary": "Payload too large error", "value": { "type": "https://tkp.example/problems/payload-too-large", "title": "Payload Too Large", "status": 413, "detail": "The uploaded file exceeds the maximum allowed size of 100MB.", "instance": "/api/v1/libraries/lib_s50vofoljazr/files" } } } } } }, "TooManyRequests": { "description": "Too Many Requests. The client has exceeded the rate limit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "summary": "Too many requests error", "value": { "type": "https://tkp.example/problems/too-many-requests", "title": "Too Many Requests", "status": 429, "detail": "The client has exceeded the rate limit.", "instance": "/api/v1/search/resources" } } } } } }, "InternalServerError": { "description": "Internal Server Error. An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_server_error": { "summary": "Internal server error", "value": { "type": "https://tkp.example/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred.", "instance": "/api/v1/search/resources" } } } } } }, "ServiceUnavailable": { "description": "Service Unavailable. The server is temporarily unable to handle the request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Service unavailable error", "value": { "type": "https://tkp.example/problems/service-unavailable", "title": "Service Unavailable", "status": 503, "detail": "The server is temporarily unable to handle the request.", "instance": "/api/v1/search/resources" } } } } } } }, "securitySchemes": { "accessToken": { "type": "http", "description": "Personal Access Token. Provide it as `Bearer `.", "scheme": "bearer" }, "oauth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://tkp.example/oauth/authorize", "tokenUrl": "https://tkp.example/oauth/token", "scopes": { "api:use": "Use the REST API" } } } } } }, "tags": [ { "name": "Auth", "description": "Authentication verification and access context introspection for the authenticated token." }, { "name": "Assets", "description": "Download asset binaries and issue short-lived signed URLs for embedding in dashboards or chat." }, { "name": "Libraries", "description": "Library metadata, navigation, file management, and operations." }, { "name": "Search", "description": "Search knowledge resources across accessible libraries." }, { "name": "Resources", "description": "Download original resource files, rendered pages, and issue short-lived signed URLs for embedding in dashboards or chat." }, { "name": "Health", "description": "Unauthenticated liveness and readiness probes for orchestrators and load balancers." } ], "security": [ { "accessToken": [] } ] }