{ "openapi": "3.1.0", "info": { "title": "quiva.ai Gateway", "description": "A comprehensive interface for managing key-value stores, object stores, streams", "contact": { "name": "quiva.ai Support", "url": "https://quiva.ai/help-center/" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.quiva.ai", "description": "Production API server" } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "oauth2": { "type": "oauth2", "description": "API integration client credentials. Tokens only work on the task-sync routes in workspaces.", "flows": { "clientCredentials": { "tokenUrl": "https://api.quiva.ai/oauth/token", "scopes": {} } } } }, "parameters": { "bucketName": { "name": "bucket", "in": "path", "description": "Name of the bucket", "required": true, "schema": { "type": "string" } }, "entryKey": { "name": "key", "in": "path", "description": "Key of the entry", "required": true, "schema": { "type": "string" } }, "streamName": { "name": "name", "in": "path", "description": "Name of the stream", "required": true, "schema": { "type": "string" } }, "stream": { "name": "stream", "in": "path", "description": "Name of the stream", "required": true, "schema": { "type": "string" } } }, "schemas": { "StorageType": { "type": "string", "enum": [ "file", "memory" ] }, "IndexMapping": { "type": "object", "required": [ "field", "field_type" ], "properties": { "field": { "type": "string", "description": "Field name to be indexed" }, "field_type": { "type": "string", "description": "Type of the field", "enum": [ "text", "number", "date", "boolean", "keyword" ] } } }, "IndexRequest": { "type": "object", "required": [ "mappings", "partitions", "replicas", "storage_type" ], "properties": { "mappings": { "type": "array", "description": "Field mappings for indexing", "items": { "$ref": "#/components/schemas/IndexMapping" } }, "partitions": { "type": "integer", "description": "Number of partitions for the index", "minimum": 1 }, "replicas": { "type": "integer", "description": "Number of replicas for the index", "minimum": 1 }, "storage_type": { "$ref": "#/components/schemas/StorageType" }, "stream": { "type": "string", "description": "Optional stream name for the index" } } }, "CreateKVBucketRequest": { "type": "object", "required": [ "bucket" ], "properties": { "bucket": { "type": "string", "description": "Name of the bucket to create" }, "compression": { "type": "boolean", "description": "Whether to enable compression", "default": false }, "description": { "type": "string", "description": "Description of the bucket" }, "history": { "type": "integer", "description": "Number of historical versions to keep", "minimum": 1, "default": 1 }, "indexing": { "$ref": "#/components/schemas/IndexRequest" }, "max_bytes": { "type": "integer", "description": "Maximum size of the bucket in bytes", "minimum": 1, "format": "int64" }, "max_value_size": { "type": "integer", "description": "Maximum size of individual values in bytes", "minimum": 1, "format": "int32" }, "replicas": { "type": "integer", "description": "Number of replicas", "minimum": 1, "default": 1 }, "storage": { "$ref": "#/components/schemas/StorageType" } } }, "UpdateKVBucketRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated description of the bucket" }, "max_bytes": { "type": "integer", "description": "Updated maximum size of the bucket in bytes", "minimum": 1 }, "max_value_size": { "type": "integer", "description": "Updated maximum size of individual values in bytes", "minimum": 1 }, "indexing": { "$ref": "#/components/schemas/IndexRequest" } } }, "CreateObjectBucketRequest": { "type": "object", "required": [ "bucket" ], "properties": { "bucket": { "type": "string", "description": "Name of the bucket to create" }, "description": { "type": "string", "description": "Description of the bucket" }, "max_bytes": { "type": "integer", "description": "Maximum size of the bucket in bytes", "minimum": 1 }, "replicas": { "type": "integer", "description": "Number of replicas", "minimum": 1, "default": 1 }, "storage": { "$ref": "#/components/schemas/StorageType" } } }, "UpdateObjectBucketRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated description of the bucket" }, "max_bytes": { "type": "integer", "description": "Updated maximum size of the bucket in bytes", "minimum": 1 } } }, "StreamSource": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the source stream" }, "opt_start_seq": { "type": "integer", "description": "Optional starting sequence number" }, "opt_start_time": { "type": "string", "format": "date-time", "description": "Optional starting time" }, "filter_subject": { "type": "string", "description": "Optional subject filter" }, "domain": { "type": "string", "description": "Optional domain" } } }, "CreateStreamRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the stream to create" }, "description": { "type": "string", "description": "Description of the stream" }, "subjects": { "type": "array", "description": "Subject patterns to capture", "items": { "type": "string" } }, "max_consumers": { "type": "integer", "description": "Maximum number of consumers", "minimum": 1 }, "max_msgs": { "type": "integer", "description": "Maximum number of messages", "minimum": 1 }, "max_bytes": { "type": "integer", "description": "Maximum size in bytes", "minimum": 1 }, "discard": { "type": "integer", "description": "Discard policy (0 = old, 1 = new)", "enum": [ 0, 1 ], "default": 0 }, "max_msgs_per_subject": { "type": "integer", "description": "Maximum messages per subject", "minimum": 1 }, "max_msg_size": { "type": "integer", "description": "Maximum message size in bytes", "minimum": 1 }, "storage": { "$ref": "#/components/schemas/StorageType" }, "num_replicas": { "type": "integer", "description": "Number of replicas", "minimum": 1, "default": 1 }, "mirror": { "$ref": "#/components/schemas/StreamSource" }, "sources": { "type": "array", "description": "Optional sources configuration", "items": { "$ref": "#/components/schemas/StreamSource" } }, "sealed": { "type": "boolean", "description": "Whether the stream is sealed", "default": false }, "deny_delete": { "type": "boolean", "description": "Whether deletes are denied", "default": false }, "deny_purge": { "type": "boolean", "description": "Whether purges are denied", "default": false } } }, "UpdateStreamRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated description of the stream" }, "max_msgs": { "type": "integer", "description": "Updated maximum number of messages", "minimum": 1 }, "max_bytes": { "type": "integer", "description": "Updated maximum size in bytes", "minimum": 1 }, "max_msg_size": { "type": "integer", "description": "Updated maximum message size in bytes", "minimum": 1 } } }, "PurgeStreamRequest": { "type": "object", "properties": { "keep": { "type": "integer", "description": "Number of messages to keep", "minimum": 0 }, "up_to_sequence": { "type": "integer", "description": "Purge up to this sequence number", "minimum": 1 }, "subject": { "type": "string", "description": "Subject filter for purging" } } }, "KVEntryValue": { "type": "object", "description": "Value to store in KV entry", "additionalProperties": true }, "Metadata": { "type": "object", "properties": { "bucket": { "type": "string", "description": "Bucket name" }, "duration": { "type": "string", "description": "Operation duration" }, "field": { "type": "string", "description": "Search field" }, "hits": { "type": "integer", "description": "Number of hits" }, "index_duration": { "type": "string", "description": "Index search duration" }, "index_hits": { "type": "integer", "description": "Number of index hits" }, "index_name": { "type": "string", "description": "Index name" }, "index_partitions": { "type": "integer", "description": "Number of index partitions" }, "key": { "type": "string", "description": "Entry key" }, "limit": { "type": "integer", "description": "Query limit" }, "partitions": { "type": "integer", "description": "Number of partitions" }, "search": { "type": "string", "description": "Search term" }, "stream": { "type": "string", "description": "Stream name" }, "subject": { "type": "string", "description": "Subject pattern" } } }, "BucketListItem": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "entry_total": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "placement": { "type": "object", "properties": { "cluster": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "created": { "type": "string", "format": "date-time" } } }, "BucketListResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "description": "List of kv buckets", "items": { "$ref": "#/components/schemas/BucketListItem" } }, "results_total": { "type": "integer", "description": "Total number of kv buckets returned", "example": 2 } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "KVBucketResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "status": { "type": "object", "properties": { "backing_store": { "type": "string" }, "bucket": { "type": "string" }, "description": { "type": "string" }, "bytes": { "type": "integer", "format": "uint64" }, "history": { "type": "integer", "format": "int64" }, "ttl": { "type": "integer", "format": "int64" }, "is_compressed": { "type": "boolean" } } }, "config": { "type": "object", "properties": { "bucket": { "type": "string" }, "max_bytes": { "type": "integer", "format": "int64" }, "max_value_size": { "type": "integer", "format": "int32" }, "history": { "type": "integer", "format": "int64" }, "num_replicas": { "type": "integer" } } }, "stream_info": { "type": "object", "properties": { "cluster": { "type": "object", "properties": { "leader": { "type": "string" }, "name": { "type": "string" }, "replicas": { "type": "array", "items": { "type": "object", "properties": { "active": { "type": "integer", "format": "uint64" }, "current": { "type": "boolean" }, "name": { "type": "string" } } } } } }, "config": { "type": "object", "properties": { "allow_direct": { "type": "boolean" }, "allow_rollup_hdrs": { "type": "boolean" }, "compression": { "type": "string" }, "consumer_limits": { "type": "object", "properties": { "inactive_threshold": { "type": "integer", "format": "int64" }, "max_ack_pending": { "type": "integer" } } }, "deny_delete": { "type": "boolean" }, "discard": { "type": "string", "enum": [ "old", "new" ] }, "duplicate_window": { "type": "integer", "format": "int64" }, "index_config": { "type": "object", "properties": { "engine": { "type": "string" }, "idBy": { "type": "string" }, "partitions": { "type": "integer" }, "version": { "type": "integer" } } }, "max_age": { "type": "integer", "format": "int64" }, "max_bytes": { "type": "integer", "format": "int64" }, "max_consumers": { "type": "integer" }, "max_msg_size": { "type": "integer", "format": "int32" }, "max_msgs": { "type": "integer", "format": "int64" }, "max_msgs_per_subject": { "type": "integer", "format": "int64" }, "mirror_direct": { "type": "boolean" }, "name": { "type": "string" }, "num_replicas": { "type": "integer" }, "retention": { "type": "string", "enum": [ "Limits", "Interest", "WorkQueue" ] }, "storage": { "type": "string", "enum": [ "file", "memory" ] }, "subject_transform": { "type": "object", "properties": { "dest": { "type": "string" }, "src": { "type": "string" } } }, "subjects": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "created": { "type": "string", "format": "date-time" }, "state": { "type": "object", "properties": { "bytes": { "type": "integer", "format": "uint64" }, "consumer_count": { "type": "integer" }, "deleted": { "type": "array", "items": { "type": "integer", "format": "uint64" } }, "first_seq": { "type": "integer", "format": "uint64" }, "first_ts": { "type": "string", "format": "date-time" }, "last_seq": { "type": "integer", "format": "uint64" }, "last_ts": { "type": "string", "format": "date-time" }, "messages": { "type": "integer", "format": "uint64" }, "num_deleted": { "type": "integer" }, "num_subjects": { "type": "integer", "format": "uint64" }, "subjects": { "type": "object" } } } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ObjectBucketResponse": { "type": "object", "properties": { "body": { "type": "object", "additionalProperties": true }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "KVEntriesItem": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "additionalProperties": true } } }, "KVEntriesResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/KVEntriesItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "KVEntryResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "additionalProperties": true } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ObjectEntriesItem": { "type": "object", "properties": { "key": { "type": "string" }, "size": { "type": "integer" } } }, "ObjectEntriesResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectEntriesItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "StreamListItem": { "type": "object", "properties": { "name": { "type": "string" }, "subjects": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "created": { "type": "string", "format": "date-time" }, "messages_total": { "type": "integer" }, "placement": { "type": "object", "properties": { "cluster": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "description": { "type": "string" } } }, "StreamListResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/StreamListItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "StreamResponse": { "type": "object", "properties": { "body": { "type": "object", "additionalProperties": true } } }, "PublishMessageRequest": { "type": "object", "required": [ "stream", "subject", "body" ], "properties": { "stream": { "type": "string", "description": "Stream name" }, "subject": { "type": "string", "description": "Message subject" }, "body": { "type": "object", "description": "Message payload", "additionalProperties": true } } }, "SearchKVItem": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "SearchByKeyResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchKVItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SearchStreamItem": { "type": "object", "properties": { "subject": { "type": "string" }, "value": { "type": "string" }, "created": { "type": "string", "format": "date-time" } } }, "StreamSearchResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchStreamItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SuccessMessage": { "type": "object", "properties": { "message": { "type": "string", "example": "success" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Error message" } } } }, "responses": { "SuccessResponse": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessage" }, "example": { "message": "success" } } } }, "BadRequestError": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "validation_error" } } } }, "UnauthorizedError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "unauthorized" } } } }, "NotFoundError": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "not_found" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "internal_error" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "paths": { "/storage/kv": { "get": { "tags": [ "KV Buckets" ], "summary": "List all KV buckets", "description": "Retrieves a list of all key-value buckets in the system", "operationId": "getKVBucketList", "x-resource-type": "service", "responses": { "200": { "description": "Successfully retrieved KV bucket list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketListResponse" }, "example": { "body": { "results": [ { "created": "2025-05-08T12:49:45.02903891Z", "name": "bucket1", "description": "First bucket", "entry_total": 0 }, { "created": "2025-05-08T12:49:45.02903891Z", "name": "bucket2", "description": "Second bucket", "entry_total": 12 } ], "results_total": 2 }, "metadata": { "duration": "5ms" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "KV Buckets" ], "summary": "Create a new KV bucket", "description": "Creates a new key-value bucket with optional indexing configuration", "operationId": "createKVBucket", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKVBucketRequest" }, "examples": { "simple": { "summary": "Simple bucket without indexing", "value": { "bucket": "user-preferences", "description": "Stores user preference settings", "compression": false, "history": 1, "replicas": 1, "storage": "file" } }, "with-indexing": { "summary": "Bucket with full-text indexing", "value": { "bucket": "products", "description": "Product catalog with search", "compression": true, "history": 5, "max_bytes": 10737418240, "max_value_size": 1048576, "replicas": 3, "storage": "file", "indexing": { "mappings": [ { "field": "name", "field_type": "text" }, { "field": "price", "field_type": "number" } ], "partitions": 3, "replicas": 2, "storage_type": "file" } } }, "memory-cache": { "summary": "In-memory bucket for caching", "value": { "bucket": "rate-limits", "description": "Rate limiting counters", "compression": false, "history": 1, "max_bytes": 104857600, "replicas": 1, "storage": "memory" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/kv/{bucket}": { "get": { "tags": [ "KV Buckets" ], "summary": "Get KV bucket details", "description": "Retrieves information about a specific KV bucket", "operationId": "getKVBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "description": "Successfully retrieved bucket information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KVBucketResponse" }, "example": { "body": { "status": { "backing_store": "BStream", "bucket": "products", "description": "Product catalog", "bytes": 52428800, "history": 5, "ttl": 0, "is_compressed": true }, "config": { "bucket": "products", "max_bytes": 10737418240, "max_value_size": 1048576, "history": 5, "num_replicas": 3 }, "stream_info": { "cluster": { "leader": "node-1", "name": "quiva-cluster", "replicas": [ { "active": 0, "current": true, "name": "node-2" }, { "active": 0, "current": true, "name": "node-3" } ] }, "config": { "name": "KV_products", "subjects": [ "$KV.products.>" ], "retention": "Limits", "storage": "file", "num_replicas": 3, "discard": "old" }, "created": "2025-05-08T12:49:45.029Z", "state": { "messages": 1250, "bytes": 52428800, "first_seq": 1, "last_seq": 1250, "consumer_count": 2, "num_subjects": 1250 } } }, "metadata": { "bucket": "products", "duration": "3ms" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "KV Buckets" ], "summary": "Create or update a KV bucket", "description": "Creates a new key-value bucket with optional indexing or updates it if one does not exist", "operationId": "createOrUpdateKVBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKVBucketRequest" }, "examples": { "update-description": { "summary": "Update bucket description", "value": { "description": "Updated product catalog with extended metadata" } }, "update-limits": { "summary": "Update storage limits", "value": { "max_bytes": 21474836480, "max_value_size": 2097152 } }, "add-indexing": { "summary": "Add indexing to existing bucket", "value": { "indexing": { "mappings": [ { "field": "title", "field_type": "text" }, { "field": "category", "field_type": "keyword" } ], "partitions": 2, "replicas": 1, "storage_type": "file" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "KV Buckets" ], "summary": "Delete KV bucket", "description": "Deletes a key-value bucket and all its contents", "operationId": "deleteKVBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/kv/{bucket}/purge": { "delete": { "tags": [ "KV Buckets" ], "summary": "Purge KV bucket", "description": "Purges all data from a key-value bucket while keeping the bucket configuration", "operationId": "purgeKVBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/kv/{bucket}/entries": { "get": { "tags": [ "KV Entries" ], "summary": "Get latest KV entries", "description": "Retrieves the latest entries from a key-value bucket", "operationId": "getKVLatestEntries", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "name": "limit", "in": "query", "description": "Maximum number of entries to retrieve", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "example": 25 } ], "responses": { "200": { "description": "Successfully retrieved entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KVEntriesResponse" }, "example": { "body": { "results": [ { "key": "key1", "value": { "name": "John Doe", "age": 30 } }, { "key": "key2", "value": { "name": "Jane Smith", "age": 28 } } ], "results_total": 2 }, "metadata": { "bucket": "my-bucket", "limit": 10 } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Create or update several KV entries", "description": "Writes several entries in one call.", "operationId": "putKVEntries", "tags": [ "KV Entries" ], "x-resource-type": "service", "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } }, "x-path-derived": true }, "delete": { "summary": "Delete several KV entries", "description": "Deletes the entries named by repeated key query parameters.", "operationId": "deleteKVEntries", "tags": [ "KV Entries" ], "x-resource-type": "service", "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/kv/{bucket}/entries/{key}": { "get": { "tags": [ "KV Entries" ], "summary": "Get KV entry", "description": "Retrieves a specific entry from a key-value bucket", "operationId": "getKVEntry", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "$ref": "#/components/parameters/entryKey" } ], "responses": { "200": { "description": "Successfully retrieved entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KVEntryResponse" }, "example": { "body": { "key": "my-key", "value": { "name": "John Doe", "age": 30 } }, "metadata": { "bucket": "my-bucket", "key": "my-key" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "KV Entries" ], "summary": "Create or update KV entry", "description": "Creates or updates a key-value entry in the specified bucket", "operationId": "putKVEntry", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "$ref": "#/components/parameters/entryKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KVEntryValue" }, "example": { "name": "John Doe", "email": "john@example.com", "age": 30 } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "KV Entries" ], "summary": "Delete KV entry", "description": "Deletes a specific entry from a key-value bucket", "operationId": "deleteKVEntry", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "$ref": "#/components/parameters/entryKey" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/kv/{bucket}/search-by-key": { "get": { "tags": [ "KV Search" ], "summary": "Search KV entries by key pattern", "description": "Searches for KV entries by key pattern (e.g., 'user*')", "operationId": "searchKVByKey", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "name": "search", "in": "query", "description": "Key pattern to search for (supports wildcards)", "required": true, "schema": { "type": "string" }, "example": "user*" }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "example": 50 } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchByKeyResponse" }, "example": { "body": { "results": [ { "key": "user123", "value": { "name": "John Doe", "email": "john@example.com" } }, { "key": "user456", "value": { "name": "Jane Smith", "email": "jane@example.com" } } ], "results_total": 2 }, "metadata": { "bucket": "my-bucket", "search": "user*", "hits": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/obj": { "get": { "tags": [ "Object Store" ], "summary": "List all object store buckets", "description": "Retrieves a list of all object store buckets", "operationId": "getObjectStoreBucketList", "x-resource-type": "service", "responses": { "200": { "description": "Successfully retrieved object bucket list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketListResponse" }, "examples": { "multiple_buckets": { "summary": "Multiple buckets", "value": { "body": { "results": [ { "name": "media-assets", "description": "Production media files", "entry_total": 1523, "metadata": { "environment": "production", "team": "content" }, "placement": { "cluster": "us-east-1", "tags": [ "ssd", "high-iops" ] }, "created": "2024-01-15T10:30:00Z" }, { "name": "user-uploads", "description": "User-generated content", "entry_total": 8492, "metadata": { "environment": "production" }, "placement": { "cluster": "us-west-2", "tags": [ "standard" ] }, "created": "2024-02-20T14:15:00Z" } ], "results_total": 2 }, "metadata": { "duration": "12ms" } } }, "empty_list": { "summary": "No buckets", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "duration": "3ms" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Object Store" ], "summary": "Create object store bucket", "description": "Creates a new object store bucket", "operationId": "createObjectStoreBucket", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectBucketRequest" }, "examples": { "basic": { "summary": "Basic bucket creation", "value": { "bucket": "app-documents", "description": "Application document storage" } }, "with_limits": { "summary": "Bucket with size limits", "value": { "bucket": "user-uploads", "description": "User file uploads with 10GB limit", "max_bytes": 10737418240, "replicas": 3, "storage": "file" } }, "memory_storage": { "summary": "In-memory bucket for caching", "value": { "bucket": "temp-cache", "description": "Temporary cache storage", "max_bytes": 536870912, "replicas": 1, "storage": "memory" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/obj/{bucket}": { "get": { "tags": [ "Object Store" ], "summary": "Get an object store bucket", "description": "Retrieves detailed information about a specific object store, including its configuration and current state.", "operationId": "getObjectStoreBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "description": "Successfully retrieved bucket information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectBucketResponse" }, "example": { "body": { "status": { "bucket": "media-assets", "description": "Production media files", "bytes": 5368709120, "objects": 1523, "sealed": false }, "config": { "bucket": "media-assets", "max_bytes": 10737418240, "num_replicas": 3, "storage": "file", "placement": { "cluster": "us-east-1", "tags": [ "ssd", "high-iops" ] } }, "stream_info": { "cluster": { "name": "prod-cluster", "leader": "node-1", "replicas": [ { "name": "node-2", "current": true, "active": 0 }, { "name": "node-3", "current": true, "active": 0 } ] }, "created": "2024-01-15T10:30:00Z", "state": { "bytes": 5368709120, "messages": 1523, "first_seq": 1, "last_seq": 1523, "first_ts": "2024-01-15T10:31:00Z", "last_ts": "2024-11-28T09:45:00Z" } } }, "metadata": { "bucket": "media-assets", "duration": "8ms" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Object Store" ], "summary": "Create or update object store", "description": "Creates a new object store bucket if one does not exist or updates it otherwise", "operationId": "createOrUpdateObjectStoreBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateObjectBucketRequest" }, "examples": { "update_description": { "summary": "Update description only", "value": { "description": "Updated bucket description" } }, "increase_capacity": { "summary": "Increase storage capacity", "value": { "max_bytes": 21474836480 } }, "full_update": { "summary": "Update multiple properties", "value": { "description": "Expanded media storage", "max_bytes": 53687091200 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Object Store" ], "summary": "Delete an object store bucket", "description": "Deletes an object store bucket and all its contents", "operationId": "deleteObjectStoreBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/obj/{bucket}/purge": { "delete": { "tags": [ "Object Store" ], "summary": "Purge object store bucket", "description": "Purges all data from an object store bucket while keeping the bucket configuration", "operationId": "purgeObjectStoreBucket", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/obj/{bucket}/entries": { "get": { "tags": [ "Object Store" ], "summary": "List object store entries", "description": "Retrieves entries from an object store bucket", "operationId": "getObjectStoreEntries", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "name": "limit", "in": "query", "description": "Maximum number of entries to retrieve", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Successfully retrieved entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectEntriesResponse" }, "examples": { "media_files": { "summary": "Media file entries", "value": { "body": { "results": [ { "key": "images/logo.png", "size": 24576 }, { "key": "images/banner.jpg", "size": 1048576 }, { "key": "videos/intro.mp4", "size": 52428800 }, { "key": "documents/readme.pdf", "size": 204800 } ], "results_total": 4 }, "metadata": { "bucket": "media-assets", "limit": 10, "duration": "15ms" } } }, "empty_bucket": { "summary": "Empty bucket", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "bucket": "new-bucket", "limit": 10, "duration": "2ms" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Delete several object store entries", "description": "Deletes the entries named by repeated key query parameters.", "operationId": "deleteObjectStoreEntries", "tags": [ "Object Store" ], "x-resource-type": "service", "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/obj/{bucket}/entries/{key}": { "delete": { "tags": [ "Object Store" ], "summary": "Delete an object store entry", "description": "Deletes a specific entry from an object store bucket", "operationId": "deleteObjectStoreEntry", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "$ref": "#/components/parameters/entryKey" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "Get an object store entry", "description": "Returns one object's content as base64, so binary files survive the JSON reply. Refused when the encoded object would exceed the reply limit.", "operationId": "getObjectStoreEntry", "tags": [ "Object Store" ], "x-resource-type": "service", "parameters": [ { "name": "bucket", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } }, "x-path-derived": true } }, "/storage/streams": { "get": { "tags": [ "Streams" ], "summary": "List all streams", "description": "Retrieves a list of all streams", "operationId": "getStreamList", "x-resource-type": "service", "responses": { "200": { "description": "Successfully retrieved stream list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamListResponse" }, "examples": { "multiple_streams": { "summary": "Multiple streams", "value": { "body": { "results": [ { "name": "user-events", "description": "User activity events", "subjects": [ "events.user.*" ], "metadata": {}, "created": "2024-01-15T10:30:00Z", "messages_total": 15420 }, { "name": "system-logs", "description": "System log aggregation", "subjects": [ "logs.system.*", "logs.app.*" ], "metadata": {}, "created": "2024-01-10T08:00:00Z", "messages_total": 892341 }, { "name": "order-processing", "description": "E-commerce order events", "subjects": [ "orders.*" ], "metadata": {}, "created": "2024-02-01T14:20:00Z", "messages_total": 5230 } ], "results_total": 3 }, "metadata": { "duration": "12ms" } } }, "empty_list": { "summary": "No streams configured", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "duration": "2ms" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Streams" ], "summary": "Create a new stream", "description": "Creates a new stream for message publishing", "operationId": "createStream", "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStreamRequest" }, "examples": { "basic_stream": { "summary": "Basic event stream", "value": { "name": "user-events", "description": "Stream for user activity events", "subjects": [ "events.user.*" ] } }, "full_configuration": { "summary": "Fully configured stream", "value": { "name": "order-processing", "description": "High-throughput order processing stream", "subjects": [ "orders.created", "orders.updated", "orders.completed", "orders.cancelled" ], "max_consumers": 10, "max_msgs": 5000000, "max_bytes": 536870912, "discard": 0, "max_msgs_per_subject": 100000, "max_msg_size": 65536, "storage": "file", "num_replicas": 3, "deny_delete": false, "deny_purge": false } }, "mirror_stream": { "summary": "Mirror stream from another source", "value": { "name": "orders-mirror", "description": "Mirror of order-processing stream", "mirror": { "name": "order-processing", "opt_start_seq": 1 }, "storage": "file", "num_replicas": 2 } }, "aggregated_stream": { "summary": "Stream aggregating multiple sources", "value": { "name": "all-events", "description": "Aggregated stream from multiple sources", "sources": [ { "name": "user-events", "filter_subject": "events.user.login" }, { "name": "order-processing", "filter_subject": "orders.completed" } ], "storage": "file", "num_replicas": 2 } }, "memory_stream": { "summary": "In-memory stream for real-time processing", "value": { "name": "realtime-notifications", "description": "Fast in-memory stream for notifications", "subjects": [ "notifications.*" ], "storage": "memory", "max_msgs": 10000, "max_bytes": 10485760, "num_replicas": 1 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/streams/{name}": { "get": { "tags": [ "Streams" ], "summary": "Get information about a stream", "description": "Retrieves detailed information about a specific stream, including its configuration and current state. This endpoint provides metrics such as the number of messages, bytes used, first and last sequence numbers, and more.", "operationId": "getStream", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" } ], "responses": { "200": { "description": "Successfully retrieved stream information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamResponse" }, "examples": { "active_stream": { "summary": "Active stream with messages", "value": { "body": { "config": { "name": "user-events", "description": "User activity events", "subjects": [ "events.user.*" ], "retention": "Limits", "max_consumers": -1, "max_msgs": 1000000, "max_bytes": 104857600, "max_age": 0, "max_msg_size": -1, "storage": "file", "discard": "old", "num_replicas": 3, "duplicate_window": 120000000000, "deny_delete": false, "deny_purge": false }, "state": { "messages": 15420, "bytes": 2458320, "first_seq": 1, "first_ts": "2024-01-15T10:30:00Z", "last_seq": 15420, "last_ts": "2024-03-15T14:22:33Z", "consumer_count": 3, "num_subjects": 12 }, "created": "2024-01-15T10:30:00Z", "cluster": { "name": "nats-cluster", "leader": "nats-1", "replicas": [ { "name": "nats-2", "current": true, "active": 0 }, { "name": "nats-3", "current": true, "active": 0 } ] } } } }, "empty_stream": { "summary": "Newly created empty stream", "value": { "body": { "config": { "name": "new-stream", "subjects": [ "new.*" ], "retention": "Limits", "storage": "file", "num_replicas": 1 }, "state": { "messages": 0, "bytes": 0, "first_seq": 0, "last_seq": 0, "consumer_count": 0, "num_subjects": 0 }, "created": "2024-03-15T14:00:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Streams" ], "summary": "Create or update a stream", "description": "Creates a new stream or updates an existing stream with the provided configuration. If the stream does not exist, it will be created. If it exists, it will be updated with the new configuration.\n\nNote that some properties cannot be changed after a stream is created, such as the storage type. If you attempt to change these properties, the request will fail with a 400 error.", "operationId": "createOrUpdateStream", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStreamRequest" }, "examples": { "update_description": { "summary": "Update stream description", "value": { "description": "Updated description for the user events stream" } }, "update_limits": { "summary": "Update stream limits", "value": { "max_msgs": 2000000, "max_bytes": 209715200, "max_msg_size": 131072 } }, "full_update": { "summary": "Full stream configuration update", "value": { "description": "High-capacity event stream", "max_msgs": 10000000, "max_bytes": 1073741824, "max_msg_size": 262144 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Streams" ], "summary": "Delete a stream", "description": "Deletes a stream with all the messages and consumers attached to it.", "operationId": "deleteStream", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/stream/{name}/purge": { "delete": { "tags": [ "Streams" ], "summary": "Purge stream messages", "description": "Purges messages from a stream with optional filters", "operationId": "purgeStream", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeStreamRequest" }, "examples": { "purge_all": { "summary": "Purge all messages", "value": {} }, "keep_recent": { "summary": "Keep the 100 most recent messages", "value": { "keep": 100 } }, "purge_by_sequence": { "summary": "Purge messages up to sequence 5000", "value": { "up_to_sequence": 5000 } }, "purge_by_subject": { "summary": "Purge messages for specific subject pattern", "value": { "subject": "events.user.deleted.*" } }, "combined_purge": { "summary": "Purge by subject keeping recent messages", "value": { "subject": "events.user.login", "keep": 50 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/streams/{name}/messages": { "post": { "tags": [ "Messages" ], "summary": "Publish message to stream", "description": "Publishes a message to a stream", "operationId": "publishMessage", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishMessageRequest" }, "examples": { "user_login_event": { "summary": "User login event", "value": { "stream": "user-events", "subject": "events.user.login", "body": { "user_id": "usr_abc123", "email": "user@example.com", "ip_address": "192.168.1.100", "user_agent": "Mozilla/5.0", "timestamp": "2024-03-15T14:30:00Z" } } }, "order_created_event": { "summary": "Order created event", "value": { "stream": "order-processing", "subject": "orders.created", "body": { "order_id": "ord_xyz789", "customer_id": "cust_456", "items": [ { "sku": "PROD-001", "quantity": 2, "price": 29.99 }, { "sku": "PROD-002", "quantity": 1, "price": 49.99 } ], "total": 109.97, "currency": "USD", "created_at": "2024-03-15T14:35:00Z" } } }, "system_metric": { "summary": "System metric event", "value": { "stream": "system-logs", "subject": "logs.system.metrics", "body": { "host": "api-server-01", "cpu_usage": 45.2, "memory_usage": 68.5, "disk_usage": 32.1, "active_connections": 1250, "timestamp": "2024-03-15T14:40:00Z" } } }, "notification_event": { "summary": "Notification event", "value": { "stream": "realtime-notifications", "subject": "notifications.email", "body": { "notification_id": "notif_001", "type": "email", "recipient": "user@example.com", "template": "welcome_email", "variables": { "name": "John Doe", "activation_link": "https://example.com/activate/abc123" } } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Messages" ], "summary": "Deletes stream messages", "description": "Deletes messages from a stream by sequence(seq).", "operationId": "deleteStreamMessages", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/streamName" }, { "name": "sequences", "in": "query", "description": "Comma-separated list of sequence numbers to delete", "required": true, "schema": { "type": "string" }, "examples": { "single": { "summary": "Delete single message", "value": "42" }, "multiple": { "summary": "Delete multiple messages", "value": "1,2,3,10,15" } } } ], "responses": { "200": { "$ref": "#/components/responses/SuccessResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/streams/{stream}/search-by-subject": { "get": { "tags": [ "Stream Search" ], "summary": "Search stream messages by subject pattern", "description": "Searches for stream messages by subject pattern", "operationId": "searchStreamBySubject", "x-resource-type": "service", "parameters": [ { "$ref": "#/components/parameters/stream" }, { "name": "search", "in": "query", "description": "Subject pattern to search for (supports wildcards)", "required": true, "schema": { "type": "string" }, "examples": { "exact": { "summary": "Exact subject match", "value": "events.user.login" }, "wildcard_single": { "summary": "Single-level wildcard", "value": "events.user.*" }, "wildcard_multi": { "summary": "Multi-level wildcard", "value": "events.>" } } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "examples": { "default": { "summary": "Default limit", "value": 10 }, "large": { "summary": "Large result set", "value": 100 } } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamSearchResponse" }, "examples": { "user_events": { "summary": "User event search results", "value": { "body": { "results": [ { "subject": "events.user.login", "value": "{\"user_id\":\"usr_abc123\",\"timestamp\":\"2024-03-15T14:30:00Z\"}", "created": "2024-03-15T14:30:00Z" }, { "subject": "events.user.logout", "value": "{\"user_id\":\"usr_abc123\",\"timestamp\":\"2024-03-15T16:45:00Z\"}", "created": "2024-03-15T16:45:00Z" }, { "subject": "events.user.profile_update", "value": "{\"user_id\":\"usr_def456\",\"field\":\"email\",\"timestamp\":\"2024-03-15T17:00:00Z\"}", "created": "2024-03-15T17:00:00Z" } ], "results_total": 3 }, "metadata": { "stream": "user-events", "search": "events.user.*", "hits": 3, "duration": "8ms" } } }, "no_results": { "summary": "No matching messages", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "stream": "user-events", "search": "events.admin.*", "hits": 0, "duration": "2ms" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/agent-sessions/{session_id}/files": { "get": { "summary": "List an assistant session's files", "description": "Lists the files kept for a chat session: work, outputs, uploads and scratch. Session access rules apply.", "operationId": "listAgentSessionFiles", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "post": { "summary": "Add a file to an assistant session", "description": "Stores a file under the session.", "operationId": "createAgentSessionFile", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/agent-sessions/{session_id}/files/{key}": { "get": { "summary": "Read a session file", "description": "Returns the live object, base64 encoded in body.data, with its content type. The reply carries the object's current digest in a header.", "operationId": "getAgentSessionFile", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } }, "put": { "summary": "Overwrite a session file", "description": "Overwrites a work or outputs file. Other kinds are refused.", "operationId": "putAgentSessionFile", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/agent-sessions/{session_id}/files/{key}/versions": { "get": { "summary": "List a session file's versions", "description": "Lists the live object first, then archived copies. Each entry's key is what the read endpoints take.", "operationId": "listAgentSessionFileVersions", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/agent-sessions/{session_id}/files/{key}/versions/{content_key}": { "get": { "summary": "Read an archived session file version", "description": "Returns one archived copy, base64 encoded. Only the content key is used server side.", "operationId": "getAgentSessionFileVersion", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "content_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/agent-sessions/{session_id}/tool-responses": { "get": { "summary": "List a session's stored tool responses", "description": "Lists tool responses kept for the session.", "operationId": "listAgentToolResponses", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/agent-sessions/{session_id}/tool-responses/{key}": { "get": { "summary": "Read a stored tool response", "description": "Returns one tool response, base64 encoded in body.data.", "operationId": "getAgentToolResponse", "tags": [ "Agent Sessions" ], "x-resource-type": "service", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/obj/sync": { "put": { "summary": "Sync an object store entry", "description": "Synchronises one object store entry through the data point service.", "operationId": "syncObjectEntry", "tags": [ "Object Store" ], "x-resource-type": "service", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } }, "/storage/index/{name}/query": { "post": { "summary": "Query a search index", "description": "Runs a query against the named index.", "operationId": "queryIndex", "tags": [ "Index" ], "x-resource-type": "service", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request refused or invalid" } } } } } }