ENSRainbow API

Endpoint Summary

Endpoint	Purpose	Key Response Types
`GET /health`	Liveness probe — succeeds as soon as the HTTP server is accepting requests	`{ status: "ok" }`
`GET /ready`	Readiness probe — succeeds once the database has been downloaded, validated, and opened	`ReadyResponse`, `ServiceUnavailableError`
`GET /v1/heal/{labelhash}`	Heal a single labelhash	`HealSuccess`, `HealError`
`GET /v1/labels/count`	Current healable label count	`CountSuccess`, `CountServerError`, `ServiceUnavailableError`
`GET /v1/config`	Public configuration of the running instance	`ENSRainbowPublicConfig`, `ServiceUnavailableError`

Liveness vs. Readiness

ENSRainbow’s container starts its HTTP server immediately so that orchestrators (Docker, Kubernetes, ECS, …) can reach it for liveness checks while the database is still being downloaded and validated on first boot (which can take 30+ minutes for large label sets).

GET /health — pure liveness probe. Returns 200 { status: "ok" } as soon as the HTTP server is bound. It does not guarantee the database is loaded.
GET /ready — readiness probe. Returns 200 { status: "ok" } only after the database has been downloaded, lite-validated, and opened by the process. While the server is still bootstrapping, it returns 503 Service Unavailable with a structured error body so clients can poll with backoff.

While the database is not yet ready, the following routes return 503 with the body:

{
  "status": "error",
  "error": "ENSRainbow is still bootstrapping its database",
  "errorCode": 503
}

GET /v1/heal/{labelhash}
GET /v1/labels/count
GET /v1/config

Clients (including ENSIndexer) should poll /ready rather than /health before issuing heal requests. The official ensrainbow-sdk exposes client.ready() exactly for this purpose.

Health Check

curl https://api.ensrainbow.io/health

Response: {"status":"ok"}

Readiness Check

curl https://api.ensrainbow.io/ready

Ready response: {"status":"ok"}

Not-ready response (HTTP 503):

{
  "status": "error",
  "error": "ENSRainbow is still bootstrapping its database",
  "errorCode": 503
}

Heal Label

Basic Usage

curl https://api.ensrainbow.io/v1/heal/0x[labelhash]

Example:

curl https://api.ensrainbow.io/v1/heal/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

Response:

{
  "status": "success",
  "label": "vitalik"
}

Advanced Usage with Query Parameters

You can optionally specify label_set_id and label_set_version query parameters:

curl "https://api.ensrainbow.io/v1/heal/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc?label_set_id=subgraph&label_set_version=0"

Query Parameters

label_set_id (optional): Validates that the request matches the database label set ID.
label_set_version (optional): Specifies the highest label set version of label set ID to query. Enables deterministic heal results across time even if the ENSRainbow server ingests label sets with greater versions than this value. If provided, label_set_id is required and only labels from label sets with versions less than or equal to this value will be returned.

Note on returned labels: The service returns labels exactly as they appear in the source data. This means:

Labels may or may not be ENS-normalized
Labels can contain any valid string, including dots, null bytes, or be empty
Clients should handle all possible string values appropriately

Error Responses

400 Bad Request: When the labelhash parameter is missing or invalid, or when query parameters are incorrectly specified

{
  "status": "error",
  "error": "Invalid labelhash - must be a valid hex string",
  "errorCode": 400
}

{
  "status": "error",
  "error": "Requested label set version is higher than available label set version",
  "errorCode": 400
}

{
  "status": "error",
  "error": "Server label set ID \"subgraph\" does not match client's requested label set ID \"ens-test-env\".",
  "errorCode": 400
}

404 Not Found: When no label is found for the given labelhash

{
  "status": "error",
  "error": "Label not found",
  "errorCode": 404
}

500 Internal Server Error: When an unexpected error occurs or database is not initialized
```
{
  "status": "error",
  "error": "Internal server error",
  "errorCode": 500
}
```

Get Count of Healable Labels

curl https://api.ensrainbow.io/v1/labels/count

Success Response:

{
  "status": "success",
  "count": 133856894,
  "timestamp": "2024-01-30T11:18:56Z"
}

Error Responses

{
  "status": "error",
  "error": "Label count not initialized. Check that the ingest command has been run.",
  "errorCode": 500
}

Get Public Config

curl https://api.ensrainbow.io/v1/config

Success Response:

{
  "version": "0.1.0",
  "labelSet": {
    "labelSetId": "subgraph",
    "highestLabelSetVersion": 0
  },
  "recordsCount": 133856894
}

The response contains:

version: The current version of ENSRainbow
labelSet: The label set of the loaded database
- labelSetId: The label set ID of the loaded database
- highestLabelSetVersion: The highest label set version available in the database
recordsCount: The total count of labels that can be healed by the ENSRainbow instance