Artifacts API¶

List, download, publish, and restore artifacts. See Artifacts.

Paths are relative to https://<your-atlas-host>/api/v1. For the API key and headers every request needs, see Authentication.

Endpoint	What it does
GET /artifacts/	List artifacts in the workspace
GET /artifacts/{artifact_id}	Get an artifact by ID
DELETE /artifacts/{artifact_id}	Delete an artifact
GET /artifacts/{artifact_id}/download	Raw stored bytes for an artifact (JSON wrapper for presentations)
POST /artifacts/{artifact_id}/publish	Make an artifact public, or restart an already-public link’s lifetime
POST /artifacts/{artifact_id}/unpublish	Take an artifact’s public link down
GET /artifacts/{artifact_id}/versions	List an artifact’s saved versions
POST /artifacts/{artifact_id}/versions/{version}/restore	Restore an earlier version of an artifact

List artifacts¶

GET /artifacts/

List artifacts in the workspace.

Parameters

Name	In	Type	Description
`artifact_type`	query	string	`presentation`, `csv`, `markdown` or `mini_data_app` (a data app).
`status`	query	`public`, `workspace`, `shared`, `draft` or string	Sharing state: `public` (anyone with the link; `published` is an alias), `workspace`, `shared` (invited people), or `draft`.
`q`	query	string	Case-insensitive search on the title.
`sort`	query	string	`created` (newest first), `created_asc`, `name`, `name_desc`, `type`.
`limit`	query	integer
`offset`	query	integer

Response A list of objects:

Field	Type	Description
`id`	UUID
`title`	string
`artifact_type`	string
`mime_type`	string
`file_size`	integer
`version`	integer
`metadata`	object
`visibility`	`restricted`, `workspace`, `public`	`restricted` (owner and invited people), `workspace`, or `public` (anyone with the link).
`share_token`	string	The secret part of the public link.
`shared_at`	datetime
`share_expires_at`	datetime	When the public link expires; `null` means it does not.
`shared_by_email`	string
`public_query_service_account_id`	UUID
`active_share_count`	integer	People with a pending or accepted invitation.
`workspace_id`	UUID
`workspace_display_name`	string
`conversation_id`	UUID
`created_by_email`	string
`created_at`	datetime
`updated_at`	datetime

Get artifact¶

GET /artifacts/{artifact_id}

Get an artifact by ID.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`title`	string
`artifact_type`	string
`mime_type`	string
`file_size`	integer
`version`	integer
`metadata`	object
`visibility`	`restricted`, `workspace`, `public`	`restricted` (owner and invited people), `workspace`, or `public` (anyone with the link).
`share_token`	string	The secret part of the public link.
`shared_at`	datetime
`share_expires_at`	datetime	When the public link expires; `null` means it does not.
`shared_by_email`	string
`public_query_service_account_id`	UUID
`active_share_count`	integer	People with a pending or accepted invitation.
`workspace_id`	UUID
`workspace_display_name`	string
`conversation_id`	UUID
`created_by_email`	string
`created_at`	datetime
`updated_at`	datetime

Delete artifact¶

DELETE /artifacts/{artifact_id}

Delete an artifact.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Response

The raw file content.

Download artifact¶

GET /artifacts/{artifact_id}/download

Raw stored bytes for an artifact (JSON wrapper for presentations).

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Response

The raw file content.

Publish artifact¶

POST /artifacts/{artifact_id}/publish

Make an artifact public, or restart an already-public link’s lifetime.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Request body

Field	Type	Description
`ttl_days`	integer	Days until the public link expires; defaults to 30. Publishing again restarts the countdown.

Response

Field	Type	Description
`id`	UUID
`title`	string
`artifact_type`	string
`mime_type`	string
`file_size`	integer
`version`	integer
`metadata`	object
`visibility`	`restricted`, `workspace`, `public`	`restricted` (owner and invited people), `workspace`, or `public` (anyone with the link).
`share_token`	string	The secret part of the public link.
`shared_at`	datetime
`share_expires_at`	datetime	When the public link expires; `null` means it does not.
`shared_by_email`	string
`public_query_service_account_id`	UUID
`active_share_count`	integer	People with a pending or accepted invitation.
`workspace_id`	UUID
`workspace_display_name`	string
`conversation_id`	UUID
`created_by_email`	string
`created_at`	datetime
`updated_at`	datetime

Unpublish artifact¶

POST /artifacts/{artifact_id}/unpublish

Take an artifact’s public link down.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Response

Field	Type	Description
`id`	UUID
`title`	string
`artifact_type`	string
`mime_type`	string
`file_size`	integer
`version`	integer
`metadata`	object
`visibility`	`restricted`, `workspace`, `public`	`restricted` (owner and invited people), `workspace`, or `public` (anyone with the link).
`share_token`	string	The secret part of the public link.
`shared_at`	datetime
`share_expires_at`	datetime	When the public link expires; `null` means it does not.
`shared_by_email`	string
`public_query_service_account_id`	UUID
`active_share_count`	integer	People with a pending or accepted invitation.
`workspace_id`	UUID
`workspace_display_name`	string
`conversation_id`	UUID
`created_by_email`	string
`created_at`	datetime
`updated_at`	datetime

List artifact versions¶

GET /artifacts/{artifact_id}/versions

List an artifact’s saved versions.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes

Response

The raw file content.

Restore artifact version¶

POST /artifacts/{artifact_id}/versions/{version}/restore

Restore an earlier version of an artifact.

Parameters

Name	In	Type	Required
`artifact_id`	path	UUID	Yes
`version`	path	integer	Yes

Response

Field	Type	Description
`id`	UUID
`title`	string
`artifact_type`	string
`mime_type`	string
`file_size`	integer
`version`	integer
`metadata`	object
`visibility`	`restricted`, `workspace`, `public`	`restricted` (owner and invited people), `workspace`, or `public` (anyone with the link).
`share_token`	string	The secret part of the public link.
`shared_at`	datetime
`share_expires_at`	datetime	When the public link expires; `null` means it does not.
`shared_by_email`	string
`public_query_service_account_id`	UUID
`active_share_count`	integer	People with a pending or accepted invitation.
`workspace_id`	UUID
`workspace_display_name`	string
`conversation_id`	UUID
`created_by_email`	string
`created_at`	datetime
`updated_at`	datetime

What’s next?¶

API overview: authentication, worked examples, and error handling
Webhooks: get events pushed to your systems instead of polling
Service accounts: create the key an integration uses