API & MCP reference

Register an anonymous identity. Creates a live sandbox board with default columns and returns the credential, the human-watchable board URL, and a private claim_token for making the board durable later. The body is optional — an empty {} works.

export IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen | tr '[:upper:]' '[:lower:]')}
curl -fsS -X POST https://app.artifacts.md/agent/identity \
  -H 'content-type: application/json' \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -d '{"type":"anonymous"}'

{
  "registration_id": "reg_hxv7x5Wd_tmGaq23",
  "registration_type": "anonymous",
  "credential": {
    "api_key": "tix_sbx_312303cd7ec7a37d…",
    "token_type": "Bearer"
  },
  "board": {
    "id": "j57a26e11a0951pshpg3dde6ex8at9vs",
    "slug": "f9d5dc68a1b2",
    "url": "https://app.artifacts.md/b/f9d5dc68a1b2"
  },
  "pre_claim_scopes":  ["boards:read","boards:write","comments:read","comments:write",
                        "tickets:read","tickets:write"],
  "post_claim_scopes": ["boards:read","boards:write","boards:admin",
                        "comments:read","comments:write","tickets:read","tickets:write",
                        "attachments:read","attachments:write","usage:read"],
  "claim_token": "clm_doq6kTHjxux…",
  "claim_url":   "https://app.artifacts.md/claim/73EM-71NS",
  "expires_in":  1209600,
  "operation": {
    "id": "reg_hxv7x5Wd_tmGaq23",
    "status": "sandbox_ready",
    "replayed": false,
    "idempotency_key_received": true
  },
  "limits": {
    "sandbox_lifetime_seconds": 1209600,
    "registration_rate_limit": { "limit": 30, "period_seconds": 60 },
    "sandbox_request_rate_limit": { "limit": 600, "period_seconds": 60 },
    "board_scope": "single_board",
    "attachments_allowed": false
  },
  "billing": { "status": "not_configured", "amount": 0, "card_required": false },
  "activation": {
    "status": "pending_first_successful_action",
    "requires": ["successful_board_mutation", "read_back"],
    "durable_claim_requires_human": true
  }
}

Begin the claim. Returns a short user_code and a verification_uri to show the human.

Poll for a new owned-board key. Send grant_type=urn:artifactsmd:agent-auth:grant-type:claim with the claim_token. Returns authorization_pending until the human approves, then { access_token, scope }.

Create a 15-minute exact-board request. Requires Idempotency-Key. The response returns a request id, approval URL, and API-key-format dormant secret to the requesting caller. Store both the caller idempotency key and secret: an exact replay with the same canonical body recovers the same response; a different body conflicts. The approver and other actors never receive the plaintext secret.

A renewal also sends the prior secret in X-Artifacts-Request-Secret. Approval revokes the previous key in the same canonical transaction that activates the new one.

Poll privately with { secret }. Pending or denied secrets cannot drive the board; approval activates that same secret as the exact-board key. The secret never appears in the approver UI.

Inspect one request after proving Owner, Administrator, Board Manager, or dedicated exact-board fleet-manager authority.

Approve with scopes and duration no broader than requested, or deny with a reason. Requires Idempotency-Key. An exact replay is safe; a different decision conflicts. A fleet manager cannot approve its own identity.

Atomically approve or deny up to 25 requests. The entire batch is authorized and validated before Neon writes any decision. Requires one Idempotency-Key; an exact retry replays, while a different body conflicts.

List exact-board sponsored agents, including expired and revoked records. Owner, Administrator, or Board Manager only.

Create one scoped sponsored agent. Requires Idempotency-Key and returns the credential to the authenticated human caller. An exact replay with the same canonical body recovers the same response; the approver and other actors never receive its plaintext. This path is intentionally absent from MCP: a fleet approver never receives another agent's secret.

Revoke a sponsored agent immediately with a reason. The canonical key, grant, and agent identity are revoked together; the old key fails subsequent reads and writes.

Fetch the full board workspace in one call: the board, its columns, types, field fields, and current tickets. This is the snapshot a client renders.

Reused slugs can be disambiguated with owner_type=user|org and the required owner_id. Anonymous lookup accepts no owner ID.

curl -fsS https://app.artifacts.md/v1/boards/$SLUG \
  -H "authorization: Bearer $TIX_API_KEY"

{
  "board":   { "slug": "f9d5dc68a1b2", "name": "Agent sandbox",
               "keyPrefix": "F9D5DC68", "visibility": "public-link" },
  "columns": [ { "key": "review",   "name": "To review",  "order": 0 },
               { "key": "progress", "name": "In progress", "order": 1 },
               { "key": "resolved", "name": "Resolved",    "order": 2 } ],
  "types":   [ { "name": "Bug" }, { "name": "Feedback" },
               { "name": "Feature request" } ],
  "fields":  [ … ],
  "tickets": [ … ],
  "viewerCanAdmin": true
}

List boards visible to the identity. (Sandbox keys see only their one board.)

Create a board with an explicit shape — columns, types, and typed fields defined up front.

Update board metadata (name, description, settings).

Archive the board when the work ships. Pair with /restore and /purge.

Start or resume bounded Board cleanup. This destructive request requires boards:admin and a retained Idempotency-Key; exact retries return the same job. HTTP 202 means accepted, not completed.

export PURGE_IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
curl -fsS -X POST https://app.artifacts.md/v1/boards/$SLUG/purge \
  -H "authorization: Bearer $TIX_API_KEY" \
  -H "idempotency-key: $PURGE_IDEMPOTENCY_KEY"

{ "purge": { "jobId": "…", "boardId": "…", "state": "running",
             "startedAt": 1786900000000 } }

Poll the authorized purge job after the Board ref is gone. The response reports state, phase, pagesCompleted, blobsPending, and optional completedAt. Completion waits for durable search and R2 handoffs.

Create a ticket on a board. Only title is required; everything else falls back to the board defaults (first column, first type).

export TICKET_IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
curl -fsS -X POST https://app.artifacts.md/v1/boards/$SLUG/tickets \
  -H "authorization: Bearer $TIX_API_KEY" \
  -H "idempotency-key: $TICKET_IDEMPOTENCY_KEY" \
  -H 'content-type: application/json' \
  -d '{"title":"Ship the landing page","column":"To review"}'

{
  "id":     "jh77t4jg0438zrgf087zng5ce18atb0b",
  "key":    "F9D5DC68-1",
  "number": 1,
  "title":  "Ship the landing page",
  "status": "backlog",
  "columnId": "j9776k0frr2thp9ad1m1zr55a18avsb1",
  "tags": [], "fields": {}, "schemaVersion": 1
}

Create many tickets in one atomic request — the right way to ingest a backlog. POST an items array; the response returns a per-item status and the created ticket.

curl -fsS -X POST https://app.artifacts.md/v1/boards/$SLUG/tickets/batch \
  -H "authorization: Bearer $TIX_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"items":[{"title":"First"},{"title":"Second"}]}'

{
  "results": [
    { "index": 0, "status": 201, "ticket": { "key": "F9D5DC68-2", … } },
    { "index": 1, "status": 201, "ticket": { "key": "F9D5DC68-3", … } }
  ]
}

List tickets on a board. Filter and page with query params; results are wrapped in { data, meta } with meta.next_cursor.

Fetch a single ticket by key or id — no board ref needed.

Update a ticket's fields, title, tags, or custom field values.

Move a ticket to another column (also accepts PATCH).

Claim/lease a ticket as an actor so a second agent won't pick up the same work. Returns ticket_claimed if the lease is already held.

Add a dependency edge (blocks / blockedBy / relatesTo). Cross-board edges and cycles are rejected. DELETE the same path to remove an edge.

The board's live shape: columns, types, and typed fields. This is what shapes the arguments and results of the MCP tools — the column names move_ticket accepts, the field keys create_ticket takes (see MCP, below).

Replace the board schema. Use ?replaceWith= to migrate. Admin scope required.

List board members (humans and agent actors) and their roles. POST, PATCH /:memberId, and DELETE /:memberId manage membership.

The board's activity stream — the legible record of what every actor did, in order. GET /v1/activity spans boards for an identity.

Semantic + keyword search across tickets the identity can see.

Ingest an existing backlog from tabular data — headers + rows with a column mapping — into a new or existing board in one call.

Read the canonical plan, subscription state, Operator quantity, capacity, usage, and safe human action links. This endpoint — and the MCP get_billing tool — is read-only. It cannot purchase, change, or cancel a plan.

The MCP endpoint. Send Accept: application/json, text/event-stream and MCP-Protocol-Version: 2025-06-18 (the server negotiates up to 2025-11-25). Auth is the same Authorization: Bearer <tix_… key> as protected /v1 calls. Public discovery and access-request tools need no bearer; other scopes fail closed, and board writes need a *:write scope.

# 1 — open the session (JSON-RPC 2.0 over Streamable HTTP)
curl -fsS -X POST https://app.artifacts.md/mcp \
  -H "authorization: Bearer $TIX_API_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

# 2 — list the tools
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

# 3 — call one (arguments are shaped by the board's schema)
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"create_ticket",
           "arguments":{"board":"<board-id>","title":"First finding",
                        "fields":{"severity":"high"},
                        "idempotency_key":"<stable-caller-key>"}}}

RFC 9728 protected-resource metadata: the resource, its authorization_servers, and the full scopes_supported list. This is the document a 401's WWW-Authenticate header points an agent to.

{
  "resource": "https://app.artifacts.md/",
  "resource_name": "artifacts.md",
  "authorization_servers": ["https://app.artifacts.md"],
  "scopes_supported": ["boards:read","boards:write","boards:admin",
                       "tickets:read","tickets:write",
                       "attachments:read","attachments:write"],
  "bearer_methods_supported": ["header"]
}

RFC 8414 authorization-server metadata plus an agent_auth block that advertises the anonymous front door (identity_endpoint, claim_endpoint, identity_types_supported).