Artifacts API

Overview

The Artifacts API stores user-owned content artifacts in a local SQLite database. Each artifact belongs to a workspace, carries a status (for example draft or final), supports tags, and is composed of ordered sections. Every update creates a revision snapshot so changes remain auditable.

This namespace is served by the Allternit API data-plane node (http://127.0.0.1:8013 on the same machine, or your paired or provisioned node). The hosted Cloud API at https://api.allternit.com does not route it; it relays only agent sessions, canvases, office and beta research/sessions. See Cloud API. The account-level store every surface shares is Artifacts v2, served by the Cloud API under /api/v2/artifacts.

Base URL

http://127.0.0.1:8013/api

Authentication

All requests require a valid bearer token in the Authorization header. See Authentication for details.

Artifact object

Field	Type	Description
`id`	string	Unique artifact identifier.
`user_id`	string	Owner identifier.
`workspace_id`	string	Workspace the artifact belongs to.
`title`	string	Artifact title.
`type`	string	Artifact type, defaults to `document`.
`status`	string	Current status, e.g. `draft`, `final`.
`summary`	string \| null	Short summary.
`tags`	string[]	Normalized tag list.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 update timestamp.
`sections`	object[]	Ordered section objects.
`revisions`	object[]	Historical snapshots.

Section object

Field	Type	Description
`id`	string	Unique section identifier.
`artifact_id`	string	Parent artifact id.
`heading`	string	Section heading.
`kind`	string	Section mime-style kind, e.g. `document/markdown`.
`body`	string	Section body content.
`position`	integer	Ordering index.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

Endpoints

Method	Path	Description
`GET`	`/artifacts`	List artifacts for the authenticated user.
`POST`	`/artifacts`	Create a new artifact.
`GET`	`/artifacts/:id`	Get an artifact with sections and revisions.
`PATCH`	`/artifacts/:id`	Update artifact metadata.
`DELETE`	`/artifacts/:id`	Delete an artifact.
`GET`	`/artifacts/search`	Search across titles, summaries, tags, and sections.
`GET`	`/artifacts/stats`	Per-workspace artifact counts.
`GET`	`/artifacts/:id/revisions`	List revision snapshots.
`GET`	`/artifacts/:id/sections`	List sections.
`POST`	`/artifacts/:id/sections`	Add a section.
`PATCH`	`/artifacts/:id/sections/:section_id`	Update a section.
`DELETE`	`/artifacts/:id/sections/:section_id`	Delete a section.
`PATCH`	`/artifacts/:id/sharing`	Update sharing. Body: `visibility` (string, required) and optional `access`.

List artifacts

curl "http://127.0.0.1:8013/api/artifacts?workspaceId=ws_01hqx8x7x7x7x7x7x7x7x7x&status=draft&type=document" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

Parameter	Type	Description
`workspaceId`	string	Filter by workspace.
`status`	string	Filter by status.
`type`	string	Filter by artifact type.
`_q`	string	Reserved generic search parameter.

Response

{
  "artifacts": [
    {
      "id": "art_01hqx8x7x7x7x7x7x7x7x7x",
      "user_id": "user_2d9e...",
      "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
      "title": "ACI Design Doc",
      "type": "document",
      "status": "draft",
      "summary": "Initial architecture for the ACI surface.",
      "tags": ["aci", "design"],
      "created_at": "2026-08-13T18:00:00Z",
      "updated_at": "2026-08-13T18:05:00Z",
      "sections": [],
      "revisions": []
    }
  ]
}

Create artifact

curl -X POST http://127.0.0.1:8013/api/artifacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
    "title": "BYOC Deployment Runbook",
    "type": "document",
    "status": "draft",
    "summary": "Step-by-step BYOC deployment guide.",
    "tags": ["byoc", "ops"],
    "sections": [
      {
        "heading": "Prerequisites",
        "kind": "document/markdown",
        "body": "- Allternit Factory installed\n- BYOC token",
        "position": 0
      }
    ]
  }'

Request body

Field	Type	Required	Description
`workspace_id`	string	yes	Workspace identifier.
`title`	string	yes	Artifact title.
`type`	string	no	Artifact type, default `document`.
`status`	string	no	Status, default `draft`.
`summary`	string	no	Optional summary.
`tags`	array	no	Tag list.
`sections`	object[]	no	Initial sections.

Response

{
  "artifact": {
    "id": "art_02hqx8x7x7x7x7x7x7x7x7x",
    "user_id": "user_2d9e...",
    "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
    "title": "BYOC Deployment Runbook",
    "type": "document",
    "status": "draft",
    "summary": "Step-by-step BYOC deployment guide.",
    "tags": ["byoc", "ops"],
    "created_at": "2026-08-13T18:00:00Z",
    "updated_at": "2026-08-13T18:00:00Z",
    "sections": [
      {
        "id": "sec_01hqx8x7x7x7x7x7x7x7x7x",
        "artifact_id": "art_02hqx8x7x7x7x7x7x7x7x7x",
        "heading": "Prerequisites",
        "kind": "document/markdown",
        "body": "- Allternit Factory installed\n- BYOC token",
        "position": 0,
        "created_at": "2026-08-13T18:00:00Z",
        "updated_at": "2026-08-13T18:00:00Z"
      }
    ],
    "revisions": [
      {
        "id": "rev_01hqx8x7x7x7x7x7x7x7x7x",
        "artifact_id": "art_02hqx8x7x7x7x7x7x7x7x7x",
        "reason": "created",
        "snapshot": { "title": "BYOC Deployment Runbook", ... },
        "created_at": "2026-08-13T18:00:00Z"
      }
    ]
  }
}

Update artifact

curl -X PATCH http://127.0.0.1:8013/api/artifacts/art_02hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "final",
    "tags": ["byoc", "ops", "approved"]
  }'

Response

{
  "artifact": {
    "id": "art_02hqx8x7x7x7x7x7x7x7x7x",
    "status": "final",
    "tags": ["byoc", "ops", "approved"],
    ...
  }
}

Search artifacts

curl "http://127.0.0.1:8013/api/artifacts/search?q=BYOC&workspaceId=ws_01hqx8x7x7x7x7x7x7x7x7x" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "artifacts": [
    {
      "id": "art_02hqx8x7x7x7x7x7x7x7x7x",
      "title": "BYOC Deployment Runbook",
      ...
    }
  ]
}

Artifact stats

curl http://127.0.0.1:8013/api/artifacts/stats \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "stats": [
    {
      "workspace_id": "ws_01hqx8x7x7x7x7x7x7x7x7x",
      "total": 12,
      "drafts": 8,
      "final": 4,
      "updated_at": "2026-08-13T18:05:00Z"
    }
  ]
}

Add a section

curl -X POST http://127.0.0.1:8013/api/artifacts/art_02hqx8x7x7x7x7x7x7x7x7x/sections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "heading": "Rollback",
    "kind": "document/markdown",
    "body": "1. Drain sessions\n2. Restore snapshot",
    "position": 1
  }'

Response

{
  "section": {
    "id": "sec_02hqx8x7x7x7x7x7x7x7x7x",
    "artifact_id": "art_02hqx8x7x7x7x7x7x7x7x7x",
    "heading": "Rollback",
    "kind": "document/markdown",
    "body": "1. Drain sessions\n2. Restore snapshot",
    "position": 1,
    "created_at": "2026-08-13T18:10:00Z",
    "updated_at": "2026-08-13T18:10:00Z"
  }
}

Error codes

Status	Code	Description
`400`	`workspace_id and title are required`	Missing required creation fields.
`400`	`heading is required`	Section heading missing.
`401`	`Unauthorized`	Missing or invalid bearer token.
`404`	`Artifact not found` / `Section not found`	Resource not found.
`500`	`internal_error`	Database or server error.

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Artifact object

Section object

Endpoints

List artifacts

Query parameters

Response

Create artifact

Request body

Response

Update artifact

Response

Search artifacts

Response

Artifact stats

Response

Add a section

Response

Error codes

​Overview

​Base URL

​Authentication

​Artifact object

​Section object

​Endpoints

​List artifacts

​Query parameters

​Response

​Create artifact

​Request body

​Response

​Update artifact

​Response

​Search artifacts

​Response

​Artifact stats

​Response

​Add a section

​Response

​Error codes

​Related pages

Overview

Base URL

Authentication

Artifact object

Section object

Endpoints

List artifacts

Query parameters

Response

Create artifact

Request body

Response

Update artifact

Response

Search artifacts

Response

Artifact stats

Response

Add a section

Response

Error codes

Related pages