Coordinator API Endpoints

Scope

This document is the HTTP API catalog for Redis Stream Coordinator. It lists endpoint paths, auth expectations, mutation behavior, idempotency expectations, and the most important request and response fields.

Use the local Scalar API Reference for interactive endpoint search, schemas, examples, and curl snippets. The server also exposes a live reference at http://localhost:8080/scalar. operationId values are treated as the API contract surface for generated clients and changed only for intentional protocol changes.

Detailed behavior is defined in these documents:

• heartbeat and reconciliation flow: 02-coordinator-architecture.md
• group state and assignment model: 03-group-assignment-model.md
• shard scaling and routing: 04-resharding-routing.md
• configuration, monitoring, and metrics: 06-data-config-observability.md

Base Contract

Base path:

/coord/v1

Common headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token-from-POST-/coord/v1/auth/login>
X-Request-Id: <caller-generated-id>

X-Request-Id is optional but strongly recommended for admin mutations, Terraform applies, CI automation, and incident replay. The coordinator records it in audit logs when present.

Path parameters:

Auth policy:

Common error response:

{
  "status": "CONFLICT",
  "errorCode": "GROUP_ALREADY_EXISTS",
  "message": "Group already exists"
}

Common status codes:

Endpoint Index

Admin API

Create Group

POST /coord/v1/streams/{streamPrefix}

Creates initial stream shard metadata and the configured shard count. The official create path only requires streamPrefix; consumer groups come from consumer runtime configuration and converge through heartbeat.

Request body:

Response: 201 Created with StreamCreateResponse.

Important response fields:

Duplicate request behavior:

• If the stream prefix already has coordinator metadata, the coordinator returns 409 Conflict.
• POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup} remains only as a compatibility endpoint for older automation.

Get Group

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}

Returns group source-of-truth metadata. This is an admin/debug endpoint. Consumers receive assignments through heartbeat responses.

Response: 200 OK with GroupResponse.

Delete Group

DELETE /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}

Deletes coordinator metadata for an inactive group. Use force=true only for operational recovery when live members cannot leave cleanly.

Request body:

Response: 200 OK with the deleted GroupResponse snapshot.

Failure behavior:

• If the group does not exist, the coordinator returns 404 Not Found with GROUP_NOT_FOUND.
• If live members exist and force=false, the coordinator returns 422 Unprocessable Entity.

Get Producer Routing Metadata

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/producer-routing

Returns read-only metadata required by producers to route partition keys to Redis Stream shard keys. This endpoint does not create streams, change shard counts, or mutate assignment.

Routing scope:

shardIndex = routeV1(partitionKey, shardCount)
streamKey = format(streamKeyPattern, shardIndex)

Routing is deterministic only for the returned shardCount, routing protocol, and partition key. After shard scale-out or scale-in, the same partition key can route to a different stream key.

Response: 200 OK with ProducerRoutingResponse.

Important response fields:

Scale Stream

POST /coord/v1/streams/{streamPrefix}/scale

Starts shard scale-out or scale-in for the stream prefix. Consumer group is intentionally not part of this request. Every registered consumer group for the stream observes the changed shard set on the next heartbeat and reconciles assignment independently.

Scale-in completion is not based only on heartbeat. If removed shards still have live owners, the coordinator waits for revoke progress through heartbeat. If every live member has expired, the coordinator advances to Redis-level drain checks and completes only when every Redis consumer group on removed shards reports pending=0 and known lag=0.

For duplicate-sensitive workloads, pause producers and drain in-flight publish retries before calling this endpoint. The project does not provide global event id deduplication across shards.

Request body:

Stream-level scale only changes shard count. Consume parallelism is configured by consumer applications, for example through @StreamListener(concurrency = N). The coordinator observes the resulting logical members through heartbeat and must not expose an admin endpoint that changes consumer runtime parallelism.

Compatibility note: POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/scale remains available during the current implementation phase, but stream-scoped scale is the official operator-facing path.

Response: 202 Accepted with StreamScaleResponse.

Important response fields:

Conflict behavior:

• If another migration is active, the coordinator returns 409 Conflict with ACTIVE_MIGRATION_EXISTS.
• If provisioning fails, the coordinator returns 503 Service Unavailable with REDIS_STREAM_PROVISIONING_FAILED.

Get Migration

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/migrations/{reshardingId}

Returns one recorded resharding.

Response: 200 OK with Migration.

Rollback Migration

POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/migrations/{reshardingId}/rollback

Requests rollback of a migration when rollback is still allowed. Messages already written to newly added shard indexes must be handled by the application or operator drain/replay policy.

Request body:

Response: 202 Accepted with Migration.

Failure behavior:

• If the migration does not exist, the coordinator returns 404 Not Found with MIGRATION_NOT_FOUND.
• If rollback is no longer allowed, the coordinator returns 422 Unprocessable Entity with ROLLBACK_NOT_ALLOWED.

Member API

Heartbeat

POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/members/{memberId}/heartbeat

Reports member liveness, owned shards, runtime capacity, revoke progress, and optional shard consumption progress. The coordinator returns assignment in the same response. There is no separate assignment polling endpoint.

Request body:

Response: 200 OK with HeartbeatResponse.

Important response fields:

Status behavior:

Mutation behavior:

• Updates member liveness and lease expiration.
• Stores member owned shard reports as current assignment.
• Stores revoke ack progress.
• May bump group epoch when join, leave, expiration, or fencing changes membership.
• Does not read, ack, retry, or modify Redis Stream messages.

Monitoring API

Monitoring endpoints are read-only. State changes must go through Admin API or member heartbeat.

Health

GET /coord/v1/monitoring/health

Response: 200 OK with HealthResponse.

Monitoring Session

GET /coord/v1/monitoring/session

Response: 200 OK with MonitoringSessionResponse.

The response is intended for Grafana/API clients that need authenticated principal metadata for the monitoring calls.

Compatibility

GET /coord/v1/monitoring/compatibility

Response: 200 OK with coordinator-module compatibility metadata.

List Groups

GET /coord/v1/monitoring/groups

Returns GroupsResponse, a list of GroupResponse summaries.

Get Group Monitoring Summary

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}

Returns GroupResponse after applying operational refresh.

List Members

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/members

Returns MembersResponse.

Important fields in each member:

Get Assignments

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/assignments

Returns AssignmentsResponse.

Get Consumption Progress

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/consumption

Returns flattened per-member, per-shard progress rows.

List Migrations

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/migrations

Returns MigrationsResponse.

Explicitly Unsupported Endpoints

The coordinator does not provide these API surfaces in the MVP:

• producer routing mutation endpoint,
• member startup desired-spec sync endpoint,
• direct Redis Stream read/ack endpoint,
• handler/retry/DLQ/idempotency marker endpoint,
• assignor selection or assignor negotiation endpoint,
• Kafka wire protocol endpoint.