ENSRainbow API

Endpoint Summary

Endpoint	Purpose	Key Response Types
`GET /health`	Liveness probe for orchestration	`{ status: "ok" }`
`GET /v1/heal/{labelhash}`	Heal a single labelhash	`HealSuccess`, `HealError`
`GET /v1/labels/count`	Current healable label count	`CountSuccess`, `CountServerError`
`GET /v1/version`	Server & database schema info plus label set details	`VersionInfo`

Health Check

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

Response: {"status":"ok"}

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 Version Information

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

Success Response:

{
  "status": "success",
  "version": "0.1.0",
  "dbSchemaVersion": 3,
  "labelSet": {
    "labelSetId": "subgraph",
    "highestLabelSetVersion": 0
  }
}

The response contains:

version: The current version of ENSRainbow
dbSchemaVersion: The current schema version of the database
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