Documentation

This guide covers the four calls needed to move from an empty project to a working notification stream.

1. Authentication

Every request carries a bearer token issued per project. Tokens are scoped to a single workspace and can be rotated without downtime by publishing the new token before revoking the old one.

Authorization: Bearer <PROJECT_TOKEN>

2. Publish an event

Events are JSON objects with three fields: topic, body and an optional correlation_id. The body is stored as UTF-8 and delivered unchanged.

curl --http2 -X POST https://abc.jdcity.cc/v1/events \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "topic": "build.finished",
    "correlation_id": "4821",
    "body": "deploy 4821 ok"
  }'

A successful publish returns 202 Accepted with the assigned event id:

{ "id": "evt_7f3c1a", "topic": "build.finished", "accepted": true }

3. Read a stream

Consumers subscribe to a topic and hold the connection open. The stream is an HTTP/2 response with content-type: application/json and one JSON object per line. Reconnect with Last-Event-ID to resume after a disconnect.

curl --http2 -N https://abc.jdcity.cc/v1/streams \
  -H "authorization: Bearer $TOKEN" \
  -H "topic: build.finished"

4. Errors

Status	Meaning	Retry
400	Malformed payload or unknown topic	No
401	Missing or revoked token	No
429	Rate limit for the workspace	After `retry-after`
503	No subscriber available for the topic	Yes, with backoff

Limits