Artifacts

Artifacts are non-code deliverables that agents produce during task execution. While code changes land in pull requests, artifacts capture everything else: analysis reports, data exports, executive summaries, curated links, and rich content.

Once shared, an artifact gets a URL that works without authentication — hand a report to stakeholders who don't have a Buildd account, embed a data export link in a Slack thread, or bookmark a summary for later reference.

Artifact Types

Types that work everywhere

Types accepted only at mission or initiative level

These are accepted by POST /api/missions/{id}/artifacts and POST /api/initiatives/{id}/artifacts, but rejected by the worker route with 400 Invalid type. Over MCP that means you must pass missionId or initiativeId; a plain worker-scoped create_artifact with type: "analysis" fails.

Types the MCP tool advertises but no route accepts

All types except link store their content directly in the content field. The link type requires a url parameter, stored in metadata, with optional content for descriptive context.

Artifact Templates

Templates provide JSON schemas for structured artifact output. Workers can discover available templates and use them to produce consistently formatted deliverables.

Available Templates

Discovering Templates

Workers can list available templates via MCP:

buildd action=list_artifact_templates

This returns all template definitions with their JSON schemas, enabling agents to produce structured output that matches the expected format.

Creating Artifacts

From Claude Code (MCP)

With the Buildd MCP server connected, agents create artifacts using the create_artifact action on the buildd tool:

> Summarize the findings from the security audit and create a shareable report

The agent calls buildd with action: "create_artifact" behind the scenes. Because the artifact is private, the MCP server reports its visibility rather than a URL:

Artifact created: "Security Audit Report" (report)
ID: a1b2c3d4-...
Visibility: private (not shared)

A Share URL: line appears here only when the artifact already has a token — for example when an upsert by key matched a previously shared artifact.

MCP Parameters

From the REST API

Create an artifact by POSTing to the worker's artifacts endpoint:

curl -X POST https://buildd.dev/api/workers/{worker-id}/artifacts \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "report",
    "title": "Weekly Performance Report",
    "content": "# Performance Summary\n\n## Key Metrics\n- P95 latency: 142ms (down 12%)\n- Error rate: 0.03%\n- Throughput: 2,400 req/s"
  }'

Response:

{
  "artifact": {
    "id": "a1b2c3d4-...",
    "workerId": "w1x2y3z4-...",
    "type": "report",
    "title": "Weekly Performance Report",
    "content": "# Performance Summary\n\n...",
    "shareToken": null,
    "visibility": "private",
    "metadata": {},
    "createdAt": "2026-02-20T10:30:00Z",
    "shareUrl": null
  }
}

shareToken and shareUrl are null on every fresh create. To get a link, call the share endpoint below with the returned id.

Creating a Link Artifact

Link artifacts require the url field:

curl -X POST https://buildd.dev/api/workers/{worker-id}/artifacts \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "link",
    "title": "Staging Preview",
    "url": "https://staging.example.com/preview/abc123",
    "content": "Deploy preview for the new checkout flow"
  }'

The url is stored in the artifact's metadata.url field and rendered as a clickable link on the share page.

Sharing an artifact

Sharing is a deliberate, separate step. Nothing is public until you take it.

From the dashboard

Open the artifact's page and click Share. The button mints a token, flips visibility to public, and copies the URL. Clicking again after that revokes.

From the API

curl -X POST https://buildd.dev/api/artifacts/{artifact-id}/share \
  -H "Authorization: Bearer bld_xxx"

Response:

{ "shareUrl": "https://buildd.dev/share/xK9mP2qR7vLnW3..." }

The token is a cryptographically random URL-safe string. It is generated once and reused if the artifact is shared again after being revoked, so a previously distributed link starts working again.

Auth accepts either a logged-in dashboard user who is a member of the artifact's workspace, or an API key that owns the artifact (via its worker) or has workspace access. Anything else gets 401 or 403.

Revoking

curl -X DELETE https://buildd.dev/api/artifacts/{artifact-id}/share \
  -H "Authorization: Bearer bld_xxx"

This sets visibility back to private and nulls the token, so the old URL 404s permanently — a later re-share mints a new one.

The share page

https://buildd.dev/share/xK9mP2qR7vLnW3...

The share page renders differently based on artifact type:

• content / report / summary — Rendered as formatted markdown with full styling
• data — Displayed as formatted JSON in a monospace code block (with pretty-printing)
• link — Shown as a clickable URL with optional description text

Each share page includes the artifact title, the associated task name (if available), creation date, and a link back to buildd.dev.

Programmatic Access

Share tokens also work via the API for programmatic consumption:

curl https://buildd.dev/api/share/{token}

The lookup requires both a matching token and visibility = 'public', so a revoked artifact returns 404 Not found even with the correct token.

Response:

{
  "artifact": {
    "id": "a1b2c3d4-...",
    "type": "report",
    "title": "Weekly Performance Report",
    "content": "# Performance Summary\n\n...",
    "metadata": {},
    "createdAt": "2026-02-20T10:30:00Z"
  },
  "task": {
    "title": "Generate weekly performance report",
    "status": "completed"
  }
}

Artifact Gallery

The dashboard provides two views for browsing artifacts:

Workspace Artifacts

Navigate to a workspace and click Artifacts in the header. This shows all artifacts produced by workers in that workspace, sorted by creation date (newest first). Each artifact displays its type, title, associated task, and a link to its share page.

Artifacts of type impl_plan are filtered out of both gallery views, so you only see deliverable artifacts. No other type is hidden.

Global Artifacts

Navigate to Artifacts in the main navigation to see artifacts across all workspaces you have access to. This cross-workspace view includes the workspace name on each artifact for context.

Realtime Updates

When an artifact is created, Buildd pushes two realtime events via Pusher:

• Worker channel — worker:progress with { workerId, taskId, status, updatedAt }
• Workspace channel — worker:artifact with { workerId, taskId }

Both payloads are deliberately thin — they carry no artifact content and no share URL. They are refresh signals; the client refetches. Don't build anything that expects artifact data on the wire.

Use Cases

Automated Reports

Schedule a recurring task that analyzes data and produces a report artifact:

Task: "Generate weekly security scan report"
→ Agent runs analysis
→ Creates artifact (type: report) with findings
→ Calls POST /api/artifacts/{id}/share to publish it
→ Share URL posted to Slack via webhook

Data Exports

Agents working with APIs or databases can export structured results:

Task: "Audit API endpoints for deprecated fields"
→ Agent scans OpenAPI spec
→ Creates artifact (type: data) with JSON findings
→ Shares it, then stakeholders access formatted data via the share link

Executive Summaries

After completing complex multi-step tasks, agents can produce a summary:

Task: "Migrate auth module to new provider"
→ Agent completes migration, creates PR
→ Creates artifact (type: summary) with migration recap
→ Tech lead reviews summary without reading every commit

Deploy Previews and External Links

Agents that trigger deployments can capture the preview URL:

Task: "Deploy feature branch to staging"
→ Agent pushes and triggers deploy
→ Creates artifact (type: link) with staging URL
→ QA team opens it from the workspace gallery (no share needed for team members)

API Reference

Endpoints

Create Artifact Request

POST /api/workers/{id}/artifacts
Authorization: Bearer bld_xxx
Content-Type: application/json

Validation rules:

• type must be one of the six types the worker route accepts (the mission and initiative routes add analysis and recommendation)
• title is required and must be a string
• url is required when type is link
• a caller-supplied storageKey must belong to the worker's workspace, or the request is rejected with 400
• in a workspace whose data class is sensitive, content and storageKey are forced to null — only a metadata stub row is stored

Artifact Object

{
  "id": "uuid",
  "workerId": "uuid",
  "type": "report",
  "title": "Security Audit Report",
  "content": "# Findings\n\n...",
  "storageKey": null,
  "shareToken": null,
  "visibility": "private",
  "metadata": {},
  "createdAt": "2026-02-20T10:30:00Z",
  "shareUrl": null
}

shareUrl is computed at response time from shareToken — it is null until the artifact is shared, and null again after a revoke.

storageKey is not reserved for future use. It is the live object key for file-backed artifacts: upload_artifact (and POST /api/artifacts/upload-url) derives one under the workspace's prefix, and GET /api/artifacts/{id}/download turns it into a signed download URL. You may also pass an existing key on create, but it must resolve inside the worker's own workspace prefix.

MCP Tool

create_artifact returns the artifact ID, title, type, and either a share URL (if one already exists) or Visibility: private (not shared).