# Endpoints (/connectors/cloudevents/reference/endpoints)



The CloudEvents connector exposes its full surface on the shared HTTP server
(default port **9090**) and is **enabled by default**. This page is the
authoritative reference for every endpoint: the send and queue operations (`POST`),
the SSE subscriptions (`GET`), their request bodies, success status codes, and query
parameters. To disable the connector, set `CONNECTORSCE_ENABLE=false` — see
[Configuration](/connectors/cloudevents/concepts/configuration-model).

## Base URL [#base-url]

All endpoints are served from the shared HTTP server:

```text
http://localhost:9090
```

The port is inherited from the REST transport (default `9090`). See the
[shared HTTP server](/connectors/concepts/shared-http-server) page for the middleware
chain, body limits, and SSE handling that apply to every route below.

## Endpoint table [#endpoint-table]

The connector groups its 12 endpoints into three families — **send** (synchronous
operations across the five messaging patterns), **queue** (durable-queue control),
and **subscribe** (long-lived SSE streams).

| Method | Path                         | Purpose                                 | Request body                      | Success status          |
| ------ | ---------------------------- | --------------------------------------- | --------------------------------- | ----------------------- |
| POST   | `/ce/send/event`             | Fire-and-forget pub/sub event           | CloudEvent (structured or binary) | 202 Accepted            |
| POST   | `/ce/send/event-store`       | Persistent, replayable event            | CloudEvent (structured or binary) | 202 Accepted            |
| POST   | `/ce/send/command`           | Command (execution confirmation)        | CloudEvent (structured or binary) | 202 Accepted            |
| POST   | `/ce/send/query`             | Query (data response)                   | CloudEvent (structured or binary) | 200 OK                  |
| POST   | `/ce/send/response`          | Response to a command/query             | CloudEvent + `?request_id=`       | 202 Accepted            |
| POST   | `/ce/queue/send`             | Send a message to a queue               | CloudEvent (structured or binary) | 202 Accepted            |
| POST   | `/ce/queue/receive`          | Receive (or peek) queue messages        | None (body ignored)               | 200 OK                  |
| POST   | `/ce/queue/ack_all`          | Acknowledge all pending queue messages  | None (body ignored)               | 200 OK                  |
| GET    | `/ce/subscribe/events`       | SSE pub/sub subscription                | —                                 | 200 `text/event-stream` |
| GET    | `/ce/subscribe/events-store` | SSE persistent subscription with replay | —                                 | 200 `text/event-stream` |
| GET    | `/ce/subscribe/commands`     | SSE command subscription                | —                                 | 200 `text/event-stream` |
| GET    | `/ce/subscribe/queries`      | SSE query subscription                  | —                                 | 200 `text/event-stream` |

<Callout type="info">
  The two success statuses are deliberate: `/ce/send/query` and the queue receive/ack
  operations return **200 OK** because they carry a synchronous payload, while the
  fire-and-forget and command sends return **202 Accepted**. All SSE endpoints return
  **200** with `Content-Type: text/event-stream`.
</Callout>

## Send endpoints [#send-endpoints]

All five send endpoints accept a CloudEvent in either content mode — structured
(`application/cloudevents+json` body) or binary (`ce-*` headers + raw data body).
See [Content modes](/connectors/cloudevents/how-to/content-modes) for the wire
format, and [Channel resolution](/connectors/cloudevents/how-to/channel-resolution)
for how the destination channel is derived from `subject` or `?channel=`.

| Endpoint               | Pattern             | Blocks for a reply | Notes                                                                       |
| ---------------------- | ------------------- | ------------------ | --------------------------------------------------------------------------- |
| `/ce/send/event`       | Events              | No                 | Pub/sub fan-out; returns the send result in `data`.                         |
| `/ce/send/event-store` | Events Store        | No                 | Persisted and replayable; same shape as `/ce/send/event`.                   |
| `/ce/send/command`     | Command             | Yes                | Waits for execution confirmation; timeout from `TimeoutSeconds`.            |
| `/ce/send/query`       | Query               | Yes                | Waits for a data response (returns **200**); timeout from `TimeoutSeconds`. |
| `/ce/send/response`    | Command/Query reply | No                 | Requires `?request_id=`; `subject` is the reply channel.                    |

The `/ce/send/response` endpoint is the only send endpoint with a required query
parameter:

| Parameter    | Type   | Required | Description                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------- |
| `request_id` | string | Yes      | The request ID from the received command/query, used for correlation. |

<Callout type="warn">
  Synchronous send endpoints enforce `TimeoutSeconds` (default 60s). A request that
  exceeds the timeout returns **HTTP 504**. SSE subscriptions are long-lived and are
  not subject to this timeout.
</Callout>

```bash
# Send a fire-and-forget event (structured mode)
curl -X POST http://localhost:9090/ce/send/event \
  -H "Content-Type: application/cloudevents+json" \
  -d '{
    "specversion": "1.0",
    "type": "com.example.order.created",
    "source": "order-service",
    "subject": "notifications",
    "data": {"order_id": "12345", "amount": 99.99}
  }'
```

## Queue endpoints [#queue-endpoints]

The queue family adds durable, at-least-once delivery. `send` carries a CloudEvent
body; `receive` and `ack_all` are **control operations** — the request body is
ignored and all inputs come from query parameters.

### POST /ce/queue/send [#post-cequeuesend]

Send a CloudEvent to a queue channel. Returns **202 Accepted** with the send result
in `data`.

### POST /ce/queue/receive [#post-cequeuereceive]

Receive (or peek at) messages from a queue. Returns **200 OK** with the received
messages; each message carrying `ce_*` tags is reconstructed as a CloudEvent, others
are returned in native KubeMQ form.

| Parameter      | Type   | Required | Default | Description                                                         |
| -------------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `channel`      | string | Yes      | —       | Queue channel name.                                                 |
| `client_id`    | string | Yes      | —       | Client identifier (overridden by auth claims when auth is enabled). |
| `max_messages` | int    | No       | `1`     | Maximum messages to receive (1–1000).                               |
| `wait_timeout` | int    | No       | `5`     | Wait timeout in seconds.                                            |
| `is_peek`      | bool   | No       | `false` | Peek at messages without consuming them.                            |

### POST /ce/queue/ack\_all [#post-cequeueack_all]

Acknowledge (drain) all pending messages in a queue. Returns **200 OK** with the ack
result in `data`.

| Parameter      | Type   | Required | Default | Description                                                         |
| -------------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `channel`      | string | Yes      | —       | Queue channel name.                                                 |
| `client_id`    | string | Yes      | —       | Client identifier (overridden by auth claims when auth is enabled). |
| `wait_timeout` | int    | No       | `5`     | Wait timeout in seconds.                                            |

```bash
# Receive up to 10 messages, waiting up to 10 seconds
curl -X POST "http://localhost:9090/ce/queue/receive?channel=work-queue&client_id=worker-1&max_messages=10&wait_timeout=10"
```

See [Queues](/connectors/cloudevents/how-to/queues) for the full send/receive
walkthrough.

## Subscribe endpoints (SSE) [#subscribe-endpoints-sse]

All four subscription endpoints are long-lived `GET` requests that respond with
`Content-Type: text/event-stream` and **HTTP 200**. They have no request body —
the subscription is configured entirely through query parameters. See
[SSE behavior](/connectors/cloudevents/how-to/sse-behavior) for the frame
format, keepalive, idle timeout, and reconnection semantics.

| Endpoint                     | Pattern      | Replay support                                                      |
| ---------------------------- | ------------ | ------------------------------------------------------------------- |
| `/ce/subscribe/events`       | Events       | No (non-persistent).                                                |
| `/ce/subscribe/events-store` | Events Store | Yes — `events_store_type`/`events_store_value` and `Last-Event-ID`. |
| `/ce/subscribe/commands`     | Command      | No; frames include request-ID/reply-channel fields.                 |
| `/ce/subscribe/queries`      | Query        | No; frames include request-ID/reply-channel fields.                 |

### Common SSE query parameters [#common-sse-query-parameters]

All four endpoints share these base parameters:

| Parameter   | Type   | Required | Description                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| `client_id` | string | Yes      | Client identifier (overridden by auth claims when auth is enabled). |
| `channel`   | string | Yes      | Channel to subscribe to.                                            |
| `group`     | string | No       | Load-balancing group name.                                          |

### Events-store replay parameters [#events-store-replay-parameters]

`/ce/subscribe/events-store` accepts two additional parameters that select the replay
start position:

| Parameter            | Type  | Default            | Description                                              |
| -------------------- | ----- | ------------------ | -------------------------------------------------------- |
| `events_store_type`  | int   | `1` (StartNewOnly) | Start position (1–6); see the table below.               |
| `events_store_value` | int64 | `0`                | Value for sequence/time-based positions (types 4, 5, 6). |

| Value | Name             | Description                                                       |
| ----- | ---------------- | ----------------------------------------------------------------- |
| 1     | StartNewOnly     | Only new messages from this point forward.                        |
| 2     | StartFromFirst   | Replay from the first stored message.                             |
| 3     | StartFromLast    | Start from the last stored message.                               |
| 4     | StartAtSequence  | Start at a specific sequence number (`events_store_value`).       |
| 5     | StartAtTime      | Start at a Unix timestamp in seconds (`events_store_value`).      |
| 6     | StartAtTimeDelta | Start at a time delta in seconds from now (`events_store_value`). |

<Callout type="info">
  For events-store subscriptions, the server emits an `id:` field (the message sequence)
  on each frame. Reconnecting with the `Last-Event-ID` header resumes from `sequence + 1`.
  If both `Last-Event-ID` and `events_store_type` are present, the query parameter wins —
  omit `events_store_type` to use header-based reconnection.
</Callout>

### SSE connection limits [#sse-connection-limits]

| Behavior       | Setting                                     | Status when exceeded                                      |
| -------------- | ------------------------------------------- | --------------------------------------------------------- |
| Idle timeout   | `MaxSSEIdleSeconds` (default 300s)          | `error` event (`stream idle timeout`), connection closed. |
| Connection cap | `MaxSSEConnections` (default 0 = unlimited) | **HTTP 429** Too Many Requests.                           |

```bash
# Subscribe to events
curl -N "http://localhost:9090/ce/subscribe/events?client_id=my-client&channel=notifications"

# Subscribe to events-store, replaying from the first stored message
curl -N "http://localhost:9090/ce/subscribe/events-store?client_id=my-client&channel=audit-log&events_store_type=2"

# Reconnect to events-store, resuming after sequence 42
curl -N -H "Last-Event-ID: 42" \
  "http://localhost:9090/ce/subscribe/events-store?client_id=my-client&channel=audit-log"
```

## Response envelope [#response-envelope]

Every endpoint returns the same response envelope. Successful responses carry the
operation result in `data`; errors set `is_error` to `true` with a descriptive
`message`:

```json
{
  "is_error": false,
  "message": "OK",
  "data": { }
}
```

## Status codes [#status-codes]

| Status | Meaning               | When                                                                                                                                                  |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200    | OK                    | Query response, queue receive, queue ack\_all, and all SSE streams.                                                                                   |
| 202    | Accepted              | Event send, event-store send, command send, queue send, response send.                                                                                |
| 400    | Bad Request           | Invalid CloudEvent (including unrecognized Content-Type), missing required parameters, validation failure, reserved channel name, subscription error. |
| 429    | Too Many Requests     | SSE connection limit (`MaxSSEConnections`) exceeded.                                                                                                  |
| 500    | Internal Server Error | Backend messaging error or SSE setup failure.                                                                                                         |
| 504    | Gateway Timeout       | A synchronous request exceeded `TimeoutSeconds`.                                                                                                      |

The full error message catalog lives in
[CE ↔ KubeMQ mapping](/connectors/cloudevents/reference/ce-to-kubemq-mapping#error-codes).

## Related [#related]

<Cards>
  <Card title="CE ↔ KubeMQ mapping" href="/connectors/cloudevents/reference/ce-to-kubemq-mapping" description="Attribute-to-tag mapping, channel/ClientID resolution, and the error catalog." />

  <Card title="Content modes" href="/connectors/cloudevents/how-to/content-modes" description="Structured vs binary request bodies for the send endpoints." />

  <Card title="SSE behavior" href="/connectors/cloudevents/how-to/sse-behavior" description="Frame format, keepalive, idle timeout, and reconnection for the subscribe endpoints." />

  <Card title="Configuration" href="/connectors/cloudevents/concepts/configuration-model" description="TimeoutSeconds, SubBuffSize, and the SSE limits referenced above." />
</Cards>