Grails API Documentation

POST /api/v1/search/bulk

Search for exact matches on multiple ENS names at once. Paginates the input terms (not results). Returns placeholder objects for terms not found in the database.

Authentication: Optional (enhances results with user-specific data)

Cache: None

Request Body

Field	Type	Required	Description
`terms`	string[]	Yes	ENS names to search for (1–10,000 items)
`page`	number	No	Page number (default `1`) — paginates the input terms
`limit`	number	No	Results per page (1–100, default `20`)

Names without .eth suffix are automatically normalized (e.g. cool → cool.eth).

Sample Request


curl -X POST https://api.grails.app/api/v1/search/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["cool", "vitalik.eth", "example"],
    "page": 1,
    "limit": 20
  }'

Response


// 200 OK
{
  "success": true,
  "data": {
    "results": [
      {
        "name": "cool.eth",
        "token_id": "12345...",
        "owner": "0x1234...",
        "listings": [...],
        "upvotes": 10,
        "watchers_count": 5,
        // ... full search result fields
      },
      {
        "name": "notfound.eth",
        "id": 0,
        "token_id": "",
        "owner": "",
        "listings": [],
        // ... placeholder with zeroed values
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body
500	`SEARCH_ERROR`	Bulk exact search failed