{ "openapi": "3.1.0", "info": { "title": "S2, the durable streams API", "description": "Streams as a cloud storage primitive.", "termsOfService": "https://s2.dev/terms", "contact": { "email": "support@s2.dev" }, "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://a.s2.dev/v1" } ], "paths": { "/access-tokens": { "get": { "tags": [ "access-tokens" ], "summary": "List access tokens.", "operationId": "list_access_tokens", "parameters": [ { "name": "prefix", "in": "query", "description": "Filter to access tokens whose IDs begin with this prefix.\nIt must not contain NUL bytes.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "start_after", "in": "query", "description": "Filter to access tokens whose IDs lexicographically start after this string.\nIt must not contain NUL bytes.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "limit", "in": "query", "description": "Number of results, up to a maximum of 1000.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 1000, "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessTokensResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "post": { "tags": [ "access-tokens" ], "summary": "Issue a new access token.", "operationId": "issue_access_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAccessTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAccessTokenResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/access-tokens/{id}": { "delete": { "tags": [ "access-tokens" ], "summary": "Revoke an access token.", "operationId": "revoke_access_token", "parameters": [ { "name": "id", "in": "path", "description": "Access token ID.", "required": true, "schema": { "$ref": "#/components/schemas/AccessTokenIdStr" } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/basins": { "get": { "tags": [ "basins" ], "summary": "List basins.", "operationId": "list_basins", "parameters": [ { "name": "prefix", "in": "query", "description": "Filter to basins whose names begin with this prefix.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "start_after", "in": "query", "description": "Filter to basins whose names lexicographically start after this string.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "limit", "in": "query", "description": "Number of results, up to a maximum of 1000.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 1000, "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBasinsResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "post": { "tags": [ "basins" ], "summary": "Create a basin.", "operationId": "create_basin", "parameters": [ { "name": "s2-request-token", "in": "header", "description": "Client-specified request token for idempotent retries.", "required": false, "schema": { "$ref": "#/components/schemas/RequestToken" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBasinRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinInfo" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/basins/{basin}": { "get": { "tags": [ "basins" ], "summary": "Get basin configuration.", "operationId": "get_basin_config", "parameters": [ { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinConfig" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "put": { "tags": [ "basins" ], "summary": "Ensure a basin.", "operationId": "ensure_basin", "parameters": [ { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EnsureBasinRequest" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinInfo" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "delete": { "tags": [ "basins" ], "summary": "Delete a basin.", "operationId": "delete_basin", "parameters": [ { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } } ], "responses": { "202": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "patch": { "tags": [ "basins" ], "summary": "Reconfigure a basin.", "operationId": "reconfigure_basin", "parameters": [ { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinReconfiguration" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasinConfig" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/locations": { "get": { "tags": [ "locations" ], "summary": "List locations.", "operationId": "list_locations", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LocationInfo" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/locations/default": { "get": { "tags": [ "locations" ], "summary": "Get the default location.", "operationId": "get_default_location", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "put": { "tags": [ "locations" ], "summary": "Set the default location.", "operationId": "set_default_location", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationName" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/metrics": { "get": { "tags": [ "metrics" ], "summary": "Account-level metrics.", "operationId": "account_metrics", "parameters": [ { "name": "set", "in": "query", "description": "Metric set to return.", "required": true, "schema": { "$ref": "#/components/schemas/AccountMetricSet" } }, { "name": "start", "in": "query", "description": "Start timestamp as Unix epoch seconds, if applicable for the metric set. Time ranges may span at most 90 days.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "end", "in": "query", "description": "End timestamp as Unix epoch seconds, if applicable for the metric set.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "interval", "in": "query", "description": "Interval to aggregate over for timeseries metric sets.", "required": false, "schema": { "$ref": "#/components/schemas/TimeseriesInterval" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSetResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/metrics/{basin}": { "get": { "tags": [ "metrics" ], "summary": "Basin-level metrics.", "operationId": "basin_metrics", "parameters": [ { "name": "set", "in": "query", "description": "Metric set to return.", "required": true, "schema": { "$ref": "#/components/schemas/BasinMetricSet" } }, { "name": "start", "in": "query", "description": "Start timestamp as Unix epoch seconds, if applicable for the metric set. Time ranges may span at most 90 days.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "end", "in": "query", "description": "End timestamp as Unix epoch seconds, if applicable for the metric set.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "interval", "in": "query", "description": "Interval to aggregate over for timeseries metric sets.", "required": false, "schema": { "$ref": "#/components/schemas/TimeseriesInterval" } }, { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSetResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/metrics/{basin}/{stream}": { "get": { "tags": [ "metrics" ], "summary": "Stream-level metrics.", "operationId": "stream_metrics", "parameters": [ { "name": "set", "in": "query", "description": "Metric set to return.", "required": true, "schema": { "$ref": "#/components/schemas/StreamMetricSet" } }, { "name": "start", "in": "query", "description": "Start timestamp as Unix epoch seconds, if applicable for the metric set. Time ranges may span at most 90 days.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "end", "in": "query", "description": "End timestamp as Unix epoch seconds, if applicable for metric set.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "interval", "in": "query", "description": "Interval to aggregate over for timeseries metric sets.", "required": false, "schema": { "$ref": "#/components/schemas/TimeseriesInterval" } }, { "name": "basin", "in": "path", "description": "Basin name.", "required": true, "schema": { "$ref": "#/components/schemas/BasinNameStr" } }, { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSetResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/streams": { "servers": [ { "url": "https://{basin}.b.s2.dev/v1", "description": "Endpoint for the basin", "variables": { "basin": { "default": "", "description": "Basin name" } } } ], "get": { "tags": [ "streams" ], "summary": "List streams.", "operationId": "list_streams", "parameters": [ { "name": "prefix", "in": "query", "description": "Filter to streams whose names begin with this prefix.\nIt must not contain NUL bytes.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "start_after", "in": "query", "description": "Filter to streams whose names lexicographically start after this string.\nIt must not contain NUL bytes.", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "limit", "in": "query", "description": "Number of results, up to a maximum of 1000.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 1000, "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStreamsResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "post": { "tags": [ "streams" ], "summary": "Create a stream.", "operationId": "create_stream", "parameters": [ { "name": "s2-request-token", "in": "header", "description": "Client-specified request token for idempotent retries.", "required": false, "schema": { "$ref": "#/components/schemas/RequestToken" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/streams/{stream}": { "servers": [ { "url": "https://{basin}.b.s2.dev/v1", "description": "Endpoint for the basin", "variables": { "basin": { "default": "", "description": "Basin name" } } } ], "get": { "tags": [ "streams" ], "summary": "Get stream configuration.", "operationId": "get_stream_config", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamConfig" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "put": { "tags": [ "streams" ], "summary": "Ensure a stream.", "operationId": "ensure_stream", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StreamConfig" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamInfo" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "delete": { "tags": [ "streams" ], "summary": "Delete a stream.", "operationId": "delete_stream", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "responses": { "202": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } }, "patch": { "tags": [ "streams" ], "summary": "Reconfigure a stream.", "operationId": "reconfigure_stream", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamReconfiguration" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamConfig" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/streams/{stream}/records": { "servers": [ { "url": "https://{basin}.b.s2.dev/v1", "description": "Endpoint for the basin", "variables": { "basin": { "default": "", "description": "Basin name" } } } ], "get": { "tags": [ "records" ], "summary": "Read records.", "operationId": "read", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } }, { "name": "s2-format", "in": "header", "description": "Defines the interpretation of record data (header name, header value, and body) with the JSON content type.\nUse `raw` (default) for efficient transmission and storage of Unicode data — storage will be in UTF-8.\nUse `base64` for safe transmission with efficient storage of binary data.", "required": false, "schema": { "$ref": "#/components/schemas/Format" } }, { "name": "s2-encryption-key", "in": "header", "description": "Encryption key material for append and read operations.\nProvide base64-encoded key when stream encryption is enabled.", "required": false, "schema": { "type": "string" } }, { "name": "s2-stream-config", "in": "header", "description": "JSON-encoded `StreamConfig` to apply if the stream is created on append or read.\nUnset fields inherit the basin's default stream configuration.\nIgnored if the stream already exists.\nCompact JSON is preferred.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamConfig" }, "example": { "delete_on_empty": { "min_age_secs": 300 }, "retention_policy": { "age": 3600 } } } } }, { "name": "seq_num", "in": "query", "description": "Start from a sequence number.", "required": false, "schema": { "$ref": "#/components/schemas/u64" } }, { "name": "timestamp", "in": "query", "description": "Start from a timestamp.", "required": false, "schema": { "$ref": "#/components/schemas/u64" } }, { "name": "tail_offset", "in": "query", "description": "Start from number of records before the next sequence number.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "clamp", "in": "query", "description": "Start reading from the tail if the requested position is beyond it.\nOtherwise, a `416 Range Not Satisfiable` response is returned.", "required": false, "schema": { "type": "boolean" } }, { "name": "count", "in": "query", "description": "Record count limit.\nNon-streaming reads are capped by the default limit of 1000 records.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "bytes", "in": "query", "description": "Metered bytes limit.\nNon-streaming reads are capped by the default limit of 1 MiB.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "until", "in": "query", "description": "Exclusive timestamp to read until.", "required": false, "schema": { "$ref": "#/components/schemas/u64" } }, { "name": "wait", "in": "query", "description": "Duration in seconds to wait for new records.\nThe default duration is 0 if there is a bound on `count`, `bytes`, or `until`, and otherwise infinite.\nNon-streaming reads are always bounded on `count` and `bytes`, so you can achieve long poll semantics by specifying a non-zero duration up to 60 seconds.\nIn the context of an SSE or S2S streaming read, the duration will bound how much time can elapse between records throughout the lifetime of the session.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadBatch" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ReadEvent" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "416": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TailResponse" } } } } } }, "post": { "tags": [ "records" ], "summary": "Append records.", "operationId": "append", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } }, { "name": "s2-format", "in": "header", "description": "Defines the interpretation of record data (header name, header value, and body) with the JSON content type.\nUse `raw` (default) for efficient transmission and storage of Unicode data — storage will be in UTF-8.\nUse `base64` for safe transmission with efficient storage of binary data.", "required": false, "schema": { "$ref": "#/components/schemas/Format" } }, { "name": "s2-encryption-key", "in": "header", "description": "Encryption key material for append and read operations.\nProvide base64-encoded key when stream encryption is enabled.", "required": false, "schema": { "type": "string" } }, { "name": "s2-stream-config", "in": "header", "description": "JSON-encoded `StreamConfig` to apply if the stream is created on append or read.\nUnset fields inherit the basin's default stream configuration.\nIgnored if the stream already exists.\nCompact JSON is preferred.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamConfig" }, "example": { "delete_on_empty": { "min_age_secs": 300 }, "retention_policy": { "age": 3600 } } } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendInput" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendAck" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "412": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendConditionFailed" } } } } } } }, "/streams/{stream}/records/tail": { "servers": [ { "url": "https://{basin}.b.s2.dev/v1", "description": "Endpoint for the basin", "variables": { "basin": { "default": "", "description": "Basin name" } } } ], "get": { "tags": [ "records" ], "summary": "Check the tail.", "operationId": "check_tail", "parameters": [ { "name": "stream", "in": "path", "description": "Stream name.", "required": true, "schema": { "$ref": "#/components/schemas/StreamNameStr" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TailResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "408": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } } }, "components": { "schemas": { "AccessTokenIdStr": { "type": "string", "maxLength": 96, "minLength": 1 }, "AccessTokenInfo": { "type": "object", "required": [ "id", "auto_prefix_streams", "scope" ], "properties": { "auto_prefix_streams": { "type": "boolean", "description": "Namespace streams based on the configured stream-level scope." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiration time in RFC 3339 format." }, "id": { "$ref": "#/components/schemas/AccessTokenIdStr", "description": "Access token ID." }, "scope": { "$ref": "#/components/schemas/AccessTokenScope", "description": "Access token scope." } } }, "AccessTokenScope": { "type": "object", "properties": { "access_tokens": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceSet", "description": "Token IDs allowed." } ] }, "basins": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceSet", "description": "Basin names allowed." } ] }, "op_groups": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PermittedOperationGroups", "description": "Access permissions at operation group level." } ] }, "ops": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Operation" }, "description": "Operations allowed for the token.\nA union of allowed operations and groups is used as an effective set of allowed operations." }, "streams": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceSet", "description": "Stream names allowed." } ] } } }, "AccountMetricSet": { "type": "string", "description": "Account-level metric sets.\n`estimated-billable-usage` returns estimated USD by billing dimension and as a `total` series.\nSupports hour (default) and day intervals, aggregating finalized hours. Daily points may be partial.", "enum": [ "active-basins", "account-ops", "estimated-billable-usage" ] }, "AccumulationMetric": { "type": "object", "required": [ "name", "unit", "interval", "values" ], "properties": { "interval": { "$ref": "#/components/schemas/TimeseriesInterval", "description": "The interval at which data points are accumulated." }, "name": { "type": "string", "description": "Timeseries name." }, "unit": { "$ref": "#/components/schemas/MetricUnit", "description": "Unit of the metric." }, "values": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "integer", "format": "int32", "minimum": 0 }, { "type": "number", "format": "double" } ] }, "description": "Timeseries values.\nEach element is a tuple of a timestamp in Unix epoch seconds and a data point.\nThe data point represents the accumulated value for the time period starting at the timestamp, spanning one `interval`." } } }, "AppendAck": { "type": "object", "description": "Success response to an `append` request.", "required": [ "start", "end", "tail" ], "properties": { "end": { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number of the last record that was appended `+ 1`, and timestamp of the last record that was appended.\nThe difference between `end.seq_num` and `start.seq_num` will be the number of records appended." }, "start": { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number and timestamp of the first record that was appended." }, "tail": { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number that will be assigned to the next record on the stream, and timestamp of the last record on the stream.\nThis can be greater than the `end` position in case of concurrent appends." } } }, "AppendConditionFailed": { "oneOf": [ { "type": "object", "title": "fencing token", "description": "Fencing token did not match.\nThe expected fencing token is returned.", "required": [ "fencing_token_mismatch" ], "properties": { "fencing_token_mismatch": { "$ref": "#/components/schemas/FencingToken", "description": "Fencing token did not match.\nThe expected fencing token is returned." } } }, { "type": "object", "title": "seq num", "description": "Sequence number did not match the tail of the stream.\nThe expected next sequence number is returned.", "required": [ "seq_num_mismatch" ], "properties": { "seq_num_mismatch": { "$ref": "#/components/schemas/u64", "description": "Sequence number did not match the tail of the stream.\nThe expected next sequence number is returned." } } } ], "description": "Aborted due to a failed condition." }, "AppendInput": { "type": "object", "description": "Payload of an `append` request.", "required": [ "records" ], "properties": { "fencing_token": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FencingToken", "description": "Enforce a fencing token, which starts out as an empty string that can be overridden by a `fence` command record." } ] }, "match_seq_num": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/u64", "description": "Enforce that the sequence number assigned to the first record matches." } ] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/AppendRecord" }, "description": "Batch of records to append atomically, which must contain at least one record, and no more than 1000.\nThe total size of a batch of records may not exceed 1 MiB of metered bytes." } } }, "AppendRecord": { "type": "object", "description": "Record to be appended to a stream.", "properties": { "body": { "type": "string", "description": "Body of the record." }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/Header" }, "description": "Series of name-value pairs for this record." }, "timestamp": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/u64", "description": "Timestamp for this record.\nThe service will always ensure monotonicity by adjusting it up if necessary to the maximum observed timestamp.\nRefer to stream timestamping configuration for the finer semantics around whether a client-specified timestamp is required, and whether it will be capped at the arrival time." } ] } } }, "BasinConfig": { "type": "object", "properties": { "create_stream_on_append": { "type": "boolean", "description": "Create stream on append if it doesn't exist, using the default stream configuration.", "default": false }, "create_stream_on_read": { "type": "boolean", "description": "Create stream on read if it doesn't exist, using the default stream configuration.", "default": false }, "default_stream_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StreamConfig", "description": "Default stream configuration." } ] }, "stream_cipher": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EncryptionAlgorithm", "description": "Encryption algorithm to apply to newly created streams in the basin." } ] } } }, "BasinInfo": { "type": "object", "required": [ "name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Creation time in RFC 3339 format." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Deletion time in RFC 3339 format, if the basin is being deleted." }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationName", "description": "Basin location." } ] }, "name": { "$ref": "#/components/schemas/BasinNameStr", "description": "Basin name." } } }, "BasinMetricSet": { "type": "string", "enum": [ "storage", "append-ops", "read-ops", "read-throughput", "append-throughput", "basin-ops" ] }, "BasinNameStr": { "type": "string", "maxLength": 48, "minLength": 8 }, "BasinReconfiguration": { "type": "object", "properties": { "create_stream_on_append": { "type": [ "boolean", "null" ], "description": "Create a stream on append." }, "create_stream_on_read": { "type": [ "boolean", "null" ], "description": "Create a stream on read." }, "default_stream_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StreamReconfiguration", "description": "Basin configuration." } ] }, "stream_cipher": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EncryptionAlgorithm", "description": "Encryption algorithm to apply to newly created streams in the basin." } ] } } }, "BasinState": { "type": "string", "enum": [ "active", "deleting" ] }, "CreateBasinRequest": { "type": "object", "required": [ "basin" ], "properties": { "basin": { "$ref": "#/components/schemas/BasinNameStr", "description": "Basin name which must be globally unique.\nIt can be between 8 and 48 bytes in length, and comprise lowercase letters, numbers and hyphens.\nIt cannot begin or end with a hyphen." }, "config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BasinConfig", "description": "Basin configuration." } ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationName", "description": "Basin location.\nIf omitted when creating, uses the default location for the account." } ] } } }, "CreateStreamRequest": { "type": "object", "required": [ "stream" ], "properties": { "config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StreamConfig", "description": "Stream configuration." } ] }, "stream": { "$ref": "#/components/schemas/StreamNameStr", "description": "Stream name that is unique to the basin.\nIt can be between 1 and 512 bytes in length, and must not contain NUL bytes." } } }, "DeleteOnEmptyConfig": { "type": "object", "properties": { "min_age_secs": { "type": "integer", "format": "int64", "description": "Minimum age in seconds before an empty stream can be deleted.\nSet to 0 (default) to disable delete-on-empty (don't delete automatically).", "minimum": 0 } } }, "DeleteOnEmptyReconfiguration": { "type": "object", "properties": { "min_age_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum age in seconds before an empty stream can be deleted.\nSet to 0 to disable delete-on-empty (don't delete automatically).", "minimum": 0 } } }, "EncryptionAlgorithm": { "type": "string", "enum": [ "aegis-256", "aes-256-gcm" ] }, "EnsureBasinRequest": { "type": "object", "properties": { "config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BasinConfig", "description": "Basin configuration." } ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocationName", "description": "Basin location.\nIf omitted when creating, uses the default location for the account.\nThis cannot be changed." } ] } } }, "ErrorInfo": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "FencingToken": { "type": "string", "maxLength": 36 }, "Format": { "type": "string", "enum": [ "raw", "base64" ] }, "GaugeMetric": { "type": "object", "required": [ "name", "unit", "values" ], "properties": { "name": { "type": "string", "description": "Timeseries name." }, "unit": { "$ref": "#/components/schemas/MetricUnit", "description": "Unit of the metric." }, "values": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "integer", "format": "int32", "minimum": 0 }, { "type": "number", "format": "double" } ] }, "description": "Timeseries values.\nEach element is a tuple of a timestamp in Unix epoch seconds and a data point.\nThe data point represents the value at the instant of the timestamp." } } }, "Header": { "type": "array", "items": { "type": "string" }, "maxItems": 2, "minItems": 2 }, "InfiniteRetention": { "type": "object" }, "IssueAccessTokenRequest": { "type": "object", "required": [ "id", "scope" ], "properties": { "auto_prefix_streams": { "type": "boolean", "description": "Namespace streams based on the configured stream-level scope, which must be a prefix.\nStream name arguments will be automatically prefixed, and the prefix will be stripped when listing streams.", "default": false }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiration time in RFC 3339 format.\nIf not set, the expiration will be set to that of the requestor's token." }, "id": { "$ref": "#/components/schemas/AccessTokenIdStr", "description": "Access token ID.\nIt must be unique to the account and between 1 and 96 bytes in length, and must not\ncontain NUL bytes." }, "scope": { "$ref": "#/components/schemas/AccessTokenScope", "description": "Access token scope." } } }, "IssueAccessTokenResponse": { "type": "object", "required": [ "access_token" ], "properties": { "access_token": { "type": "string", "description": "Created access token." } } }, "LabelMetric": { "type": "object", "required": [ "name", "values" ], "properties": { "name": { "type": "string", "description": "Label name." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Label values." } } }, "ListAccessTokensResponse": { "type": "object", "required": [ "access_tokens", "has_more" ], "properties": { "access_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/AccessTokenInfo" }, "description": "Matching access tokens.", "maxItems": 1000 }, "has_more": { "type": "boolean", "description": "Indicates that there are more access tokens that match the criteria." } } }, "ListBasinsResponse": { "type": "object", "required": [ "basins", "has_more" ], "properties": { "basins": { "type": "array", "items": { "$ref": "#/components/schemas/BasinInfo" }, "description": "Matching basins.", "maxItems": 1000 }, "has_more": { "type": "boolean", "description": "Indicates that there are more basins that match the criteria." } } }, "ListStreamsResponse": { "type": "object", "required": [ "streams", "has_more" ], "properties": { "has_more": { "type": "boolean", "description": "Indicates that there are more results that match the criteria." }, "streams": { "type": "array", "items": { "$ref": "#/components/schemas/StreamInfo" }, "description": "Matching streams.", "maxItems": 1000 } } }, "LocationInfo": { "type": "object", "required": [ "name", "is_private" ], "properties": { "default_storage_class": { "type": [ "string", "null" ], "description": "Default [storage class](https://s2.dev/docs/storage-classes) for this location." }, "is_private": { "type": "boolean", "description": "Location represents a private placement, limited by account." }, "name": { "$ref": "#/components/schemas/LocationName", "description": "Location name." }, "storage_classes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "[Storage classes](https://s2.dev/docs/storage-classes) available to the account in this location." } } }, "LocationName": { "type": "string", "maxLength": 64, "minLength": 1 }, "Metric": { "oneOf": [ { "type": "object", "description": "Single named value.", "required": [ "scalar" ], "properties": { "scalar": { "$ref": "#/components/schemas/ScalarMetric", "description": "Single named value." } } }, { "type": "object", "description": "Named series of `(timestamp, value)` points representing an accumulation over a specified interval.", "required": [ "accumulation" ], "properties": { "accumulation": { "$ref": "#/components/schemas/AccumulationMetric", "description": "Named series of `(timestamp, value)` points representing an accumulation over a specified interval." } } }, { "type": "object", "description": "Named series of `(timestamp, value)` points each representing an instantaneous value.", "required": [ "gauge" ], "properties": { "gauge": { "$ref": "#/components/schemas/GaugeMetric", "description": "Named series of `(timestamp, value)` points each representing an instantaneous value." } } }, { "type": "object", "description": "Set of string labels.", "required": [ "label" ], "properties": { "label": { "$ref": "#/components/schemas/LabelMetric", "description": "Set of string labels." } } } ] }, "MetricSetResponse": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" }, "description": "Metrics comprising the set." } } }, "MetricUnit": { "type": "string", "enum": [ "bytes", "operations", "usd" ] }, "Operation": { "type": "string", "enum": [ "list-basins", "create-basin", "delete-basin", "reconfigure-basin", "get-basin-config", "issue-access-token", "revoke-access-token", "list-access-tokens", "list-streams", "create-stream", "delete-stream", "get-stream-config", "reconfigure-stream", "check-tail", "append", "read", "trim", "fence", "account-metrics", "basin-metrics", "stream-metrics", "list-locations", "get-default-location", "set-default-location" ] }, "PermittedOperationGroups": { "type": "object", "properties": { "account": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadWritePermissions", "description": "Account-level access permissions." } ] }, "basin": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadWritePermissions", "description": "Basin-level access permissions." } ] }, "stream": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadWritePermissions", "description": "Stream-level access permissions." } ] } } }, "PingEventData": { "type": "object", "required": [ "timestamp", "tail" ], "properties": { "tail": { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number that will be assigned to the next record on the stream, and timestamp of the last record." }, "timestamp": { "type": "integer", "format": "int64", "description": "Time the ping was emitted, as Unix epoch milliseconds.", "minimum": 0 } } }, "ReadBatch": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SequencedRecord" }, "description": "Records that are durably sequenced on the stream, retrieved based on the requested criteria.\nThis can only be empty in response to a unary read (i.e. not SSE), if the request cannot be satisfied without violating an explicit bound (`count`, `bytes`, or `until`)." }, "tail": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number that will be assigned to the next record on the stream, and timestamp of the last record.\nThis will only be present when reading recent records." } ] } } }, "ReadEvent": { "oneOf": [ { "type": "object", "title": "batch", "required": [ "event", "data", "id" ], "properties": { "data": { "$ref": "#/components/schemas/ReadBatch" }, "event": { "type": "string", "enum": [ "batch" ] }, "id": { "type": "string", "pattern": "^[0-9]+,[0-9]+,[0-9]+$" } } }, { "type": "object", "title": "error", "required": [ "event", "data" ], "properties": { "data": { "type": "string" }, "event": { "type": "string", "enum": [ "error" ] } } }, { "type": "object", "title": "ping", "required": [ "event", "data" ], "properties": { "data": { "$ref": "#/components/schemas/PingEventData" }, "event": { "type": "string", "enum": [ "ping" ] } } } ] }, "ReadWritePermissions": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Read permission.", "default": false }, "write": { "type": "boolean", "description": "Write permission.", "default": false } } }, "RequestToken": { "type": "string", "maxLength": 36 }, "ResourceSet": { "oneOf": [ { "type": "object", "title": "exact", "description": "Match only the resource with this exact name.\nUse an empty string to match no resources.", "required": [ "exact" ], "properties": { "exact": { "type": "string", "description": "Match only the resource with this exact name.\nUse an empty string to match no resources." } } }, { "type": "object", "title": "prefix", "description": "Match all resources that start with this prefix.\nUse an empty string to match all resource.", "required": [ "prefix" ], "properties": { "prefix": { "type": "string", "description": "Match all resources that start with this prefix.\nUse an empty string to match all resource." } } } ] }, "RetentionPolicy": { "oneOf": [ { "type": "object", "description": "Age in seconds for automatic trimming of records older than this threshold.\nThis must be set to a value greater than 0 seconds.", "required": [ "age" ], "properties": { "age": { "type": "integer", "format": "int64", "description": "Age in seconds for automatic trimming of records older than this threshold.\nThis must be set to a value greater than 0 seconds.", "minimum": 0 } } }, { "type": "object", "description": "Retain records unless explicitly trimmed.", "required": [ "infinite" ], "properties": { "infinite": { "$ref": "#/components/schemas/InfiniteRetention", "description": "Retain records unless explicitly trimmed." } } } ] }, "ScalarMetric": { "type": "object", "required": [ "name", "unit", "value" ], "properties": { "name": { "type": "string", "description": "Metric name." }, "unit": { "$ref": "#/components/schemas/MetricUnit", "description": "Unit of the metric." }, "value": { "type": "number", "format": "double", "description": "Metric value." } } }, "SequencedRecord": { "type": "object", "description": "Record that is durably sequenced on a stream.", "required": [ "seq_num", "timestamp" ], "properties": { "body": { "type": "string", "description": "Body of the record." }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/Header" }, "description": "Series of name-value pairs for this record." }, "seq_num": { "$ref": "#/components/schemas/u64", "description": "Sequence number assigned by the service." }, "timestamp": { "$ref": "#/components/schemas/u64", "description": "Timestamp for this record." } } }, "StreamConfig": { "type": "object", "properties": { "delete_on_empty": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeleteOnEmptyConfig", "description": "Delete-on-empty configuration." } ] }, "retention_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RetentionPolicy", "description": "Retention policy for the stream.\nIf unspecified, the default is to retain records for 7 days." } ] }, "storage_class": { "type": [ "string", "null" ], "description": "[Storage class](https://s2.dev/docs/storage-classes) for recent writes." }, "timestamping": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TimestampingConfig", "description": "Timestamping behavior." } ] } } }, "StreamInfo": { "type": "object", "required": [ "name", "created_at" ], "properties": { "cipher": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EncryptionAlgorithm", "description": "Encryption algorithm for this stream, if encryption is enabled." } ] }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time in RFC 3339 format." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Deletion time in RFC 3339 format, if the stream is being deleted." }, "name": { "$ref": "#/components/schemas/StreamNameStr", "description": "Stream name." } } }, "StreamMetricSet": { "type": "string", "enum": [ "storage" ] }, "StreamNameStr": { "type": "string", "maxLength": 512, "minLength": 1 }, "StreamPosition": { "type": "object", "description": "Position of a record in a stream.", "required": [ "seq_num", "timestamp" ], "properties": { "seq_num": { "$ref": "#/components/schemas/u64", "description": "Sequence number assigned by the service." }, "timestamp": { "$ref": "#/components/schemas/u64", "description": "Timestamp, which may be client-specified or assigned by the service.\nIf it is assigned by the service, it will represent milliseconds since Unix epoch." } } }, "StreamReconfiguration": { "type": "object", "properties": { "delete_on_empty": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeleteOnEmptyReconfiguration", "description": "Delete-on-empty configuration." } ] }, "retention_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RetentionPolicy", "description": "Retention policy for the stream.\nIf unspecified, the default is to retain records for 7 days." } ] }, "storage_class": { "type": [ "string", "null" ], "description": "[Storage class](https://s2.dev/docs/storage-classes) for recent writes." }, "timestamping": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TimestampingReconfiguration", "description": "Timestamping behavior." } ] } } }, "TailResponse": { "type": "object", "required": [ "tail" ], "properties": { "tail": { "$ref": "#/components/schemas/StreamPosition", "description": "Sequence number that will be assigned to the next record on the stream, and timestamp of the last record." } } }, "TimeseriesInterval": { "type": "string", "enum": [ "minute", "hour", "day" ] }, "TimestampingConfig": { "type": "object", "properties": { "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TimestampingMode", "description": "Timestamping mode for appends that influences how timestamps are handled." } ] }, "uncapped": { "type": [ "boolean", "null" ], "description": "Allow client-specified timestamps to exceed the arrival time.\nIf this is `false` or not set, client timestamps will be capped at the arrival time." } } }, "TimestampingMode": { "type": "string", "enum": [ "client-prefer", "client-require", "arrival" ] }, "TimestampingReconfiguration": { "type": "object", "properties": { "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TimestampingMode", "description": "Timestamping mode for appends that influences how timestamps are handled." } ] }, "uncapped": { "type": [ "boolean", "null" ], "description": "Allow client-specified timestamps to exceed the arrival time." } } }, "u64": { "type": "integer", "format": "int64", "minimum": 0 } }, "securitySchemes": { "access_token": { "type": "http", "scheme": "bearer", "description": "Bearer authentication header of the form `Bearer `, where `` is your access token." } } }, "security": [ { "access_token": [] } ], "tags": [ { "name": "metrics", "description": "Usage metrics and data." }, { "name": "basins", "description": "Manage basins" }, { "name": "access-tokens", "description": "Manage access tokens" }, { "name": "locations", "description": "Manage locations" }, { "name": "streams", "description": "Manage streams" }, { "name": "records", "description": "Manage records" } ] }