Skip to main content

​
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

ParameterTypeDescription
idstringArtifact ID (art_...)

​
Request body

{
  "visibility": "unlisted",
  "access": "none",
  "title": "Q2 Report"
}
FieldTypeRequiredDescription
visibilitystringYes"unlisted" — accessible by URL only. "public" — discoverable.
accessstringNo"none" (default) — open. "password" — password-protected (Pro plan).
titlestringNoPage title shown in the viewer header.
passwordstringConditionalRequired 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"
}
FieldTypeDescription
page_idstringPage slug (pg_...). Stable across re-publishes.
public_urlstringFull viewer URL. Anyone with this URL can view the artifact.
visibilitystringEcho of the requested visibility.
accessstringEcho of the requested access mode.

​
Error codes

CodeStatusWhen
artifact_not_found404Artifact ID does not exist or belongs to another tenant.
artifact_already_deleted410Artifact has been soft-deleted.
artifact_expired410Artifact has passed its TTL.
quota_exceeded403access="password" on a Free-tier account, or monthly request quota reached.
invalid_request400Missing 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"}'