> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts API: integration guide

> Generate, version and share Artifacts from your own systems: recurring reports, dashboards and announcements published through the API, under the same rules as the app.

The Artifacts API lets your systems produce and distribute deliverables in Tess without going through chat. A BI pipeline can generate the weekly leadership report, a CRM can publish a proposal for the sales team, and a monthly job can refresh the KPI dashboard, always at the same link and with version history.

The API follows the same rules as the app: ownership, plan and role permissions, and the sharing restrictions set by the admin. Nothing the API does bypasses workspace governance.

For an overview of the feature, see [Artifacts](https://docs.tess.im/en/html-artifacts.md).

## Before you start

* **API key:** send it as a Bearer token in the `Authorization` header. See [Authentication](https://docs.tess.im/en/api-quickstart.md).
* **Workspace:** the `x-workspace-id` header is required on every call. Without it, the response is `403`.
* **Permissions:** actions depend on the feature being enabled and on the plan and role of the user who owns the key.

| Permission | What it allows |
| - | - |
| Artifacts User | Create, edit, restore, rename, share and delete your own Artifacts |
| Workspace content deletion | Required, together with Artifacts User, to delete an Artifact or a version |
| Artifacts Manager | Read any Artifact in the workspace (recorded in the audit log) and unpublish any of them |

## Concepts

* **Owner:** the person who creates the Artifact. Only the owner changes, publishes and shares it. Others get `404` (they cannot tell the Artifact exists) or `403 ARTIFACT_EDIT_FORBIDDEN` (they can read it but not change it).
* **Latest version (`head_version`):** every edit or restore creates a new version. Edits always start from the latest one.
* **Shared version (`shared_version`):** the version people with access see. It changes when you publish another version, on the first share (which publishes the latest version), when the shared version is deleted (it falls back to the newest earlier one), and when you unpublish (it becomes null). Edits never change it, so you can review before releasing.
* **Link (`viewer_url`):** the Artifact's address in Tess. It stays the same across versions and requires a Tess login, including for public access.

## Integration flow

**1. Pick a template (optional)**

[List Artifact Templates](https://docs.tess.im/en/list-artifact-templates.md) returns the global templates plus the workspace's own; when the slug is the same, the workspace one wins. Without a choice, creation uses `default`, with the Tess visual identity.

**2. Create the Artifact**

[Create Artifact](https://docs.tess.im/en/create-artifact.md) takes the title and the body HTML, with optional CSS and JavaScript. The response returns `universal_id`, version 1 and `viewer_url`. The Artifact starts private.

```bash theme={null}
curl --request POST \
  --url 'https://api.tess.im/artifacts' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --data '{"title": "Weekly pipeline", "lang": "en", "content": "<h1>Weekly pipeline</h1><p>Open pipeline: $1.2M</p>"}'
```

**3. Share with the right audience**

[Share Artifact](https://docs.tess.im/en/share-artifact.md) grants access to people, teams, the workspace or anyone signed in to Tess. The first grant publishes the current version.

```json theme={null}
{ "grant": [{ "type": "team", "team_id": 87 }, { "type": "user", "email": "cfo@company.com" }] }
```

**4. Update without changing the link**

On the next cycle, use [Edit Artifact](https://docs.tess.im/en/edit-artifact.md) with `base_version` to apply the changes. The new version does not reach people with access (only the owner and managers with Artifacts Manager see the latest version) until you call [Publish Artifact Version](https://docs.tess.im/en/publish-artifact.md).

```json theme={null}
{ "base_version": 1, "operations": [{ "op": "replace", "old": "$1.2M", "new": "$1.4M" }] }
```

**5. Control the history**

[List Artifact Versions](https://docs.tess.im/en/list-artifact-versions.md) shows the latest and the shared version. To roll back, use [Restore Artifact Version](https://docs.tess.im/en/restore-artifact-version.md) and publish the restored version.

> [!TIP]
>
> For recurring material, store the `universal_id` and edit the same Artifact every cycle. The link sent to leadership never changes, and the history shows how the numbers evolved.

## Sharing and governance

* Granting access follows the user's restrictions, set by the admin on the Members page. By default, organization, workspace and teams are allowed and public access is not.
* People can only be added if they are active members of the workspace or the organization.
* A share call is all or nothing: if one target is rejected, nothing is written and the response lists `rejected_targets`.
* [Unpublish Artifact](https://docs.tess.im/en/unpublish-artifact.md) removes every grant at once. When a manager unpublishes, the owner cannot publish again.
* Permissions are checked on every view: anyone who leaves the workspace or loses a sharing level loses access immediately.
* On the Enterprise plan, changes made through the API (create, edit, publish, share, delete) also appear in [Audit Events](https://docs.tess.im/en/audit-events.md), with `entity_type` set to `artifact`.

## Errors

Artifact-specific errors return a stable code in `error_code` and an explanation in `message`. Validation, workspace, rate-limit, and content-deletion errors return only `message` (validation also includes `errors`). Example:

```json theme={null}
{
  "error_code": "ARTIFACT_STALE",
  "message": "Artifact is at version 4, edit was based on 3."
}
```

| Status | Meaning |
| - | - |
| `403` | No permission for the action (feature off, plan, role, content deletion), missing workspace or one you are not a member of, publication revoked by a manager (`ARTIFACT_PUBLICATION_REVOKED`), or you can read the Artifact but are not its owner |
| `404` | The Artifact, version or template does not exist, or does not belong to you; or the given workspace does not exist |
| `409` | `ARTIFACT_STALE`: the latest version changed since `base_version`. Read again and retry |
| `422` | Invalid data, an edit that does not apply, or a rejected share target |
| `429` | Rate limit reached |

Each endpoint page lists its codes. For general API statuses, see [Errors](https://docs.tess.im/en/errors.md).

## Limits

| Item | Limit |
| - | - |
| Reads (`GET`) | 600 per minute per user, counted together with app usage |
| Writes | 120 per minute per user, counted together with app usage |
| Operations per edit | 40 |
| Text of one edit | 12,000 characters, summing every field of every operation (anchors and selectors included) |
| Artifact content | 2,000,000 characters |
| `styles` and `script` on create | 500,000 characters each |
| Targets per share call | 50 in `grant` and 50 in `revoke` |

> [!WARNING]
>
> Content is static: the page script has no network access. To update numbers, edit the Artifact with the new data and publish the version.

## Endpoints

> [card] [List Artifacts](https://docs.tess.im/en/list-artifacts.md)
>
> Your Artifacts in the workspace, paginated.

> [card] [Create Artifact](https://docs.tess.im/en/create-artifact.md)
>
> Version 1 from a template.

> [card] [Get Artifact](https://docs.tess.im/en/get-artifact.md)
>
> Latest version with its HTML.

> [card] [Edit Artifact](https://docs.tess.im/en/edit-artifact.md)
>
> Patch operations that create a new version.

> [card] [Publish version](https://docs.tess.im/en/publish-artifact.md)
>
> Sets the version people see.

> [card] [Share Artifact](https://docs.tess.im/en/share-artifact.md)
>
> Grants and revokes access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.