Artifacts API Endpoints

REST API endpoints for managing generated artifacts.

List Artifacts

Get all artifacts for a user.

GET /api/v1/artifacts

Query Parameters

Example

curl "https://clanker.net/api/v1/artifacts?limit=10" \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

When paginated (with limit or offset):

{
  "items": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "skillSlug": "readme-generator",
      "skillName": "README Generator",
      "title": "README.md",
      "fileType": "text/markdown",
      "artifactType": "output",
      "inputText": "Create a README for my TypeScript CLI",
      "contentSize": 2048,
      "createdSkillSlug": null,
      "metadata": null,
      "isInstalled": false,
      "bundleType": null,
      "status": "completed",
      "cost": 45,
      "executionTimeMs": 30000,
      "createdAt": "2024-01-15T10:31:30.000Z",
      "isPublic": false,
      "fileList": [{ "path": "README.md", "size": 2048 }]
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0,
  "hasMore": true
}

Without limit the response is a bare array of the same objects — no envelope, no total. Artifact ids are UUIDs.

Get Artifact

Get details of a specific artifact.

GET /api/v1/artifacts/:id

Example

curl https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "skillSlug": "readme-generator",
  "skillName": "README Generator",
  "title": "README.md",
  "fileType": "text/markdown",
  "artifactType": "output",
  "inputText": "Create a README for my TypeScript CLI",
  "contentSize": 2048,
  "createdSkillSlug": null,
  "metadata": null,
  "isInstalled": false,
  "bundleType": null,
  "status": "completed",
  "cost": 45,
  "executionTimeMs": 30000,
  "createdAt": "2024-01-15T10:31:30.000Z",
  "content": "# My Project\n\n...",
  "isPublic": false
}

The detail response carries content (the artifact’s text, read from storage) but not fileList — for the per-file view of a bundle, read the manifest below.

Get Artifact Manifest

Get the file manifest for a multi-file artifact.

GET /api/v1/artifacts/:id/manifest

Example

curl https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab/manifest \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

{
  "version": "1",
  "bundleType": "directory",
  "files": [
    {
      "path": "README.md",
      "checksum": "9f1c2a80…",
      "size": 2048,
      "mimeType": "text/markdown"
    },
    {
      "path": "CONTRIBUTING.md",
      "checksum": "4d5e6f70…",
      "size": 1024,
      "mimeType": "text/markdown"
    }
  ],
  "createdAt": "2024-01-15T10:31:30.000Z"
}

404 NOT_FOUND when the artifact has no stored manifest — single-file artifacts generally do not.

Download Artifact

Download the artifact file(s).

GET /api/v1/artifacts/:id/download

Example

curl -O https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab/download \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

Returns the file content with appropriate Content-Type and Content-Disposition headers.

For multi-file artifacts, returns a ZIP archive.

Get Raw Artifact Content

Get the raw text content of an artifact (for text-based files).

GET /api/v1/artifacts/:id/raw

Example

curl https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab/raw \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

Returns plain text content with Content-Type: text/plain.

Get Artifact File

Get a specific file from a multi-file artifact.

GET /api/v1/artifacts/:id/file/:path

Example

curl https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab/file/src/index.ts \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

Returns the file content with appropriate Content-Type.

Delete Artifact

Permanently delete an artifact.

DELETE /api/v1/artifacts/:id

Example

curl -X DELETE https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

{
  "success": true
}

Errors

Shape note: this route answers failures in the pre-envelope shape, { "error": "<message>", "isRunning": false }, where error is a string rather than the usual { code, message } object. Read it defensively.

Publish an Artifact

Copy an artifact’s files to the public registry path and mark it public. Owner or admin only.

POST /api/v1/artifacts/:id/publish

Example

curl -X POST https://clanker.net/api/v1/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab/publish \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

Response

{
  "publicUrl": "https://registry.example/artifacts/a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "filesCopied": 3
}

Unpublish an Artifact

Flip an artifact back to private. Owner or admin only.

POST /api/v1/artifacts/:id/unpublish

{ "success": true }