Artifacts, Access, and Website Sharing

Artifacts are versioned outputs associated with a workspace. Artifact access and public Website sharing are separate capabilities:

• Access controls who can use an Artifact inside its workspace.
• Sharing explicitly publishes one immutable Website Artifact version for public preview.

Creating or promoting a Website Artifact does not publish it. A user must explicitly share the version, and a public URL is returned only after sharing has reached the published state.

All routes below use the API base URL (https://api.chainabit.com/api/v1), a Bearer token, and an active x-workspace-id header unless noted otherwise.

Artifact visibility

Visibility is an Artifact-level access setting:

Visibility	Who can view the Artifact
private	The creator, workspace administrators, and people with an active explicit access grant.
team	Workspace members, as well as the creator and workspace administrators.
public	Anyone who can reach the public representation, as well as authenticated workspace users.

Visibility controls access to the Artifact. It does not replace explicit Website sharing: a Website Artifact can be available to workspace users while its versions remain unpublished to the public.

Capabilities

• A viewer grant permits viewing but not editing.
• A contributor grant permits viewing and editing.
• Workspace owners and administrators manage explicit access grants.
• The Artifact creator and workspace administrators can manage the public sharing boundary.
• Editing permission alone does not grant permission to publish or unshare another creator's Website Artifact.

Explicit access grants

An explicit grant gives one active workspace member access to an Artifact. The supported permissions are viewer and contributor; an optional expiration can limit how long the grant remains active. A grant does not make an Artifact public.

Access-grant management is restricted to workspace owners and administrators. The target of a grant must be an active member of the workspace. Re-granting the same person updates their permission and expiration.

List grants

GET /artifacts/:artifactId/access-grants

Lists active grants for an Artifact. Requires a workspace owner or admin role. Revoked grants are not included.

curl "$BASE_URL/artifacts/<artifact-id>/access-grants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: <workspace-id>"

The response is wrapped in the standard data envelope. Grant records contain the grant id, artifact_id, workspace_id, grantee_chainer_id, permission, granted_by_chainer_id, expires_at, revoked_at, created_at, and updated_at. Timestamps are ISO 8601 values; an unbounded grant has expires_at: null.

Grant or update access

POST /artifacts/:artifactId/access-grants

Creates a grant, or updates the existing grant for the same recipient. Requires a workspace owner or admin role.

{
  "granteeChainerId": "<chainer-id>",
  "permission": "contributor",
  "expiresAt": "2026-12-31T23:59:59.000Z"
}

permission must be viewer or contributor. expiresAt is optional and must be an ISO 8601 timestamp. The response returns the resulting grant in the standard data envelope.

Common actionable errors include:

• 400 Bad Request when the recipient is not an active workspace member.
• 404 Not Found when the Artifact is not visible in the current workspace.
• 403 Forbidden when the caller is not a workspace owner or administrator.

Revoke access

DELETE /artifacts/:artifactId/access-grants/:granteeChainerId

Revokes the recipient's active grant. Requires a workspace owner or admin role.

curl -X DELETE \
  "$BASE_URL/artifacts/<artifact-id>/access-grants/<chainer-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: <workspace-id>"

On success, the response data is { "revoked": true }. If there is no active grant for that recipient, the API returns 404 Not Found.

Website Artifact sharing

Website sharing applies to one immutable version at a time. The lifecycle is:

1. A Website Artifact and version exists in the workspace.
2. It remains non-public until an authorized user calls the share endpoint.
3. The share initially has state: "pending".
4. When public publication succeeds, the state becomes "published" and the response includes previewOrigin.
5. Calling unshare changes the state to "revoked"; the public link must no longer provide access.

The creator of the Artifact or a workspace administrator can share and unshare. Contributors may edit content when their grant allows it, but cannot change the public security boundary for another creator's Artifact. Only Website Artifact versions in an available version state can be shared; other Artifact kinds are rejected by this operation.

Share a Website version

POST /artifacts/:artifactId/versions/:versionId/share

Starts explicit public sharing for the selected version. No request body is required. The response is the share record in the standard data envelope:

{
  "shareKind": "website_static",
  "state": "pending",
  "publishedAt": null,
  "revokedAt": null
}

Calling the endpoint again is safe: an already published share remains published; other share states can be requested again.

Read share status

Share metadata is included when reading Website versions:

• GET /artifacts/:artifactId/versions
• GET /artifacts/:artifactId/versions/:versionId

The version response includes the canonical artifactShare object:

{
  "artifactShare": {
    "kind": "website_static",
    "state": "published",
    "publishedAt": "2026-08-29T12:00:00.000Z",
    "revokedAt": null,
    "previewOrigin": "https://<returned-public-preview-host>"
  }
}

When no share exists, artifactShare is null. previewOrigin is omitted until the share is published; do not construct or use a public URL for a pending, failed, or revoked share. Treat the returned URL as opaque and use it exactly as provided. The response may also contain the legacy websiteShare representation for clients that already use it; new integrations should use artifactShare.

The share states have these user-facing meanings:

State	Meaning
pending	Sharing was requested, but the public preview is not ready.
published	The version is publicly available and previewOrigin is usable.
failed	Public publication did not complete; no public URL is available.
revoked	Public access was removed; the version is no longer publicly available.

Unshare a Website version

POST /artifacts/:artifactId/versions/:versionId/unshare

Revokes public sharing for the selected version. No request body is required. The returned share record has state: "revoked" and a revokedAt timestamp. Calling unshare again leaves an already revoked share revoked.

Access grants and Website sharing are independent. Granting a teammate viewer or contributor access does not publish a Website version, and unsharing a Website version does not revoke workspace access grants.

Related Artifact reads

Use these authenticated routes to inspect the workspace-visible Artifact and its versions:

Method	Route	Purpose
GET	/artifacts	List Artifacts visible to the current workspace user.
GET	/artifacts/:artifactId	Read one Artifact.
GET	/artifacts/:artifactId/versions	List versions, including Website share metadata for Website Artifacts.
GET	/artifacts/:artifactId/versions/:versionId	Read a version and its files, including Website share metadata when applicable.

Artifact and version identifiers are not standalone authorization credentials: the current workspace context and the caller's current access are evaluated for each request.