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.

curl -fsS -X POST https://app.artifacts.md/agent/identity \
  -H 'content-type: application/json' \
  -d '{"type":"anonymous"}'

{
  "registration_id": "reg_hxv7x5Wd_tmGaq23",
  "registration_type": "anonymous",
  "credential": {
    "api_key": "tix_sbx_312303cd7ec7a37d…",
    "token_type": "Bearer"
  },
  "board": {
    "id": "j57a26e11a0951pshpg3dde6ex8at9vs",
    "slug": "f9d5dc68",
    "url": "https://artifacts.md/f9d5dc68"
  },
  "pre_claim_scopes":  ["boards:read","boards:write","tickets:read","tickets:write"],
  "post_claim_scopes": ["boards:read","boards:write","boards:admin",
                        "tickets:read","tickets:write",
                        "attachments:read","attachments:write"],
  "claim_token": "clm_doq6kTHjxux…",
  "claim_url":   "https://artifacts.md/claim/73EM-71NS",
  "expires_in":  1209599
}

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

Poll for the upgraded 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 }.

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.

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

{
  "board":   { "slug": "f9d5dc68", "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. The structure is a prompt, not a project.

Update board metadata (name, description, settings).

Archive the board — a system of motion tears boards down when the work ships. Pair with /restore and /purge.

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

curl -fsS -X POST https://app.artifacts.md/v1/boards/$SLUG/tickets \
  -H "authorization: Bearer $TIX_API_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.

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 every /v1 call; scopes fail closed, and 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"}}}}

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).