Publish Artifact

`POST /v1/artifacts/{id}/publish`

Publishes an artifact as a page at https://artifacta.io/a/{slug}. The slug is minted on the first publish and stays stable across re-publishes. Calling this endpoint again on the same artifact upserts the existing page and keeps the same URL — it is safe to call repeatedly. Publishing is a lifecycle transition and does not increment the monthly request counter.

Authentication

Requires a Bearer token. See Authentication.

Path parameters

Parameter	Type	Description
`id`	string	Artifact ID (`art_...`)

Request body

{
  "visibility": "unlisted",
  "access": "none",
  "title": "Q2 Report"
}

Field	Type	Required	Description
`visibility`	string	Yes	`"unlisted"` — accessible by URL only. `"public"` — discoverable.
`access`	string	No	`"none"` (default) — open. `"password"` — password-protected (Pro plan).
`title`	string	No	Page title shown in the viewer header.
`password`	string	Conditional	Required when `access="password"`. Argon2id-hashed server-side. Pro plan only. Not available for HTML content types.

Response

{
  "page_id": "pg_aB3xK9mP1qR5sT2u",
  "public_url": "https://artifacta.io/a/pg_aB3xK9mP1qR5sT2u",
  "visibility": "unlisted",
  "access": "none"
}

Field	Type	Description
`page_id`	string	Page slug (`pg_...`). Stable across re-publishes.
`public_url`	string	Full viewer URL. Anyone with this URL can view the artifact.
`visibility`	string	Echo of the requested visibility.
`access`	string	Echo of the requested access mode.

Error codes

Code	Status	When
`artifact_not_found`	404	Artifact ID does not exist or belongs to another tenant.
`artifact_already_deleted`	410	Artifact has been soft-deleted.
`artifact_expired`	410	Artifact has passed its TTL.
`quota_exceeded`	403	`access="password"` on a Free-tier account, or monthly request quota reached.
`invalid_request`	400	Missing `visibility`, invalid field value, or `access="password"` for HTML content type.

Notes

HTML and passwords: access="password" is rejected for text/html or application/xhtml+xml artifacts — there is no safe gated render path for HTML in the current viewer.
Re-publish: Calling publish again on the same artifact updates the page title, visibility, and access, keeping the existing page_id and URL.
page field on artifacts: After a successful publish, GET /v1/artifacts/{id} returns a page sub-object on the artifact — see the artifact response page field.

Example

curl -X POST https://api.artifacta.io/v1/artifacts/art_abc123/publish \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"visibility": "unlisted", "title": "Q2 Analysis"}'

API Reference

Artifact Pages

`POST /v1/artifacts/{id}/publish`

Authentication

Path parameters

Request body

Response

Error codes

Notes

Example

​POST /v1/artifacts/{id}/publish

​Authentication

​Path parameters

​Request body

​Response

​Error codes

​Notes

​Example

`POST /v1/artifacts/{id}/publish`

Authentication

Path parameters

Request body

Response

Error codes

Notes

Example