List indexer candidates and claims

GET/v1alpha1/admin/indexersindexes.read

Lists candidate nodes competing to write indexes and the active writer claim for each index.

Any node can serve this request from its local view of shared deployment state, including search-only nodes. The response can lag actual state by a few seconds. Indexes without an active claim are omitted until a write assigns a writer.

If a credential lacks permissions for an index, that index is omitted from the claims list. On nodes using local storage, both lists are empty.

Request

HTTP

GET /v1alpha1/admin/indexers
Authorization: Bearer <key>

curl

curl -X GET "http://localhost:8080/v1alpha1/admin/indexers" \
  -H "Authorization: Bearer $EXOFIND_API_KEY"

JavaScript

const apiKey = process.env.EXOFIND_API_KEY;

const response = await fetch("http://localhost:8080/v1alpha1/admin/indexers", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${apiKey}`
  }
});

const result = await response.json();

Java

String apiKey = System.getenv("EXOFIND_API_KEY");

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("http://localhost:8080/v1alpha1/admin/indexers"))
  .header("Authorization", "Bearer " + apiKey)
  .GET()
  .build();

HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());

Go

apiKey := os.Getenv("EXOFIND_API_KEY")

request, err := http.NewRequest("GET", "http://localhost:8080/v1alpha1/admin/indexers", nil)
if err != nil {
  log.Fatal(err)
}

request.Header.Set("Authorization", "Bearer "+apiKey)

response, err := http.DefaultClient.Do(request)

Response200

{
  "candidates": [
    {
      "node": "node-a-7f21",
      "address": "http://node-a:8080",
      "expiresAt": "2026-08-21T10:15:30Z"
    }
  ],
  "claims": [
    {
      "index": "products",
      "node": "node-a-7f21",
      "address": "http://node-a:8080",
      "expiresAt": "2026-08-21T10:15:30Z"
    }
  ]
}

Responses

200

The candidate nodes and the claims the key can see.

IndexerListResponse

Candidate nodes competing to write indexes and the active writer claim for each index. The response reflects the answering node's view of shared deployment state and can lag actual state by a few seconds. On nodes using local storage, both lists are empty.

candidatesCandidate[]

The candidate nodes competing to write indexes, ordered by node.

Example

{
  "node": "node-a-7f21",
  "address": "http://node-a:8080",
  "expiresAt": "2026-08-21T10:15:30Z"
}

3 properties

nodestring

The name the node competes under.

Example

"node-a-7f21"

addressstring

Target address for write forwarding. Omitted when the node did not set EXOFIND_NODE_ADDRESS.

Example

"http://node-a:8080"

expiresAtstring

The timestamp when the candidacy expires unless renewed by the node, as an ISO 8601 timestamp.

Example

"2026-08-21T10:15:30Z"

claimsClaim[]

The active writer claim for each index, ordered by index. Indexes without an active claim are omitted until a write assigns a writer. Claims on indexes where the key lacks permissions are also omitted.

Example

{
  "index": "products",
  "node": "node-a-7f21",
  "address": "http://node-a:8080",
  "expiresAt": "2026-08-21T10:15:30Z"
}

4 properties

indexstring

Name of the index.

Example

"products"

nodestring

The node writing the index.

Example

"node-a-7f21"

addressstring

Target address for write forwarding. Omitted when the node did not set EXOFIND_NODE_ADDRESS.

Example

"http://node-a:8080"

expiresAtstring

The timestamp when the claim expires unless renewed by the node, as an ISO 8601 timestamp.

Example

"2026-08-21T10:15:30Z"

401

The request carries no credential this node accepts. Absent, malformed, unknown and lapsed keys are all answered alike, so a refusal cannot be used to find out which keys exist. The response carries WWW-Authenticate: Bearer.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:unauthenticated

The request carries no credential this node accepts.

403

The API key does not have the indexes.read permission.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:forbidden

The key is accepted but does not hold the `indexes.read` permission.

503

Indexer leadership assignments could not be read from shared storage. Retrying the request is expected to work once storage responds.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

indexer:leadership_unreadable

Leadership assignments could not be read from shared state storage. Send the request again once storage answers.

Authorization

Permission

indexes.read

Checked on

At least one index

Roles

reader, writer, admin

An API key sent as a bearer token, such as Authorization: Bearer exok_4ff6b760264c1918_ePQcdT1O9HSATZoXfDbT8hhHGsP9VpZH. A key carries grants that pair permissions with index patterns; the permission each endpoint needs is named beside it. Nodes running with EXOFIND_AUTH_MODE=none accept requests without a credential, and a node with EXOFIND_AUTH_ANONYMOUS_KEY set serves requests that carry none with the permissions of that key.