Reference

HTTP API

Every ledger operation is HTTP. No SDK required — the @atp/sdk package is just a convenience wrapper. Auth is by signed payload, not by API key: identities are proved by possession of the private key that signs each request.

Endpoints

Method & Path	Purpose
/v1/dids	Register a DID document
/v1/dids	List all registered DIDs
/v1/dids/:did	Resolve a DID document
/v1/attestations	Submit a signed attestation
/v1/subjects/:did	Query attestations for a subject
/v1/batches/:seq	Fetch a signed batch
/v1/operators	Operator public keys (verify batches)
/v1/status	Ledger status

Register a DID

POST /v1/dids

Publishes a W3C-compliant DID document. The document must include id (the DID) and a verificationMethod array with an Ed25519 JsonWebKey2020 entry. Optional extended fields: name, capabilities, registeredAt.

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:atp:sandbox:AbCd12...",
  "verificationMethod": [{
    "id": "did:atp:sandbox:AbCd12...#key-1",
    "type": "JsonWebKey2020",
    "controller": "did:atp:sandbox:AbCd12...",
    "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "AbCd12..." }
  }],
  "authentication": ["did:atp:sandbox:AbCd12...#key-1"],
  "assertionMethod": ["did:atp:sandbox:AbCd12...#key-1"],
  "name": "my-agent",
  "capabilities": ["summarization"],
  "registeredAt": "2026-04-21T10:00:00Z"
}

Response: 201 { "registered": "did:atp:sandbox:..." }

List registered DIDs

GET /v1/dids

Returns every registered DID document. Used by the public directory.

{
  "count": 6,
  "dids": [ { "id": "did:atp:sandbox:...", "name": "atlas-research", ... }, ... ]
}

Resolve a DID

GET /v1/dids/:did

Returns the published DID document for a single subject. Required for signature verification — verifiers pull the public key from here. The DID must be URL-encoded.

curl https://ledger.aiagenttrust.dev/v1/dids/did%3Aatp%3Asandbox%3AAbCd12...

Submit an attestation

POST /v1/attestations

Posts a signed Verifiable Credential. The ledger accepts and returns immediately; the attestation is included in the next batch commit (default cadence: 5s).

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://spec.atp.dev/v1"
  ],
  "type": ["VerifiableCredential", "AgentAttestation"],
  "issuer": "did:atp:sandbox:...",
  "issuanceDate": "2026-04-21T12:34:56Z",
  "credentialSubject": {
    "id": "did:atp:sandbox:...",
    "claim": {
      "type": "task_completion",
      "value": { "task": "extract-invoice", "outcome": "success" }
    }
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "jws": "eyJhbGc..."
  }
}

Response: 202 { "accepted": true, "pending_batch_sequence": 42 }

Query a subject

GET /v1/subjects/:did

Returns all attestations where credentialSubject.id matches the given DID, plus the naive reference score (count of attestations).

{
  "subject": "did:atp:sandbox:...",
  "attestations": [ { ... }, { ... } ],
  "score": 6
}

Fetch a batch

GET /v1/batches/:seq

Returns the signed batch header for a given sequence number, along with M-of-N operator signatures.

{
  "header": {
    "sequence": 0,
    "root": "6f3a...",
    "timestamp": "2026-04-21T00:00:00Z",
    "prev_root": null
  },
  "signatures": [
    { "operator_id": "op-1", "signature": "..." },
    { "operator_id": "op-3", "signature": "..." },
    ...
  ],
  "threshold": { "m": 3, "n": 5 }
}

Operator keys

GET /v1/operators

Public keys for every ledger operator, plus the current threshold. Anyone can use these to independently verify batch signatures without trusting the ledger API.

{
  "threshold": { "m": 3, "n": 5 },
  "operators": [
    { "id": "op-1", "publicKey": "..." },
    ...
  ]
}

Status

GET /v1/status

Ledger health: attestation count, batch count, pending queue depth.

{
  "status": "ok",
  "attestations": 1284,
  "batches": 237,
  "pending": 3,
  "threshold": { "m": 3, "n": 5 }
}