Append events to a stream

POST

/api/event-stores/{eventStoreName}/streams/{streamId}

• Production

Appends one or more events to an event stream. Events are stored in chronological order and can be used to track state changes over time.

The stream version is used for optimistic concurrency control. If expectedStreamVersion is provided, the operation will fail if the current version doesn’t match.

expectedStreamVersion can be:

• A specific version number
• ‘no_stream’ (expects the stream does not exist)
• ‘stream_exists’ (expects the stream exists, any version)
• ‘any’ (no version checking, will append regardless of stream state)

Authorizations

• Bearer

Parameters

Path Parameters

eventStoreName

required

Event store name (automatically scoped to your organization)

string

Event store name (automatically scoped to your organization)

streamId

required

Unique identifier for the event stream (e.g., “user-123”, “order_456”, “product:789”). Supports hyphen (-), underscore (_), or colon (:) as delimiters. The first segment before the delimiter is used as the stream type.

string

Unique identifier for the event stream (e.g., “user-123”, “order_456”, “product:789”). Supports hyphen (-), underscore (_), or colon (:) as delimiters. The first segment before the delimiter is used as the stream type.

Request Body

object

events

required

Array<object>

object

type

required

string

data

required

object

key

additional properties

nullable

metadata

object

key

additional properties

nullable

options

object

expectedStreamVersion

Any of:

number

number

string

string

Examples

Single event append

{
  "events": [
    {
      "type": "user.created",
      "data": {
        "userId": "123",
        "email": "user@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      },
      "schemaVersion": "1.0.0"
    }
  ],
  "options": {
    "expectedStreamVersion": 0
  }
}

Multiple events append

{
  "events": [
    {
      "type": "user.created",
      "data": {
        "userId": "123",
        "email": "user@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      },
      "schemaVersion": "1.0.0"
    },
    {
      "type": "user.updated",
      "data": {
        "userId": "123",
        "email": "user1@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      }
    }
  ],
  "options": {
    "expectedStreamVersion": 0
  }
}

Using enum value for expectedStreamVersion

{
  "events": [
    {
      "type": "user.created",
      "data": {
        "userId": "123",
        "email": "user@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      }
    }
  ],
  "options": {
    "expectedStreamVersion": "no_stream"
  }
}

Responses

200

Events were successfully appended to the stream. Returns the new stream version and count of events written.

object

success

required

boolean

nextExpectedStreamVersion

required

number

eventsWritten

required

number

Examples

{
  "success": true,
  "nextExpectedStreamVersion": 1,
  "eventsWritten": 1
}

400

The request was invalid. This can occur if the event data is malformed or required fields are missing.

object

error

required

string

Allowed values: Invalid request body

details

required

Array<object>

object

code

required

string

message

required

string

path

required

Array

401

Unauthorized: Organization ID not found in authentication context

object

error

required

string

Allowed values: UNAUTHORIZED

message

required

string

Allowed values: Unauthorized: Organization ID not found in authentication context

Examples

{
  "error": "UNAUTHORIZED",
  "message": "Unauthorized: Organization ID not found in authentication context"
}

409

A version conflict occurred. This happens when the expectedStreamVersion doesn’t match the current stream version, indicating potential concurrent modifications.

object

error

required

string

Allowed values: Version conflict

details

required

string

currentVersion

required

number

expectedVersion

required

number

Examples

{
  "error": "Version conflict",
  "details": "Expected version 0 but stream is at version 1",
  "currentVersion": 1,
  "expectedVersion": 0
}