GET /v1/merkle/:artifactId

Request

GET /v1/merkle/:artifactId

No authentication required. Proofs are public so anyone can verify.

Response

Returns a self-contained ProofFile JSON. This includes everything needed to verify that the artifact is included in a specific Merkle tree checkpoint -- no further requests to Hub required.

{
  "artifact_id": "art_f7e6d5c4b3a2f7e6",
  "artifact_summary": {
    "actor": "agent://ci",
    "action": "test suite",
    "timestamp": "2026-03-28T14:30:00Z",
    "key_id": "ship_a1b2c3d4"
  },
  "inclusion_proof": {
    "leaf_index": 2048,
    "leaf_hash": "9d2fa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
    "path": [
      { "direction": "Right", "hash": "1a2b3c4d..." },
      { "direction": "Left", "hash": "5e6f7a8b..." },
      { "direction": "Right", "hash": "9c0d1e2f..." }
    ],
    "algorithm": "sha256-rfc9162"
  },
  "checkpoint": {
    "index": 42,
    "root": "sha256:7e3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
    "tree_size": 4096,
    "height": 12,
    "signed_at": "2026-03-28T15:00:00Z",
    "signer": "ship_a1b2c3d4",
    "public_key": "base64url-encoded-ed25519-public-key",
    "signature": "base64url-encoded-ed25519-signature",
    "algorithm": "sha256-rfc9162"
  }
}

ProofFile fields

How to verify

The proof is self-contained. To verify locally:

1. Recompute the leaf hash: sha256(artifact_id) and compare to inclusion_proof.leaf_hash
2. Walk the inclusion_proof.path from leaf to root, combining hashes at each level based on direction
3. Compare the computed root against checkpoint.root
4. Verify the checkpoint signature using the embedded public_key

CLI verification

treeship merkle verify proof.json

merkle proof emits the proof and merkle verify checks it; there is no single-step --verify flag. Pipe one into the other:

treeship merkle proof art_f7e6d5c4b3a2f7e6 > proof.json
treeship merkle verify proof.json

Errors

Example

curl https://api.treeship.dev/v1/merkle/art_f7e6d5c4b3a2f7e6

POST /v1/merkle/proof

Publish an inclusion proof binding an artifact to a checkpoint. DPoP-authenticated — treeship merkle publish calls this; you rarely call it by hand.

Body

Response 200 — { "artifact_id": "art_…", "stored": true }

The caller must own both the artifact and the checkpoint. This is object-level authorization, not a formality: because proofs are stored per (artifact_id, checkpoint_id) and the highest checkpoint wins, any authenticated dock that could write a proof it did not own could shadow another dock's proof and make anchored artifacts read as un-anchored.