Artifacts API: integration guide

​

Before you start

• API key: send it as a Bearer token in the Authorization header. See Authentication.
• 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.

​

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

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>"}'

{ "grant": [{ "type": "team", "team_id": 87 }, { "type": "user", "email": "cfo@company.com" }] }

{ "base_version": 1, "operations": [{ "op": "replace", "old": "$1.2M", "new": "$1.4M" }] }

​

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 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, with entity_type set to artifact.

​

Errors

{
  "error_code": "ARTIFACT_STALE",
  "message": "Artifact is at version 4, edit was based on 3."
}

​

Limits

​

Endpoints