Files and ingestion

Every file you upload lives in a workspace, at a path you choose. The routes on this page all sit under /v1/workspaces/{workspace_id}. Listing, reading, replacing and deleting files is free and works at any balance.

• Add files with Uploads, passing the workspace's workspace_id. An upload without one goes to the server instead, and isn't part of a workspace. In the dashboard, see Workspaces.
• Use a file in a tool job as a workspace_file source, straight away, when your account owns the workspace. A file in a workspace you were invited into from another account is refused with 422 invalid_source.
• Search only finds a file once it's ingested. See Search.

In the CLI, every command here takes --workspace ID:

• Without it, the CLI uses $NACE_WORKSPACE_ID, then the workspace nace workspace-use saved. With none, the command exits with a usage error that says how to pick one. See Workspaces.
• nace workspace-file and nace workspace-file-delete also take the file as ws:<workspace_id>/<file_id>, which names its workspace too.

List filesCopy Anchor Link

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/files?path_prefix=reports/&ingestion_status=stale" \
  -H "Authorization: Bearer $NACE_API_KEY"

The CLI also takes --all, for every page, and --json, to print the page as JSON.

Each page has:

When nothing was kept from you, as in a workspace without labels, the coverage fields are 0, [] and null.

Read a fileCopy Anchor Link

GET .../files/{file_id} returns the file plus download_url and preview_url: links to its bytes that work without your API key until download_url_expires_at, 15 minutes on. download_url saves the file; preview_url opens it in a browser. A file that doesn't exist, or was deleted, is 404 file_not_found.

curl https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID \
  -H "Authorization: Bearer $NACE_API_KEY"

MetadataCopy Anchor Link

GET .../files/{file_id}/metadata (files.metadata, --metadata) returns what ingestion learned about the file. Most of it is empty until the file is ingested.

VersionsCopy Anchor Link

GET .../files/{file_id}/versions (files.versions, --versions) pages through the file's versions, newest first, with limit and cursor as above. Only the current version's bytes are kept. Each version has:

OutputsCopy Anchor Link

Ingestion turns a file into outputs, listed in its metadata's outputs. Each has output_id, kind, path, generation (the file version it came from) and created_at. Its kind is one of:

Read one output: GET .../files/{file_id}/outputs/{output_id} (files.output) returns a derived_file with download_url, preview_url and download_url_expires_at. Any other kind is 422 invalid_request.

List the files in a folder output, such as a recording's frames: GET .../files/{file_id}/outputs/{output_id}/members (files.output_members, outputMembers in TypeScript). It pages with offset and limit (1 to 200, default 50). A single-file output has no members. It returns:

Replace a fileCopy Anchor Link

PUT .../files/{file_id} gives the file new bytes, at the same path.

• The body is multipart, like an upload: the new bytes in file, and optionally a metadata part with labels, which replaces them ({} clears them). A body that isn't multipart/form-data is 415 unsupported_media_type.
• The answer is 200 with a file_replace job that has already succeeded, with result.file and result.previous_version.
• Up to about 4.5 MB. For a larger file, upload it to the same path instead, as below.
• Not retried: Python's files.replace sends it once unless you pass retry, since a retry after the first one landed would add a second version.

curl -X PUT "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -F file=@report-v2.pdf

After a replace:

• A file that was ingested becomes stale until you ingest it again; one that wasn't stays discovered.
• Jobs that read the file from then on get the new version.

Uploading to the same path with on_conflict: "new_version" does the same; see Same path again. Use that for a file over about 4.5 MB, and in the CLI, which has no replace command.

Delete a fileCopy Anchor Link

DELETE .../files/{file_id} removes the file, its outputs and its search-index entries, and cancels ingestions still running on it. Deleting can't be undone.

• The answer is 202 with a file_delete job, or 200 when it finishes within wait_seconds.
• Waiting and retries: like ingestion, it takes ?wait_seconds (capped at 60) and an Idempotency-Key. It has no body.

curl -X DELETE "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID" \
  -H "Authorization: Bearer $NACE_API_KEY"

The job's result has file_id, the counts of what was deleted (outputs_deleted, index_documents_deleted), jobs_cancelled and verified, which is true once every trace is confirmed gone.

Ingest filesCopy Anchor Link

Ingestion reads your files and builds what search needs: the search index, metadata and outputs. It's the only call that makes files searchable. Upload a batch first, then ingest it in one run.

curl https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/ingestions \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ingest-reports-2026-10" \
  -d '{ "selection": { "type": "path_prefix", "path_prefix": "reports/", "stale_only": true } }'

• In the API, selection is required: {"type": "file_ids", "file_ids": [...]} or {"type": "path_prefix", "path_prefix": "reports/"}.
• In the SDKs and the CLI, pass file ids or a path prefix, not both. With neither, the whole workspace is ingested.

What comes back:

• The answer is 202 with an ingestion job, or 200 when it finishes within wait_seconds. Read it as in Jobs and results.
• Waiting and retries: it takes ?wait_seconds=N (0 to 60; more waits 60) and an Idempotency-Key. Retry identical inputs with the same key to get the original job; use a new key for a changed selection. Changed inputs are not a supported retry: they may replay an earlier job or be rejected.
• One bad file doesn't fail the run: the job succeeds, and its result reports each file.

Search reads only what ingestion built, so it misses any file that isn't ingested.

Ingestion statusCopy Anchor Link

Each file's ingestion_status says where it stands, and the workspace's stats count them in files_by_ingestion_status, so you can tell what needs ingesting without listing every file.

The workspace file objectCopy Anchor Link