Skip to main content
POST/data-streams/user

Create Stream

Creates a user stream in the project: a named, append-only message log that the project's own producers publish to and consumers read from.

The slug is derived from displayName. maxBytes reserves storage from the organization's Pulse Stream allotment and retentionSeconds sets how long each message is kept.

Answers 201 with the stream.

Needs PROJECT_ADMIN.

Audited as data.write.pulse_stream.created.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
displayName *string

A single line of text, 1 to 80 characters.

The stream's slug (its address under /data-streams/user/<slug>) is derived from it and must be unique among the project's active streams.

retentionSecondsinteger

Retention (max_age) in whole hours: 3600 to 86400 is Warm, above 86400 is Cold.

Default 86400. 900 (Hot, 15 min) is reserved for platform system streams and answers 403 K9O_STREAM_TIER_FORBIDDEN; any other value that is not a whole number of hours answers 400 K9O_STREAM_INVALID.

A project's stream retention ceiling may refuse a long window.

maxBytes *integer

The stream's reserved storage ceiling in bytes (required).

Legal sizes: 10 MiB to 1 GiB in 10 MiB steps; above 1 GiB to 10 GiB in 100 MiB steps; above 10 GiB to 64 GiB in 1 GiB steps.

The band edges 1 GiB and 10 GiB are legal.

Anything else is 400 K9O_INVALID_FIELD_VALUE naming the band.

The org's storage allotment also bounds the sum over its active streams.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_REQUEST_SHAPEThe request body did not match the expected shape (displayName required; retentionSeconds/maxBytes must be positive integers if supplied).
400K9O_STREAM_INVALIDThe displayName does not yield a valid slug (needs at least one alphanumeric character), the requested retentionSeconds is not a valid quantized value, or a stream with the derived slug already exists in this project.
403K9O_IAM_POLICY_DENIEDThe bound IAMPolicy ceiling denies streams:create for this principal.
404K9O_NOT_FOUNDThe project this stream would belong to could not be found, or the caller has no project membership.
409K9O_PULSE_STREAM_ORG_QUOTA_EXCEEDEDThe organization is at its tier's org-wide active Pulse Stream quota; raise the quota or retire an existing stream elsewhere in the org before creating another.
429K9O_STREAM_LIMIT_EXCEEDEDThis project is at its active Pulse Stream cap; retire an existing stream in this project before creating another.
Response body (201)
data *object

A user stream: an append-only message log in the project.

id *string

The stream's internal id (pstr_...).

Address the stream by slug.

slug *string

The stream's address in the project, derived from displayName.

projectId *string

The project the stream belongs to (proj_...).

displayName *string

The name given at creation.

subjectPrefix *string

The message subject namespace the platform assigned to the stream: k9o.<region>.<org>.<project>.user.<id>.

Published messages carry subjects under it.

region *string

The region the stream's data lives in.

retentionSeconds *integer

How long each message is kept, in seconds: 900 or a whole number of hours.

retentionClass *"hot" | "warm" | "cold"

The retention class retentionSeconds falls in, which sets the storage rate: hot is 15 minutes, warm is 1 to 24 hours, cold is above 24 hours.

maxBytes *any

The storage the stream reserves, in bytes.

Null only on a stream created before a size was required.

One of: integer
or: null
status *"active"

Always active: a deleted stream is not returned.

createdAt *string <date-time>

When the stream was created.

createdBy *any

The id of the caller that created the stream; null if not recorded.

One of: string
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.streams.create({})

Showing example in TypeScript

Request example
{
  "displayName": "string",
  "retentionSeconds": 0,
  "maxBytes": 0
}
Response example (201)
{
  "data": {
    "id": "string",
    "slug": "string",
    "projectId": "string",
    "displayName": "string",
    "subjectPrefix": "string",
    "region": "string",
    "retentionSeconds": 0,
    "retentionClass": "hot",
    "maxBytes": 0,
    "status": "active",
    "createdAt": "string",
    "createdBy": "string"
  }
}

More in Realtime Feeds & Streams