REST API

The REST gateway exposes owner-address-native request and response shapes. The canonical protocol reference is protocol/SPECIFICATION.md — AccountKeychain custody, ERC-1271 removal, chain wipe.

Some deployed gateway routes are still catching up. This page is the authoritative reference.

Address-native selectors

REST surfaces are keyed by owner_address.

Examples of normative request/response changes:

  • project owner filters use owner_address
  • account lookups use owner_address
  • link reverse lookups use target_owner_address
  • commit and ref history entries expose owner_address or author_address

Disabled relay-era surfaces

REST documentation must not model these as active message families:

  • KEY_ADD
  • OWNERSHIP_TRANSFER
  • STORAGE_RENT
  • RELAY_SIGNER_ADD
  • RELAY_SIGNER_REMOVE

Write endpoints

The write path still revolves around signed Message submission:

  • submit one message
  • dry-run one message
  • batch submit multiple messages

Read model highlights

  • projects expose owner_address
  • account summaries are address-native
  • collaborator entries are address-native
  • commit metadata uses author_address
  • ref log entries use owner_address
  • merge request summaries include requester_owner_address, source_project_id, source_ref, and target_ref

Custody-key endpoints

  • GET /v1/accounts/{ownerAddress}/custody-keys — list AccountKeychain custody keys (paginated via limit / cursor)
  • GET /v1/accounts/{ownerAddress}/custody-keys/{key_id} — get a specific custody key (404 when absent)

Each entry exposes key_id (0x-prefixed 20-byte address), signature_type (1=secp256k1, 2=P256, 3=WebAuthn), public_key, admin, expires_at, added_at, revoked_at, and status (active / revoked). expires_at is a uint64 unix-seconds value serialized as a decimal string ("0" = non-expiring) to avoid JS number precision loss; added_at / revoked_at are uint32 numbers. GET /v1/accounts/{ownerAddress} also returns a custody_keys snapshot and a custody_nonce (uint64 decimal string).

Merge request endpoints

  • GET /v1/projects/{projectId}/merge-requests — list active merge requests targeting a project
  • GET /v1/projects/{projectId}/merge-requests/{requestId} — get a specific merge request
  • GET /v1/accounts/{ownerAddress}/merge-requests — list active merge requests opened by an account

On the REST surface, source_ref and target_ref are exposed as hex-encoded bytes so non-UTF-8 ref names round-trip without loss.

See RPC reference for field details.