> ## Documentation Index > Fetch the complete documentation index at: https://docs.qontext.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace the content of a file > 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. ## OpenAPI ````yaml api-reference/public-api.json PUT /v1/files/{id}/content openapi: 3.0.0 info: title: Qontext API description: Read and write the knowledge a workspace has ingested. version: 1.0.0 contact: {} servers: - url: https://api.qontext.ai description: Production security: [] 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. paths: /v1/files/{id}/content: put: tags: - Files summary: Replace a file's content 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: [] components: schemas: 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 Refunds 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 Refunds 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 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 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 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. ````