---
title: "Replace a workspace file"
method: PUT
path: "/v1/workspaces/{id}/files/{file_id}"
tags: ["Workspaces"]
---

# Replace a workspace file

`PUT /v1/workspaces/{id}/files/{file_id}`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/workspaces/{id}/files/{file_id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/workspaces/:id/files/:file_id/put.ts> (a function with typed inputs; its response is checked against the schema)

New bytes for the file, at the same path, as multipart form data. The request goes through Drex, so it is limited to about 4.5 MB; upload a larger file to the same path with `on_conflict: "new_version"` instead. Free.

## Path parameters

- `id` string, required
- `file_id` string, required

## Request body `multipart/form-data`

- object
  - `file` string, binary, required
  - `metadata` string: JSON: `labels` (replaces them; `{}` clears) and `graph_inclusion` (`auto`, `include` or `exclude`).

## Response `200`

The `file_replace` job, already succeeded, with `result.file` and `result.previous_version`.

- WorkspaceJob: A job in a workspace (an ingestion, reconciliation, knowledge-graph build, automatic search, QA turn, file replace or delete, or workspace delete), passed through from the document service. Read it again with `GET /v1/documents/jobs/{id}`.
  - `job_id` string, uuid, required
  - `kind` string, required: The document service's job kind, such as `ingestion`, `reconciliation`, `kg_build`, `intelligent_search` (automatic search), `automatic_agent` (QA), `file_replace`, `file_delete` or `workspace_delete`.
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
  - `workspace_id` string
  - `result` unknown

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `404`: No such workspace (`workspace_not_found`) or file (`file_not_found`).
- `415`: The body is not multipart form data (`invalid_request_error`).
- `422`: The body or a parameter is invalid, or the document service refused it (`invalid_request_error`).
- `429`: Over the account's requests per minute for document routes, or the document service is throttling this account (`rate_limit_error`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable (`service_unavailable`).

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)