Workspace files

client.workspaces.files lists, reads, replaces and deletes the files you uploaded to a workspace. To make them searchable, use client.workspaces.ingest.

Arguments: every method takes the workspace_id first, and the file methods take the file_id next.
A missing file: one that doesn't exist, or was deleted, raises NaceNotFoundError (file_not_found).
Cost: listing, reading, replacing and deleting files is free, at any balance.

See List files in the API reference.

List workspace files

client.workspaces.files.list(workspace_id, **options)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`path_prefix`	`str`	No	Only files whose path starts with this.
`ingestion_status`	`list[str]`	No	Only files in these ingestion statuses: `discovered`, `queued`, `ingesting`, `ingested`, `stale`, `expired`, `failed` or `not_required`.
`categories`	`list[str]`	No	Only files in these categories, set by ingestion.
`file_types`	`list[str]`	No	Only these extensions, such as `pdf` or `xlsx`.
`modified_after`	`str \| datetime`	No	Only files whose `updated_at` falls after this time. A `datetime` is sent in ISO 8601; give it a time zone.
`modified_before`	`str \| datetime`	No	Only files whose `updated_at` falls before this time.
`limit`	`int`	No	1 to 200. Default: `50`.
`cursor`	`str`	No	The previous page's `next_cursor`. Keep going until it's `None`.

It returns a WorkspaceFilePage. A filter that takes a list keeps a file matching any of its values.

list_files.py

page = client.workspaces.files.list(workspace_id, path_prefix="reports/", ingestion_status=["stale"])
for file in page.items:
    print(file.path, file.ingestion_status)

Read a workspace file

client.workspaces.files.get(workspace_id, file_id)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.

It returns a WorkspaceFileDetail: the file, plus download_url and preview_url, links to its bytes that work without your API key for 15 minutes.

get_file.py

file = client.workspaces.files.get(workspace_id, file_id)
print(file.path, file.download_url)

File metadata

client.workspaces.files.metadata(workspace_id, file_id)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.

It returns a WorkspaceFileMetadata: what ingestion learned about the file, its outputs, and whether each representations entry is current. Most of it is empty until the file is ingested. See Read a file's metadata.

file_metadata.py

metadata = client.workspaces.files.metadata(workspace_id, file_id)
print(metadata.lane, metadata.representations, len(metadata.outputs))

File versions

client.workspaces.files.versions(workspace_id, file_id, **options)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.
`limit`	`int`	No	1 to 200. Default: `50`.
`cursor`	`str`	No	The previous page's `next_cursor`.

It returns a WorkspaceFileVersionPage: the file's versions, newest first. Only the current version's bytes are kept.

file_versions.py

for version in client.workspaces.files.versions(workspace_id, file_id).items:
    print(version.version, version.size_bytes, version.is_current)

Replace a workspace file

client.workspaces.files.replace(workspace_id, file_id, content, *, file_name=None, labels=None)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file. Its path stays the same.
`content`	`str \| PathLike \| bytes \| BinaryIO`	Yes	The new bytes: a path, bytes, or an open binary file.
`file_name`	`str`	For bytes and nameless streams	The name sent with the bytes. Default: the name of the path or stream. Bytes without it raise `ValueError`.
`labels`	`dict[str, str]`	No	Your own key-value metadata, replacing the file's. `{}` clears it. Default: keep them.

It returns a DocumentJob that has already succeeded, with result["file"] and result["previous_version"]. An ingested file becomes stale until you ingest it again. The bytes go through Drex in one request, about 4.5 MB at most; to replace a larger file, upload it to the same path with on_conflict="new_version" instead. A replace isn't retried unless you pass retry, since a retry after the first one landed would add a second version. See Replace a file.

replace_file.py

job = client.workspaces.files.replace(workspace_id, file_id, "report-v2.pdf")
print(job.result["file"]["version"])

Delete a workspace file

client.workspaces.files.delete(workspace_id, file_id, **options)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.
`wait_seconds`	`int`	No	0 to 60. Default: `None`, which returns at once.
`idempotency_key`	`str`	No	Up to 200 characters. Default: one minted per call.

It returns a DocumentJob of kind file_delete. It removes the file, its outputs and its search-index entries, cancels ingestions still running on it, and can't be undone.

delete_file.py

done = client.jobs.wait(client.workspaces.files.delete(workspace_id, file_id).job_id)
print(done.result["verified"])

Read an output

client.workspaces.files.output(workspace_id, file_id, output_id)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.
`output_id`	`str`	Yes	A `derived_file` output from the file's metadata. Another kind raises `NaceUnprocessableEntityError`.

It returns a WorkspaceFileOutput, with links to the output's bytes. See Read an output.

file_output.py

output = client.workspaces.files.output(workspace_id, file_id, output_id)
print(output.path, output.download_url)

List output members

client.workspaces.files.output_members(workspace_id, file_id, output_id, **options)

Parameter	Type	Required	Description
`workspace_id`	`str`	Yes	The workspace.
`file_id`	`str`	Yes	The file.
`output_id`	`str`	Yes	A folder output, such as a recording's frames.
`offset`	`int`	No	How many members to skip. Default: `0`.
`limit`	`int`	No	1 to 200. Default: `50`.

It returns a WorkspaceFileOutputMembers: one page of the files inside the output, with links to each. A single-file output has no members.

output_members.py

members = client.workspaces.files.output_members(workspace_id, file_id, output_id, limit=100)
print(members.total_count, len(members.members))

List workspace filesCopy Anchor Link

Read a workspace fileCopy Anchor Link

File metadataCopy Anchor Link

File versionsCopy Anchor Link

Replace a workspace fileCopy Anchor Link

Delete a workspace fileCopy Anchor Link

Read an outputCopy Anchor Link

List output membersCopy Anchor Link

On this page