REST API

The Cloudflare Workers gateway translates HTTP REST requests to the underlying gRPC service. All endpoints return JSON and accept standard query parameters.

Base URL: https://api.makechain.net

Interactive docs: api.makechain.net/reference — try endpoints directly in the browser.

Projects

GET /v1/projects/

Get a project by its 32-byte hex ID.

curl https://api.makechain.net/v1/projects/a1b2c3d4...

Response:

{
  "project_id": "a1b2c3d4...",
  "name": "my-project",
  "description": "A sample project",
  "license": "MIT",
  "visibility": "public",
  "owner_mid": 42,
  "status": "active",
  "fork_source": null,
  "ref_count": 3,
  "collaborator_count": 2,
  "commit_count": 47,
  "max_refs": 100,
  "max_collaborators": 50,
  "max_commits": 10000
}

GET /v1/projects/by-name/
/

Look up a project by owner MID and name.

curl https://api.makechain.net/v1/projects/by-name/42/my-project

GET /v1/projects

List projects. Supports pagination and owner filtering.

Parameter	Type	Description
`owner_mid`	string	Filter by owner account MID
`limit`	string	Max results per page (1-200)
`cursor`	string	Hex cursor from previous response

curl "https://api.makechain.net/v1/projects?owner_mid=42&limit=10"

Response:

{
  "projects": [{ "project_id": "...", "name": "...", ... }],
  "next_cursor": "abcd1234..."
}

GET /v1/projects/search

Search projects by name prefix.

Parameter	Type	Description
`query`	string	Name prefix to search for
`owner_mid`	string	Optional owner filter
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

GET /v1/projects/
/activity

Recent activity feed for a project.

Parameter	Type	Description
`limit`	string	Max entries to return

Refs

GET /v1/projects/
/refs

List refs in a project (branches and tags).

Parameter	Type	Description
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

Response:

{
  "refs": [
    {
      "project_id": "a1b2c3d4...",
      "ref_name": "refs/heads/main",
      "ref_type": "branch",
      "hash": "c0ff33de...",
      "nonce": 5
    }
  ],
  "next_cursor": null
}

GET /v1/projects/
/refs/

Get a single ref by name.

GET /v1/projects/
/refs/
/log

Get the update history of a ref.

Parameter	Type	Description
`limit`	string	Max entries to return

Response:

{
  "entries": [
    {
      "old_hash": "aabbccdd...",
      "new_hash": "c0ff33de...",
      "mid": 42,
      "timestamp": 1740000100,
      "block_number": 1312,
      "force": false,
      "nonce": 5
    }
  ]
}

Commits

GET /v1/projects/
/commits

List commits in a project.

Parameter	Type	Description
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

GET /v1/projects/
/commits/

Get a single commit by hash.

Response:

{
  "project_id": "a1b2c3d4...",
  "commit": {
    "hash": "c0ff33de...",
    "parents": ["aabbccdd..."],
    "tree_root": "11223344...",
    "author_mid": 42,
    "author_timestamp": 1740000100,
    "title": "feat: add user authentication",
    "message_hash": "eeff0011..."
  }
}

GET /v1/projects/
/commits/
/ancestors

Walk the commit graph and return the ancestor chain.

Parameter	Type	Description
`limit`	string	Max ancestors to return

Collaborators

GET /v1/projects/
/collaborators

List project collaborators.

Parameter	Type	Description
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

Response:

{
  "collaborators": [
    { "mid": 87, "permission": "write" }
  ],
  "next_cursor": null
}

Accounts

GET /v1/accounts/

Get account by MID (Make ID).

Response:

{
  "mid": 42,
  "username": "alice",
  "avatar": "",
  "bio": "",
  "website": "",
  "keys": [
    {
      "key": "abcd1234...",
      "scope": "owner",
      "allowed_projects": []
    }
  ],
  "storage_units": 1,
  "project_count": 3,
  "verifications": [
    {
      "verification_type": "eth_address",
      "address": "d8da6bf2...",
      "chain_id": "01"
    }
  ]
}

GET /v1/accounts/by-key/

Look up an account by its Ed25519 public key (64-char hex).

GET /v1/accounts/
/keys

List all keys registered to an account.

Parameter	Type	Description
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

GET /v1/accounts/
/keys/

Get a single key entry.

GET /v1/accounts/
/verifications

List verified external addresses for an account.

Parameter	Type	Description
`limit`	string	Max results per page
`cursor`	string	Pagination cursor

GET /v1/accounts/
/activity

Recent activity feed for an account.

Parameter	Type	Description
`limit`	string	Max entries to return

Blocks

GET /v1/blocks/

Get a committed block by number.

Response:

{
  "block": {
    "hash": "deadbeef...",
    "header": {
      "block_number": 1312,
      "timestamp": 1740000205,
      "version": 1,
      "network": 3,
      "parent_hash": "aabbccdd...",
      "state_root": "11223344..."
    }
  },
  "message_count": 5
}

GET /v1/blocks

List recent blocks.

Parameter	Type	Description
`start`	string	Starting block number
`limit`	string	Max blocks to return

Messages

GET /v1/messages/

Look up a committed message by its BLAKE3 hash (64-char hex).

GET /v1/messages

List committed messages across a block range.

Parameter	Type	Description
`start_block`	string	Starting block number
`end_block`	string	Ending block number
`limit`	string	Max messages to return

Write Endpoints

POST /v1/messages/submit

Submit a signed protobuf Message for consensus. The request body is the raw protobuf-encoded Message bytes.

Response:

{
  "hash": "c0ff33de...",
  "accepted": true,
  "error": ""
}

POST /v1/messages/batch

Submit up to 100 signed messages atomically. The request body is a protobuf-encoded BatchSubmitRequest.

Response:

{
  "results": [
    { "hash": "c0ff33de...", "accepted": true, "error": "" },
    { "hash": "deadbeef...", "accepted": false, "error": "duplicate message" }
  ],
  "accepted_count": 1,
  "rejected_count": 1
}

POST /v1/messages/dry-run

Validate a message against the current state without submitting.

Response:

{
  "would_accept": true,
  "error": "",
  "error_stage": ""
}

Chain Status

GET /v1/chain/stats

Cumulative chain analytics.

GET /v1/chain/status

Current node status (block height, mempool, network, version, uptime).

GET /v1/chain/snapshot

Snapshot export status.

GET /v1/chain/mempool

Mempool breakdown by message type.

Response:

{
  "total": 12,
  "capacity": 10000,
  "account_messages": 3,
  "project_messages": 9,
  "type_breakdown": [
    { "message_type": "COMMIT_BUNDLE", "count": 5 },
    { "message_type": "REF_UPDATE", "count": 4 }
  ],
  "oldest_timestamp": 1740000100,
  "newest_timestamp": 1740000500
}

GET /v1/health

Liveness and readiness probe.

Streaming (SSE)

Server-Sent Events endpoints for real-time updates. These bridge gRPC server streaming to browser-friendly SSE.

GET /v1/subscribe/messages

Stream finalized messages as SSE events.

Parameter	Type	Description
`project_id`	string	Optional: filter to one project (64-char hex)
`types`	string	Optional: comma-separated message type numbers

curl -N "https://api.makechain.net/v1/subscribe/messages?types=20,10"

SSE format:

event: message
data: {"hash":"c0ff33de...","signer":"abcd1234...","type":20,"type_name":"COMMIT_BUNDLE","mid":42,"timestamp":1740000100,"project_id":"a1b2c3d4..."}

GET /v1/subscribe/blocks

Stream block finalization events.

curl -N "https://api.makechain.net/v1/subscribe/blocks"

SSE format:

event: block
data: {"block_number":1312,"hash":"deadbeef...","timestamp":1740000205,"state_root":"11223344...","message_count":5}

gRPC-web Passthrough

For clients that prefer raw gRPC-web, the gateway proxies all requests to /makechain.MakechainService/* directly to the node.

# Example using grpcurl through the gateway
grpcurl -plaintext api.makechain.net:443 makechain.MakechainService/GetHealth

Input Validation

All path parameters and query strings are validated with Zod schemas. Invalid inputs return a structured 400 error:

{
  "error": "validation error",
  "issues": [
    { "path": "id", "message": "must be a 64-character hex string (32 bytes)" }
  ]
}

Error Format

gRPC errors are translated to HTTP status codes:

gRPC Code	HTTP Status	Meaning
3	400	Invalid argument
5	404	Not found
6	409	Already exists
7	403	Permission denied
8	429	Resource exhausted
16	401	Unauthenticated

All errors return:

{
  "error": "human-readable error message",
  "code": 5
}

Projects

GET /v1/projects/

GET /v1/projects/by-name//

GET /v1/projects

GET /v1/projects/search

GET /v1/projects//activity

Refs

GET /v1/projects//refs

GET /v1/projects//refs/

GET /v1/projects//refs//log

Commits

GET /v1/projects//commits

GET /v1/projects//commits/

GET /v1/projects//commits//ancestors

Collaborators

GET /v1/projects//collaborators

Accounts

GET /v1/accounts/

GET /v1/accounts/by-key/

GET /v1/accounts//keys

GET /v1/accounts//keys/

GET /v1/accounts//verifications

GET /v1/accounts//activity

Blocks

GET /v1/blocks/

GET /v1/blocks

Messages

GET /v1/messages/

GET /v1/messages

Write Endpoints

POST /v1/messages/submit

POST /v1/messages/batch

POST /v1/messages/dry-run

Chain Status

GET /v1/chain/stats

GET /v1/chain/status

GET /v1/chain/snapshot

GET /v1/chain/mempool

GET /v1/health

Streaming (SSE)

GET /v1/subscribe/messages

GET /v1/subscribe/blocks

gRPC-web Passthrough

Input Validation

Error Format

GET /v1/projects/by-name/
/

GET /v1/projects/
/activity

GET /v1/projects/
/refs

GET /v1/projects/
/refs/

GET /v1/projects/
/refs/
/log

GET /v1/projects/
/commits

GET /v1/projects/
/commits/

GET /v1/projects/
/commits/
/ancestors

GET /v1/projects/
/collaborators

GET /v1/accounts/
/keys

GET /v1/accounts/
/keys/

GET /v1/accounts/
/verifications

GET /v1/accounts/
/activity