Skip to content

api-reference.md

Latest commit

 

History

History
194 lines (140 loc) · 3.03 KB

api-reference.md

File metadata and controls

194 lines (140 loc) · 3.03 KB
Raw

API Reference

All examples assume platform-api is running at http://localhost:4111.

Authentication

POST /v1/auth/token

Bootstrap token issuance for local and demo flows.

Request:

{
  "subject": "local-admin",
  "roles": ["demo-admin"],
  "scopes": ["admin:read", "topics:read", "topics:write", "messages:read", "messages:write"],
  "ttlSeconds": 3600
}

Response:

{
  "accessToken": "jwt",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "subject": "local-admin",
  "roles": ["demo-admin"],
  "scopes": ["admin:read", "topics:read", "topics:write", "messages:read", "messages:write"]
}

POST /v1/auth/verify

Request:

{
  "token": "jwt"
}

Topics

GET /v1/topics

Requires topics:read.

POST /v1/topics

Requires topics:write.

Request:

{
  "name": "orders",
  "memo": "Ordered domain events",
  "partitions": 4,
  "retentionHours": 72,
  "acl": {
    "publishers": ["checkout"],
    "subscribers": ["orders-projection"]
  }
}

GET /v1/topics/:topicId

Requires topics:read.

Messages

POST /v1/topics/:topicId/messages

Requires messages:write.

Request:

{
  "publisherId": "checkout",
  "idempotencyKey": "order-123-created",
  "partitionKey": "merchant-42",
  "orderingKey": "order-123",
  "payload": {
    "orderId": "123",
    "status": "CREATED"
  }
}

Response:

{
  "accepted": true,
  "deliverySemantics": "AT_LEAST_ONCE_WITH_IDEMPOTENCY",
  "message": {
    "messageId": "uuid",
    "topicId": "orders",
    "publisherId": "checkout",
    "payload": {
      "orderId": "123",
      "status": "CREATED"
    },
    "metadata": {},
    "partitionKey": "merchant-42",
    "orderingKey": "order-123",
    "integrityHash": "sha256",
    "topicMemo": "Ordered domain events",
    "transactionId": "0.0.5005-42",
    "sequenceNumber": 42,
    "topicSequenceNumber": 11,
    "consensusTimestamp": "2026-07-09T12:00:00.000Z",
    "status": "FINAL"
  }
}

GET /v1/topics/:topicId/messages

Requires messages:read.

Query parameters:

  • afterSequence
  • afterConsensusTimestamp
  • limit
  • consumerGroup

When consumerGroup is supplied, the returned batch advances that consumer group's checkpoint to the last returned message.

GET /v1/topics/:topicId/stream

Requires messages:read.

SSE stream with at-least-once delivery.

Query parameters:

  • afterSequence

Subscriptions

POST /v1/subscriptions

Requires messages:read.

Request:

{
  "topicId": "orders",
  "consumerGroup": "orders-projection"
}

GET /v1/subscriptions/:consumerGroup/checkpoints/:topicId

Requires messages:read.

Admin

GET /v1/admin/snapshot

Requires admin:read.

Returns:

  • topic list
  • total message count
  • latest canonical sequence
  • mirror status
  • repository, provider, and rate-limiter health

Errors

All business errors use:

{
  "code": "VALIDATION_ERROR",
  "message": "name is required",
  "requestId": "req-123"
}

OpenAPI

  • Human-readable UI: /docs
  • JSON document: /openapi.json