{ "openapi": "3.0.0", "paths": { "/v1/files": { "get": { "description": "Cursor paginated, never offset. A short page does not mean the end: items the key may not read are dropped after the page is read, so page until `hasMore` is false.", "operationId": "FilesController_listFiles", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum items in one page. A page may come back shorter; read `hasMore`, not the count.", "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "A `nextCursor` from an earlier page. Opaque: store and echo it, never parse or construct one. A cursor belongs to the query that issued it, so changing a filter means starting again from the first page; reusing one across filters answers `invalid_cursor` rather than a page from the wrong collection.", "schema": { "type": "string" } }, { "name": "path", "required": false, "in": "query", "description": "Exact path to a file, so it ends in `.md`. Returns the collection holding zero or one file: a path naming nothing is an empty collection, not a 404, because the request named no resource to be missing.", "schema": { "example": "/support/policies/refunds.md", "type": "string" } }, { "name": "path_prefix", "required": false, "in": "query", "description": "Every file below this folder, recursively. A folder path, so it does not end in `.md`. A prefix naming no folder is an empty collection, for the same reason `path` is.", "schema": { "example": "/support", "type": "string" } }, { "name": "parent_id", "required": false, "in": "query", "description": "Files directly inside this folder, one level only. Use `path_prefix` for a whole subtree. A folder id naming nothing is an empty collection.", "schema": { "example": "dir_9f2k1x8b3m7q0v", "type": "string" } } ], "responses": { "200": { "description": "A page of files. Read `hasMore` before stopping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" } } } }, "400": { "description": "`invalid_request`: unknown or malformed parameter, see `errors`. `invalid_cursor`: the `cursor` is malformed or was issued for a different query; start again from the first page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } }, "invalid_cursor": { "summary": "Invalid cursor", "value": { "type": "https://docs.qontext.ai/errors/invalid-cursor", "title": "Invalid cursor", "status": 400, "code": "invalid_cursor", "detail": "This cursor could not be read. Start again from the first page.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "List files", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/list-files", "metadata": { "description": "List file metadata one page at a time, filtered by path or parent folder." } } }, "post": { "description": "Creates a file at the path given. Not an upsert: a path already holding a file is a conflict, so this never overwrites and never creates a duplicate. The response carries the `id` and the `lastChangeId`; later writes address those, because a rename moves the path.", "operationId": "FilesController_createFile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateFileByPathRequest" }, { "$ref": "#/components/schemas/CreateFileInFolderRequest" } ] } } } }, "responses": { "201": { "description": "Created. The file is in the live files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not create here. Declared on this operation rather than for the whole API, because a read this key may not perform answers as not found instead.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`path_already_exists`: a file is already at that path", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "path_already_exists": { "summary": "Path already exists", "value": { "type": "https://docs.qontext.ai/errors/path-already-exists", "title": "Path already exists", "status": 409, "code": "path_already_exists", "detail": "Something already exists at that path.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "422": { "description": "`content_too_large`: `content` is longer than the published limit", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "summary": "Content too long", "value": { "type": "https://docs.qontext.ai/errors/content-too-large", "title": "Content too long", "status": 422, "code": "content_too_large", "detail": "The content is longer than this API accepts.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "too_long", "pointer": "/content", "detail": "61440 characters; the limit is 51200." } ] } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Create a file", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/create-file", "metadata": { "description": "Create a file by path or in a parent folder. An existing file is never overwritten." } } } }, "/v1/files/{id}": { "get": { "description": "Answers the file and its full text. Together with `lastChangeId`, that is everything the content endpoint needs for the next write. The workspace is implicit in the API key and never appears in the URL. A file in another workspace answers as `file_not_found`, so existence does not leak.", "operationId": "FilesController_getFile", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The file id, as an earlier response reported it. Always `doc_…`; a composite id is refused.", "schema": { "example": "doc_9f2k1x8b3m7q0v", "type": "string" } } ], "responses": { "200": { "description": "The file as the live files hold it, with its full text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileWithContent" } } } }, "400": { "description": "`invalid_id`: not a file id of the form `doc_…`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_id": { "summary": "Invalid id", "value": { "type": "https://docs.qontext.ai/errors/invalid-id", "title": "Invalid id", "status": 400, "code": "invalid_id", "detail": "This id is not in a form this API issues. Use one from an earlier response.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`file_not_found`: no such file readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "file_not_found": { "summary": "File not found", "value": { "type": "https://docs.qontext.ai/errors/file-not-found", "title": "File not found", "status": 404, "code": "file_not_found", "detail": "No file with that id, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Get a file by its id", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/get-file", "metadata": { "description": "Read a file by its id, with its full content and its last change id." } } }, "patch": { "description": "Send exactly one of `name` to rename in place, `parentId` to move, or `protected` to change whether changes to this file go to review. The id never changes, so ids held by a client stay valid; the path does. Sending two, or none, is rejected rather than resolved by a precedence rule: these are separate writes with no transaction across them, so a request doing two could apply the first and fail the second with no way to report which.", "operationId": "FilesController_updateFile", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The file id, as an earlier response reported it. Always `doc_…`; a composite id is refused.", "schema": { "example": "doc_9f2k1x8b3m7q0v", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RenameFileRequest" }, { "$ref": "#/components/schemas/MoveFileRequest" }, { "$ref": "#/components/schemas/ProtectFileRequest" } ] } } } }, "responses": { "200": { "description": "The file after the change. Its id is the one you sent to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`; or not exactly one of `name`, `parentId` and `protected`. `invalid_id`: not a file id of the form `doc_…`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } }, "invalid_id": { "summary": "Invalid id", "value": { "type": "https://docs.qontext.ai/errors/invalid-id", "title": "Invalid id", "status": 400, "code": "invalid_id", "detail": "This id is not in a form this API issues. Use one from an earlier response.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not change this file, or may not administer it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`file_not_found`: no such file readable with this key. `folder_not_found`: no such destination folder readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "file_not_found": { "summary": "File not found", "value": { "type": "https://docs.qontext.ai/errors/file-not-found", "title": "File not found", "status": 404, "code": "file_not_found", "detail": "No file with that id, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } }, "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`path_already_exists`: the destination already holds a file with this name", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "path_already_exists": { "summary": "Path already exists", "value": { "type": "https://docs.qontext.ai/errors/path-already-exists", "title": "Path already exists", "status": 409, "code": "path_already_exists", "detail": "Something already exists at that path.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Rename, move, or protect a file", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/update-file", "metadata": { "description": "Rename, move, or protect a file. One change per request; the id never changes." }, "content": "## Changing `protected`\n\nSetting or clearing `protected` needs the admin grant on the file, which the app shows as **Full access**. A key that holds only **Can read** or **Can edit** on the file answers `403 forbidden` for this one member. A rename or a move needs **Can edit**." } }, "delete": { "description": "Removes the file. Its change history goes with it, so this is not reversible through this API. A protected file, or one with changes still in review, is refused and nothing is removed, so a caller that did not mean to discard that work can deal with it first.", "operationId": "FilesController_deleteFile", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The file id, as an earlier response reported it. Always `doc_…`; a composite id is refused.", "schema": { "example": "doc_9f2k1x8b3m7q0v", "type": "string" } } ], "responses": { "204": { "description": "Deleted. No body." }, "400": { "description": "`invalid_id`: not a file id of the form `doc_…`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_id": { "summary": "Invalid id", "value": { "type": "https://docs.qontext.ai/errors/invalid-id", "title": "Invalid id", "status": 400, "code": "invalid_id", "detail": "This id is not in a form this API issues. Use one from an earlier response.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not delete this file", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`file_not_found`: no such file deletable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "file_not_found": { "summary": "File not found", "value": { "type": "https://docs.qontext.ai/errors/file-not-found", "title": "File not found", "status": 404, "code": "file_not_found", "detail": "No file with that id, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`changes_in_review`: the file has changes in review; try again once those are accepted or rejected. `file_protected`: the file is protected; clear `protected` on it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "changes_in_review": { "summary": "Changes in review", "value": { "type": "https://docs.qontext.ai/errors/changes-in-review", "title": "Changes in review", "status": 409, "code": "changes_in_review", "detail": "This folder contains files with changes in review. Try again after those changes are accepted or rejected.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } }, "file_protected": { "summary": "File protected", "value": { "type": "https://docs.qontext.ai/errors/file-protected", "title": "File protected", "status": 409, "code": "file_protected", "detail": "This file is protected. Clear `protected` on it first if you mean to delete it.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Delete a file", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/delete-file", "metadata": { "description": "Delete a file and its change history. This cannot be undone through the API." } } } }, "/v1/files/{id}/content": { "put": { "description": "Replace the entire file content. Send the file's `lastChangeId` as `baseChangeId`. If the file changed first, the two versions are combined when possible. The response contains the content now saved; use it for the next edit.", "operationId": "FilesController_editFileContent", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The file id, as an earlier response reported it. Always `doc_…`; a composite id is refused.", "schema": { "example": "doc_9f2k1x8b3m7q0v", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditFileRequest" } } } }, "responses": { "200": { "description": "Accepted. The edit is in the live files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditFileResponse" } } } }, "202": { "description": "The change is in review. The live files are unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeInReview" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`. `invalid_id`: not a file id of the form `doc_…`, or a `baseChangeId` not of the form `chg_…`. `invalid_base_change`: `baseChangeId` names no change of this file.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } }, "invalid_id": { "summary": "Invalid id", "value": { "type": "https://docs.qontext.ai/errors/invalid-id", "title": "Invalid id", "status": 400, "code": "invalid_id", "detail": "This id is not in a form this API issues. Use one from an earlier response.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } }, "invalid_base_change": { "summary": "Invalid base change", "value": { "type": "https://docs.qontext.ai/errors/invalid-base-change", "title": "Invalid base change", "status": 400, "code": "invalid_base_change", "detail": "This change does not belong to this file. Read the file again and use the change it reports.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not edit this file", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`file_not_found`: no such file editable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "file_not_found": { "summary": "File not found", "value": { "type": "https://docs.qontext.ai/errors/file-not-found", "title": "File not found", "status": 404, "code": "file_not_found", "detail": "No file with that id, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "422": { "description": "`content_too_large`: `content` is longer than the published limit", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "summary": "Content too long", "value": { "type": "https://docs.qontext.ai/errors/content-too-large", "title": "Content too long", "status": 422, "code": "content_too_large", "detail": "The content is longer than this API accepts.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "too_long", "pointer": "/content", "detail": "61440 characters; the limit is 51200." } ] } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Replace a file's content", "tags": [ "Files" ], "x-mint": { "href": "/api-docs/files/replace-file-content", "metadata": { "description": "Replace the content of a file from the version you read. A change to a protected file goes to review." } } } }, "/v1/folders": { "post": { "description": "Creates one folder at `path`, creating missing parents, or directly inside `parentId` when sent with `name`. Not an upsert: a path already holding a folder is a conflict, so this never merges into an existing folder.", "operationId": "FoldersController_createFolder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateFolderByPathRequest" }, { "$ref": "#/components/schemas/CreateFolderInParentRequest" } ] } } } }, "responses": { "201": { "description": "Created. The folder is in the live files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not create in that parent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`folder_not_found`: parent folder not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`path_already_exists`: that parent already holds a folder with this name", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "path_already_exists": { "summary": "Path already exists", "value": { "type": "https://docs.qontext.ai/errors/path-already-exists", "title": "Path already exists", "status": 409, "code": "path_already_exists", "detail": "Something already exists at that path.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Create a folder", "tags": [ "Folders" ], "x-mint": { "href": "/api-docs/folders/create-folder", "metadata": { "description": "Create a folder by path or in a parent folder. Missing parents are created." } } }, "get": { "description": "Lists one folder by `path`, every folder below `path_prefix`, or direct children by `parent_id`. Without a selector it lists root folders. Cursor paginated, never offset. A short page does not mean the end: items the key may not read are dropped after the page is read, so page until `hasMore` is false.", "operationId": "FoldersController_listFolders", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum items in one page. A page may come back shorter; read `hasMore`, not the count.", "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "A `nextCursor` from an earlier page. Opaque: store and echo it, never parse or construct one. A cursor belongs to the query that issued it, so changing a filter means starting again from the first page; reusing one across filters answers `invalid_cursor` rather than a page from the wrong collection.", "schema": { "type": "string" } }, { "name": "path", "required": false, "in": "query", "description": "Exact path to a folder. A path naming nothing is an empty collection. The root itself is not addressable here; omit every selector to list root folders.", "schema": { "example": "/support/policies", "type": "string" } }, { "name": "path_prefix", "required": false, "in": "query", "description": "Every folder below this folder, recursively. A prefix naming nothing is an empty collection.", "schema": { "example": "/support", "type": "string" } }, { "name": "parent_id", "required": false, "in": "query", "description": "Lists folders directly inside this parent. Omit it to list root folders.", "schema": { "example": "dir_9f2k1x8b3m7q0v", "type": "string" } } ], "responses": { "200": { "description": "A page of folders. Read `hasMore` before stopping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderList" } } } }, "400": { "description": "`invalid_request`: unknown or malformed parameter, see `errors`. `invalid_cursor`: the `cursor` is malformed or was issued for a different query; start again from the first page.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } }, "invalid_cursor": { "summary": "Invalid cursor", "value": { "type": "https://docs.qontext.ai/errors/invalid-cursor", "title": "Invalid cursor", "status": 400, "code": "invalid_cursor", "detail": "This cursor could not be read. Start again from the first page.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`folder_not_found`: no such parent folder readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "List folders", "tags": [ "Folders" ], "x-mint": { "href": "/api-docs/folders/list-folders", "metadata": { "description": "List folders one page at a time, filtered by path or parent folder." } } } }, "/v1/folders/{id}": { "get": { "description": "The workspace is implicit in the API key and never appears in the URL. A folder in another workspace answers as `folder_not_found`, so existence does not leak.", "operationId": "FoldersController_getFolder", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The folder id, as an earlier response reported it. Always `dir_…`.", "schema": { "example": "dir_9f2k1x8b3m7q0v", "type": "string" } } ], "responses": { "200": { "description": "The folder as the live files hold it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "`invalid_id`: not a folder id of the form `dir_…`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_id": { "summary": "Invalid id", "value": { "type": "https://docs.qontext.ai/errors/invalid-id", "title": "Invalid id", "status": 400, "code": "invalid_id", "detail": "This id is not in a form this API issues. Use one from an earlier response.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`folder_not_found`: no such folder readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Get a folder by its id", "tags": [ "Folders" ], "x-mint": { "href": "/api-docs/folders/get-folder", "metadata": { "description": "Read the metadata of a folder by its id." } } }, "patch": { "description": "Send exactly one of `name` to rename in place, or `parentId` to move. A move takes the whole subtree and every id in it survives, so ids held by a client stay valid; the paths below it change. Sending both, or neither, is rejected rather than resolved by a precedence rule.", "operationId": "FoldersController_updateFolder", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The folder id, as an earlier response reported it. Always `dir_…`.", "schema": { "example": "dir_9f2k1x8b3m7q0v", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RenameFolderRequest" }, { "$ref": "#/components/schemas/MoveFolderRequest" } ] } } } }, "responses": { "200": { "description": "The folder after the change. Its id, and every id below it, is unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`; not exactly one of `name` and `parentId`; or a move into this folder or one of its descendants", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not change that folder", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`folder_not_found`: no such folder, or no such destination, readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`path_already_exists`: the destination already holds a folder with this name", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "path_already_exists": { "summary": "Path already exists", "value": { "type": "https://docs.qontext.ai/errors/path-already-exists", "title": "Path already exists", "status": 409, "code": "path_already_exists", "detail": "Something already exists at that path.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Rename or move a folder", "tags": [ "Folders" ], "x-mint": { "href": "/api-docs/folders/update-folder", "metadata": { "description": "Rename a folder or move it with its subtree. Every id below it survives." } } }, "delete": { "description": "Refuses a folder that still has contents unless `recursive=true` is sent, in which case the whole subtree goes. The refusal changes nothing, so a caller that did not mean to delete the contents can read them first and decide.", "operationId": "FoldersController_deleteFolder", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The folder id, as an earlier response reported it. Always `dir_…`.", "schema": { "example": "dir_9f2k1x8b3m7q0v", "type": "string" } }, { "name": "recursive", "required": false, "in": "query", "description": "Delete the folder together with everything below it. Left off, a folder that still has contents is refused as `folder_not_empty` and nothing is removed.", "schema": { "default": false, "example": true, "type": "boolean" } } ], "responses": { "204": { "description": "Deleted. No body." }, "400": { "description": "`invalid_request`: malformed delete parameter", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "403": { "description": "`forbidden`: this key may not delete that folder", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "summary": "Not permitted", "value": { "type": "https://docs.qontext.ai/errors/forbidden", "title": "Not permitted", "status": 403, "code": "forbidden", "detail": "This key is not allowed to do that.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "404": { "description": "`folder_not_found`: no such folder readable with this key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_found": { "summary": "Folder not found", "value": { "type": "https://docs.qontext.ai/errors/folder-not-found", "title": "Folder not found", "status": 404, "code": "folder_not_found", "detail": "No folder at that path, or none this key is allowed to read.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "409": { "description": "`folder_not_empty`: the folder still has contents; send `recursive=true` to remove them. `changes_in_review`: the folder contains files with changes in review; try again once those are accepted or rejected.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "folder_not_empty": { "summary": "Folder not empty", "value": { "type": "https://docs.qontext.ai/errors/folder-not-empty", "title": "Folder not empty", "status": 409, "code": "folder_not_empty", "detail": "This folder still has contents. Delete those first, or send `recursive=true`.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } }, "changes_in_review": { "summary": "Changes in review", "value": { "type": "https://docs.qontext.ai/errors/changes-in-review", "title": "Changes in review", "status": 409, "code": "changes_in_review", "detail": "This folder contains files with changes in review. Try again after those changes are accepted or rejected.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Delete a folder", "tags": [ "Folders" ], "x-mint": { "href": "/api-docs/folders/delete-folder", "metadata": { "description": "Delete an empty folder, or its whole subtree with `recursive=true`." } } } }, "/v1/search/hybrid": { "post": { "description": "Finds the files that match your query and returns their content, best match first. Each result cites the file it came from. It also matches on meaning, which finds files that answer the query without using the same words. A result appears only if this API key can read the file. A new or changed file is not searchable straight away, so search again in a moment if you do not see it.", "operationId": "SearchController_searchHybrid", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Matching files from the live files, best match first. One page; there is no next.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridSearchResult" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Search files by meaning", "tags": [ "Search" ], "x-mint": { "href": "/api-docs/search/hybrid-search", "metadata": { "description": "Find files by meaning and read their content, with the file each result came from." }, "content": "## Results with restricted access\n\nA key that can read only part of the context repository can get fewer files than `limit`, or none, when readable matches exist. Access is applied after the best matches are chosen. An empty result does not prove that no matching content exists. When you know a file by its id or its path, read it directly." } } }, "/v1/search/regex": { "post": { "description": "Finds lines that match an RE2 regular expression. Each result cites the file the lines came from. Results are not relevance-ranked. A result appears only if this API key can read the file.", "operationId": "SearchController_searchRegex", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegexSearchRequest" } } } }, "responses": { "200": { "description": "Files in the live files with matching lines, not ranked. One page; there is no next.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegexSearchResult" } } } }, "400": { "description": "`invalid_request`: unknown or malformed member, see `errors`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "summary": "Invalid request", "value": { "type": "https://docs.qontext.ai/errors/invalid-request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "The request could not be accepted as sent.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b", "errors": [ { "code": "out_of_range", "pointer": "/limit", "detail": "limit must not be greater than 1000" } ] } } } } } }, "401": { "description": "`unauthenticated`: missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthenticated": { "summary": "Unauthenticated", "value": { "type": "https://docs.qontext.ai/errors/unauthenticated", "title": "Unauthenticated", "status": 401, "code": "unauthenticated", "detail": "The API key is missing or not valid.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "500": { "description": "`internal_error`: unexpected failure, already reported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qontext.ai/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "detail": "An unexpected error occurred.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } }, "503": { "description": "`service_unavailable`: temporarily unreachable. Honour `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "summary": "Temporarily unavailable", "value": { "type": "https://docs.qontext.ai/errors/service-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "service_unavailable", "detail": "This workspace is temporarily unavailable.", "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b" } } } } } } }, "security": [ { "Authorization": [] }, { "X-API-Key": [] } ], "summary": "Search file lines with a regular expression", "tags": [ "Search" ], "x-mint": { "href": "/api-docs/search/regex-search", "metadata": { "description": "Find lines that match an RE2 regular expression across the files this key can read." }, "content": "## Limits\n\n- Each file reports at most 50 matching lines.\n- A line longer than 4096 characters is skipped.\n\n## Results with restricted access\n\nA key that can read only part of the context repository can get fewer files than `limit`, or none, when readable matches exist. Access is applied after the best matches are chosen. An empty result does not prove that no matching content exists. When you know a file by its id or its path, read it directly." } } } }, "info": { "title": "Qontext API", "description": "Read and write the knowledge a workspace has ingested.", "version": "1.0.0", "contact": {} }, "tags": [ { "name": "Files", "description": "Read and write the files in a workspace. What you read, and what an accepted change goes into, is the live files: the accepted state of the world. A change to a protected file goes to review instead of being accepted automatically, and stays in review until somebody accepts or rejects it." }, { "name": "Folders", "description": "The tree the files sit in. A folder id survives a rename and a move, and so does every id below it, so ids a client holds stay valid while paths change." }, { "name": "Search", "description": "Find files by meaning or by a regular expression. Both search the live files, both answer one page of the best matches, and both drop a file this key may not read." } ], "servers": [ { "url": "https://api.qontext.ai", "description": "Production" } ], "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer", "description": "Workspace-scoped API key, sent as a bearer token. The recommended header. The workspace is implicit in the key and never appears in a URL." }, "X-API-Key": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same workspace-scoped API key under its original header. Still supported, and still enough on its own. Prefer `Authorization: Bearer` for a new client." } }, "schemas": { "FieldError": { "type": "object", "properties": { "code": { "type": "string", "example": "out_of_range", "description": "Stable machine token for what was wrong with this field." }, "pointer": { "type": "string", "example": "/limit", "description": "JSON Pointer to the offending member." }, "detail": { "type": "string", "example": "limit must not be greater than 1000", "description": "Human explanation for this field alone. Branch on `code`, not on this." } }, "required": [ "code", "pointer", "detail" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "example": "https://docs.qontext.ai/errors/file-not-found", "description": "Stable URI for this kind of failure. Branch on this or on `code`, never on `title` or `detail`." }, "title": { "type": "string", "example": "File not found", "description": "Human label. Not for branching on." }, "status": { "type": "number", "example": 404, "description": "Matches the HTTP status." }, "code": { "type": "string", "example": "file_not_found", "description": "Stable machine code. This is what a client branches on." }, "detail": { "type": "string", "description": "Human explanation, safe to display. Never a stack trace or engine detail." }, "requestId": { "type": "string", "description": "Echoes the `X-Request-Id` response header. One string locates the log line for this call." }, "errors": { "description": "Present when the failure is attributable to specific inputs.", "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } } }, "required": [ "type", "title", "status", "code", "detail", "requestId" ] }, "File": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "file" ], "description": "Type discriminator. Always `file`." }, "id": { "type": "string", "example": "doc_9f2k1x8b3m7q0v", "description": "Stable id. Survives a rename or a move." }, "path": { "type": "string", "example": "/support/policies/refunds.md", "description": "Live file location. Changes when the file moves." }, "name": { "type": "string", "example": "refunds.md", "description": "Leaf name, including its extension, without any part of the path." }, "parentId": { "type": "string", "example": "dir_4k1n8p2v5m7q0x", "nullable": true, "description": "The containing folder, or `null` when the file sits at the root. Send it back to move a file." }, "parentPath": { "type": "string", "example": "/support/policies", "description": "Path of the containing folder. `/` at the root." }, "protected": { "type": "boolean", "description": "When true, a change to this file goes to review instead of being accepted automatically." }, "lastChangeId": { "type": "string", "example": "chg_7t4p2w9c1n6s8k", "description": "The last content change to this file. A rename or a move does not advance it. Pass it back as `baseChangeId` on a write." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-07-01T09:12:00.000Z", "description": "When the file was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-08-01T14:03:00.000Z", "description": "When the file last changed, including a rename or a move." } }, "required": [ "object", "id", "path", "name", "parentId", "parentPath", "protected", "lastChangeId", "createdAt", "updatedAt" ] }, "FileList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Type discriminator. Always `list`." }, "url": { "type": "string", "example": "/v1/files", "description": "The collection this page came from, without the query that selected it." }, "hasMore": { "type": "boolean", "description": "Whether more items remain. A short page does not mean the end: unreadable items are dropped after the page is read. Page until this is false." }, "nextCursor": { "type": "string", "nullable": true, "example": "c_9f2k1x8b3m7q0v", "description": "Opaque. Pass back as `cursor`. Present whenever `hasMore` is true, `null` on the last page." }, "data": { "description": "The files on this page.", "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "object", "url", "hasMore", "nextCursor", "data" ] }, "FileWithContent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "file" ], "description": "Type discriminator. Always `file`." }, "id": { "type": "string", "example": "doc_9f2k1x8b3m7q0v", "description": "Stable id. Survives a rename or a move." }, "path": { "type": "string", "example": "/support/policies/refunds.md", "description": "Live file location. Changes when the file moves." }, "name": { "type": "string", "example": "refunds.md", "description": "Leaf name, including its extension, without any part of the path." }, "parentId": { "type": "string", "example": "dir_4k1n8p2v5m7q0x", "nullable": true, "description": "The containing folder, or `null` when the file sits at the root. Send it back to move a file." }, "parentPath": { "type": "string", "example": "/support/policies", "description": "Path of the containing folder. `/` at the root." }, "protected": { "type": "boolean", "description": "When true, a change to this file goes to review instead of being accepted automatically." }, "lastChangeId": { "type": "string", "example": "chg_7t4p2w9c1n6s8k", "description": "The last content change to this file. A rename or a move does not advance it. Pass it back as `baseChangeId` on a write." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-07-01T09:12:00.000Z", "description": "When the file was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-08-01T14:03:00.000Z", "description": "When the file last changed, including a rename or a move." }, "content": { "type": "string", "example": "# Refunds\n\nRefunds are processed within 14 days.", "description": "The full file text, as authored. Send it back through the content endpoint, with the `lastChangeId` from this response as `baseChangeId`, to edit the file." } }, "required": [ "object", "id", "path", "name", "parentId", "parentPath", "protected", "lastChangeId", "createdAt", "updatedAt", "content" ] }, "CreateFileByPathRequest": { "type": "object", "properties": { "path": { "type": "string", "example": "/support/policies/refunds.md", "description": "Where to create the file. Absolute, and ends in `.md`. A path already holding a file is a conflict, never an overwrite." }, "content": { "type": "string", "example": "# Refunds\n\nRefunds are processed within 14 days.", "description": "Markdown or plain text.", "maxLength": 51200 } }, "title": "Create by path", "description": "Create the file at an absolute path. Missing parent folders are created on the way.", "additionalProperties": false, "required": [ "path", "content" ] }, "CreateFileInFolderRequest": { "type": "object", "properties": { "parentId": { "type": "string", "example": "dir_9f2k1x8b3m7q0v", "nullable": true, "description": "Parent folder id. Send with `name` instead of `path`; `null` puts the file at the root." }, "name": { "type": "string", "example": "refunds.md", "description": "File name. Send with `parentId` instead of `path`." }, "content": { "type": "string", "example": "# Refunds\n\nRefunds are processed within 14 days.", "description": "Markdown or plain text.", "maxLength": 51200 } }, "title": "Create in a folder", "description": "Create the file inside a folder you already hold the id of. `null` puts it at the root.", "additionalProperties": false, "required": [ "parentId", "name", "content" ] }, "EditFileRequest": { "type": "object", "properties": { "baseChangeId": { "type": "string", "example": "chg_7t4p2w9c1n6s8k", "description": "The file's last content change when this edit started. Send the `lastChangeId` returned when you read the file." }, "content": { "type": "string", "example": "# Refunds\n\nRefunds are processed within 14 days.", "description": "The full new file content. It replaces the live content.", "maxLength": 51200 } }, "additionalProperties": false, "required": [ "baseChangeId", "content" ] }, "EditFileResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "edit" ], "description": "Type discriminator. Always `edit`." }, "file": { "description": "The file at its new state. `lastChangeId` has advanced.", "allOf": [ { "$ref": "#/components/schemas/File" } ] }, "content": { "type": "string", "example": "# Refunds\n\nRefunds are processed within 14 days.", "description": "The content now in the live files. Not always the content that was sent: an edit based on an older change is combined with the changes accepted since. Adopt this before editing the file again." } }, "required": [ "object", "file", "content" ] }, "ChangeInReview": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "change" ], "description": "Type discriminator. Always `change`." }, "id": { "type": "string", "example": "chg_7t4p2w9c1n6s8k", "description": "Stable id. Use it to accept or reject the change." }, "status": { "type": "string", "enum": [ "in_review" ], "description": "Always `in_review` here: a change this endpoint returns is one that was not accepted." }, "reason": { "type": "string", "enum": [ "protected", "conflict" ], "description": "Why it was not accepted. `protected`: the file requires review, so the edit is waiting for a decision. `conflict`: an accepted change since then touched the same sections, so somebody has to choose. `protected` wins when both are true." }, "fileIds": { "example": [ "doc_9f2k1x8b3m7q0v" ], "description": "The files the change could not apply to. Always one for an edit.", "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-08-01T14:03:00.000Z", "description": "When this change was raised, which is not when the file it touches was made." } }, "required": [ "object", "id", "status", "reason", "fileIds", "createdAt" ] }, "RenameFileRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "returns.md", "description": "New file name, including its extension. Renames the file in place. Send instead of `parentId`, never with it." } }, "title": "Rename", "description": "Rename the file in place. The id and the folder do not change.", "additionalProperties": false, "required": [ "name" ] }, "MoveFileRequest": { "type": "object", "properties": { "parentId": { "type": "string", "example": "dir_9f2k1x8b3m7q0v", "nullable": true, "description": "Folder to move this file into, keeping its id and its name. `null` moves it to the root. The file object answers the same `parentId`, so a read gives you what a move needs. Send instead of `name`, never with it." } }, "title": "Move", "description": "Move the file into another folder. The id and the name do not change.", "additionalProperties": false, "required": [ "parentId" ] }, "ProtectFileRequest": { "type": "object", "properties": { "protected": { "type": "boolean", "example": true, "description": "Whether a change touching this file goes to review instead of being accepted automatically. Send instead of `name` or `parentId`, never with either." } }, "title": "Protect", "description": "Route changes to this file through review, or stop doing so.", "additionalProperties": false, "required": [ "protected" ] }, "CreateFolderByPathRequest": { "type": "object", "properties": { "path": { "type": "string", "example": "/projects/reports", "description": "Absolute path for the new folder. Missing parent folders are created on the way." } }, "title": "Create by path", "description": "Create the folder at an absolute path. Missing parent folders are created on the way.", "additionalProperties": false, "required": [ "path" ] }, "CreateFolderInParentRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "reports", "description": "Leaf name of the new folder. Send with `parentId` instead of `path`." }, "parentId": { "type": "string", "example": "dir_9f2k1x8b3m7q0v", "nullable": true, "description": "Folder to create this one inside. Send with `name` instead of `path`; `null` puts it at the root." } }, "title": "Create in a parent", "description": "Create the folder inside a parent you already hold the id of. `null` puts it at the root.", "additionalProperties": false, "required": [ "name", "parentId" ] }, "Folder": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "folder" ], "description": "Type discriminator. Always `folder`." }, "id": { "type": "string", "example": "dir_9f2k1x8b3m7q0v", "description": "Stable id. Survives a rename or a move." }, "name": { "type": "string", "example": "reports", "description": "Leaf name, without any part of the path." }, "parentId": { "type": "string", "example": "dir_4k1n8p2v5m7q0x", "nullable": true, "description": "The containing folder, or `null` when this folder sits at the root." }, "parentPath": { "type": "string", "example": "/projects", "description": "Path of the containing folder. `/` at the root." }, "path": { "type": "string", "example": "/projects/reports", "description": "Live folder location. Changes when the folder moves." }, "protected": { "type": "boolean", "description": "When true, a change to any file inside this folder goes to review instead of being accepted automatically, however the file itself is flagged." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-07-01T09:12:00.000Z", "description": "When the folder was created." }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-08-01T14:03:00.000Z", "description": "When the folder was last updated." } }, "required": [ "object", "id", "name", "parentId", "parentPath", "path", "protected", "createdAt", "updatedAt" ] }, "FolderList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Type discriminator. Always `list`." }, "url": { "type": "string", "example": "/v1/files", "description": "The collection this page came from, without the query that selected it." }, "hasMore": { "type": "boolean", "description": "Whether more items remain. A short page does not mean the end: unreadable items are dropped after the page is read. Page until this is false." }, "nextCursor": { "type": "string", "nullable": true, "example": "c_9f2k1x8b3m7q0v", "description": "Opaque. Pass back as `cursor`. Present whenever `hasMore` is true, `null` on the last page." }, "data": { "description": "The folders on this page.", "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } }, "required": [ "object", "url", "hasMore", "nextCursor", "data" ] }, "RenameFolderRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "initiatives", "description": "New leaf name, which renames the folder in place. Send instead of `parentId`, never with it." } }, "title": "Rename", "description": "Rename the folder in place. The id and the parent do not change.", "additionalProperties": false, "required": [ "name" ] }, "MoveFolderRequest": { "type": "object", "properties": { "parentId": { "type": "string", "example": "dir_9f2k1x8b3m7q0v", "nullable": true, "description": "Folder to move this one into, taking its whole subtree and keeping every id. `null` moves it to the root. Send instead of `name`, never with it." } }, "title": "Move", "description": "Move the folder, with its whole subtree, into another parent. Every id survives.", "additionalProperties": false, "required": [ "parentId" ] }, "SearchRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "What you are looking for. A few words or a whole question both work.", "example": "What is the refund policy?" }, "limit": { "type": "integer", "description": "Maximum results to return. Defaults to 10.", "minimum": 1, "maximum": 500, "default": 10 }, "includeSources": { "type": "boolean", "description": "Cite the file each result came from. Defaults to true.", "default": true } }, "additionalProperties": false, "required": [ "query" ] }, "SearchSource": { "type": "object", "properties": { "fileId": { "type": "string", "example": "doc_9f2k1x8b3m7q0v", "description": "Id of the file this result came from." }, "path": { "type": "string", "example": "/support/policies/refunds.md", "description": "Where the file sits in your context repository." }, "object": { "type": "string", "enum": [ "file" ], "description": "Type discriminator. Always `file`." }, "url": { "type": "string", "example": "/v1/files/doc_9f2k1x8b3m7q0v", "description": "Where to read this file through the API." } }, "required": [ "fileId", "path", "object", "url" ] }, "HybridSearchResultItem": { "type": "object", "properties": { "text": { "type": "string", "example": "# Refunds\nRefunds are available within 30 days.", "description": "The content of the matching file." }, "source": { "description": "Which file this result came from. Absent when `includeSources` is false.", "allOf": [ { "$ref": "#/components/schemas/SearchSource" } ] } }, "required": [ "text" ] }, "HybridSearchResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Type discriminator. Always `list`." }, "url": { "type": "string", "example": "/v1/search/hybrid", "description": "The search this page came from." }, "hasMore": { "type": "boolean", "description": "Always false. A search answers the best matches in one page and has no next page.", "example": false }, "nextCursor": { "type": "string", "nullable": true, "example": null, "description": "Always null. A search has no position to resume from, so there is no cursor to pass back." }, "data": { "description": "Matching files, best match first.", "type": "array", "items": { "$ref": "#/components/schemas/HybridSearchResultItem" } } }, "required": [ "object", "url", "hasMore", "nextCursor", "data" ] }, "RegexSearchRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "An RE2 regular expression, matched line by line. One line, no backreferences, no lookahead or lookbehind.", "example": "refund|return", "maxLength": 1024 }, "limit": { "type": "integer", "description": "Maximum files to return. Defaults to 50.", "minimum": 1, "maximum": 500, "default": 50 }, "includeSources": { "type": "boolean", "description": "Cite the file each result came from. Defaults to true.", "default": true } }, "additionalProperties": false, "required": [ "query" ] }, "RegexMatch": { "type": "object", "properties": { "line": { "type": "number", "example": 42, "description": "Line number in the matching file, starting at 1." }, "text": { "type": "string", "example": "Refunds are available within 30 days.", "description": "The matching line." } }, "required": [ "line", "text" ] }, "RegexSearchResultItem": { "type": "object", "properties": { "matches": { "description": "Lines that match the query.", "type": "array", "items": { "$ref": "#/components/schemas/RegexMatch" } }, "source": { "description": "Which file these lines came from. Absent when `includeSources` is false.", "allOf": [ { "$ref": "#/components/schemas/SearchSource" } ] } }, "required": [ "matches" ] }, "RegexSearchResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Type discriminator. Always `list`." }, "url": { "type": "string", "example": "/v1/search/regex", "description": "The search this page came from." }, "hasMore": { "type": "boolean", "description": "Always false. A search answers the best matches in one page and has no next page.", "example": false }, "nextCursor": { "type": "string", "nullable": true, "example": null, "description": "Always null. A search has no position to resume from, so there is no cursor to pass back." }, "data": { "description": "Files with matching lines.", "type": "array", "items": { "$ref": "#/components/schemas/RegexSearchResultItem" } } }, "required": [ "object", "url", "hasMore", "nextCursor", "data" ] } } } }