{ "openapi": "3.0.3", "info": { "title": "quiva.ai Gateway", "description": "A comprehensive interface for managing key-value stores, object stores, streams, and search indexing", "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": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "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" } } }, "SearchResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchKVItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "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" } } }, "IndexSearchItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the result" }, "stream": { "type": "string" }, "subject": { "type": "string" }, "fields": { "type": "object", "description": "Indexed fields and their values", "additionalProperties": true }, "score": { "type": "number", "description": "Relevance score of the result" }, "partition": { "type": "integer" }, "sequence": { "type": "integer" }, "timestamp": { "type": "integer" } } }, "IndexSearchResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/IndexSearchItem" } }, "results_total": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "IndexerListItem": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "subjects": { "type": "array", "items": { "type": "string" } }, "index_config": { "type": "object", "properties": { "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/IndexMapping" } }, "engine": { "type": "string" }, "idBy": { "type": "string" }, "partitions": { "type": "integer" }, "version": { "type": "integer" } } } } }, "IndexerListResponse": { "type": "object", "properties": { "body": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/IndexerListItem" } }, "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", "x-resource": "microstrate.storage.get.kv-list", "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", "x-resource": "microstrate.storage.post.kv", "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", "x-resource": "microstrate.storage.get.kv", "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", "x-resource": "microstrate.storage.put.kv", "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", "x-resource": "microstrate.storage.delete.kv", "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", "x-resource": "microstrate.storage.delete.kv-purge", "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", "x-resource": "microstrate.storage.get.kv-entries", "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" } } } }, "/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", "x-resource": "microstrate.storage.get.kv-entry", "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", "x-resource": "microstrate.storage.put.kv-entry", "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", "x-resource": "microstrate.storage.delete.kv-entry", "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": { "get": { "tags": [ "KV Search" ], "summary": "Search KV entries", "description": "Searches for entries in a KV bucket based on indexed fields", "operationId": "searchKVEntries", "x-resource-type": "service", "x-resource": "microstrate.storage.get.search-kv", "parameters": [ { "$ref": "#/components/parameters/bucketName" }, { "name": "field", "in": "query", "description": "Field to search in", "required": true, "schema": { "type": "string" }, "example": "name" }, { "name": "search", "in": "query", "description": "Search term", "required": true, "schema": { "type": "string" }, "example": "keyboard" }, { "name": "search_type", "in": "query", "description": "Type of search to perform", "required": false, "schema": { "type": "string", "enum": [ "exact", "fuzzy", "prefix", "range" ] }, "example": "fuzzy" }, { "name": "min", "in": "query", "description": "Minimum value for range searches", "required": false, "schema": { "type": "number" }, "example": 50 }, { "name": "max", "in": "query", "description": "Maximum value for range searches", "required": false, "schema": { "type": "number" }, "example": 200 }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "example": 20 } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "body": { "results": [ { "key": "user123", "value": { "name": "John Doe", "age": 30 } } ], "results_total": 1 }, "metadata": { "bucket": "my-bucket", "field": "name", "search": "John", "index_duration": "3ms", "index_hits": 1 } } } } }, "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", "x-resource": "microstrate.storage.get.search-kv-by-key", "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", "x-resource": "microstrate.storage.get.obj-list", "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", "x-resource": "microstrate.storage.post.obj", "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", "x-resource": "microstrate.storage.get.obj", "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", "x-resource": "microstrate.storage.put.obj", "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", "x-resource": "microstrate.storage.delete.obj", "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", "x-resource": "microstrate.storage.delete.obj-purge", "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", "x-resource": "microstrate.storage.get.obj-entries", "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" } } } }, "/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", "x-resource": "microstrate.storage.delete.obj-entry", "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/streams": { "get": { "tags": [ "Streams" ], "summary": "List all streams", "description": "Retrieves a list of all streams", "operationId": "getStreamList", "x-resource-type": "service", "x-resource": "microstrate.storage.get.stream-list", "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", "x-resource": "microstrate.storage.post.stream", "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", "x-resource": "microstrate.storage.get.stream", "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", "x-resource": "microstrate.storage.put.stream", "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", "x-resource": "microstrate.storage.delete.stream", "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", "x-resource": "microstrate.storage.delete.stream-purge", "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", "x-resource": "microstrate.storage.post.message", "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", "x-resource": "microstrate.storage.delete.messages", "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", "x-resource": "microstrate.storage.get.search-stream-by-subject", "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/search/{index}": { "get": { "tags": [ "Search" ], "summary": "Search an index", "description": "Performs a search on an index", "operationId": "searchIndex", "x-resource-type": "service", "x-resource": "microstrate.storage.get.search-index", "parameters": [ { "name": "index", "in": "path", "description": "Name of the index to search", "required": true, "schema": { "type": "string" }, "examples": { "users": { "summary": "Users index", "value": "users-index" }, "products": { "summary": "Products index", "value": "products-index" } } }, { "name": "field", "in": "query", "description": "Field to search in", "required": true, "schema": { "type": "string" }, "examples": { "name": { "summary": "Search by name", "value": "name" }, "email": { "summary": "Search by email", "value": "email" }, "description": { "summary": "Search by description", "value": "description" } } }, { "name": "search", "in": "query", "description": "Search term", "required": true, "schema": { "type": "string" }, "examples": { "name_search": { "summary": "Search for name", "value": "John" }, "partial_search": { "summary": "Partial term search", "value": "acme" } } }, { "name": "search_type", "in": "query", "description": "Type of search to perform", "required": false, "schema": { "type": "string", "enum": [ "exact", "fuzzy", "prefix", "range" ] }, "examples": { "exact": { "summary": "Exact match", "value": "exact" }, "fuzzy": { "summary": "Fuzzy match (typo-tolerant)", "value": "fuzzy" }, "prefix": { "summary": "Prefix match", "value": "prefix" } } }, { "name": "min", "in": "query", "description": "Minimum value for range searches", "required": false, "schema": { "type": "number" }, "examples": { "age_min": { "summary": "Minimum age", "value": 18 }, "price_min": { "summary": "Minimum price", "value": 9.99 } } }, { "name": "max", "in": "query", "description": "Maximum value for range searches", "required": false, "schema": { "type": "number" }, "examples": { "age_max": { "summary": "Maximum age", "value": 65 }, "price_max": { "summary": "Maximum price", "value": 99.99 } } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "examples": { "small": { "summary": "Small result set", "value": 5 }, "medium": { "summary": "Medium result set", "value": 25 }, "large": { "summary": "Large result set", "value": 100 } } }, { "name": "sortBy", "in": "query", "description": "Field to sort results by", "required": false, "schema": { "type": "string" }, "examples": { "by_name": { "summary": "Sort by name", "value": "name" }, "by_date": { "summary": "Sort by date", "value": "created_at" }, "by_score": { "summary": "Sort by relevance score", "value": "_score" } } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexSearchResponse" }, "examples": { "user_search": { "summary": "User search results", "value": { "body": { "results": [ { "id": "usr_abc123", "stream": "user-events", "subject": "users.profiles", "fields": { "name": "John Doe", "email": "john.doe@example.com", "age": 32, "department": "Engineering" }, "score": 0.98, "partition": 0, "sequence": 1542, "timestamp": 1710512400 }, { "id": "usr_def456", "stream": "user-events", "subject": "users.profiles", "fields": { "name": "Johnny Smith", "email": "johnny.smith@example.com", "age": 28, "department": "Marketing" }, "score": 0.85, "partition": 1, "sequence": 2103, "timestamp": 1710598800 } ], "results_total": 2 }, "metadata": { "field": "name", "search": "John", "index_name": "users-index", "index_duration": "5ms", "index_hits": 2, "index_partitions": 4 } } }, "range_search": { "summary": "Range search results", "value": { "body": { "results": [ { "id": "prod_001", "fields": { "name": "Basic Widget", "price": 19.99, "category": "widgets" }, "score": 1.0, "partition": 0, "sequence": 501 }, { "id": "prod_002", "fields": { "name": "Premium Widget", "price": 49.99, "category": "widgets" }, "score": 1.0, "partition": 0, "sequence": 502 } ], "results_total": 2 }, "metadata": { "field": "price", "search": "range", "index_name": "products-index", "index_duration": "3ms", "index_hits": 2 } } }, "no_results": { "summary": "No matching results", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "field": "name", "search": "nonexistent", "index_name": "users-index", "index_duration": "1ms", "index_hits": 0 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/storage/indexers": { "get": { "tags": [ "Indexers" ], "summary": "List all indexers", "description": "Retrieves a list of all indexers", "operationId": "getIndexerList", "x-resource-type": "service", "x-resource": "microstrate.storage.get.indexer-list", "responses": { "200": { "description": "Successfully retrieved indexer list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexerListResponse" }, "examples": { "multiple_indexers": { "summary": "Multiple indexers configured", "value": { "body": { "results": [ { "name": "users-index", "description": "Full-text search index for user profiles", "subjects": [ "users.profiles.*" ], "index_config": { "mappings": [ { "field": "name", "field_type": "text" }, { "field": "email", "field_type": "keyword" }, { "field": "age", "field_type": "number" }, { "field": "created_at", "field_type": "date" }, { "field": "active", "field_type": "boolean" } ], "engine": "bleve", "idBy": "user_id", "partitions": 4, "version": 1 } }, { "name": "products-index", "description": "Product catalog search index", "subjects": [ "products.*" ], "index_config": { "mappings": [ { "field": "name", "field_type": "text" }, { "field": "description", "field_type": "text" }, { "field": "price", "field_type": "number" }, { "field": "category", "field_type": "keyword" }, { "field": "in_stock", "field_type": "boolean" } ], "engine": "bleve", "idBy": "product_id", "partitions": 2, "version": 1 } }, { "name": "logs-index", "description": "System logs search index", "subjects": [ "logs.system.*", "logs.app.*" ], "index_config": { "mappings": [ { "field": "message", "field_type": "text" }, { "field": "level", "field_type": "keyword" }, { "field": "service", "field_type": "keyword" }, { "field": "timestamp", "field_type": "date" } ], "engine": "bleve", "idBy": "log_id", "partitions": 8, "version": 2 } } ], "results_total": 3 }, "metadata": { "duration": "15ms" } } }, "single_indexer": { "summary": "Single indexer configured", "value": { "body": { "results": [ { "name": "default-index", "description": "Default search index", "subjects": [ "data.*" ], "index_config": { "mappings": [ { "field": "content", "field_type": "text" }, { "field": "tags", "field_type": "keyword" } ], "engine": "bleve", "idBy": "id", "partitions": 1, "version": 1 } } ], "results_total": 1 }, "metadata": { "duration": "5ms" } } }, "empty_list": { "summary": "No indexers configured", "value": { "body": { "results": [], "results_total": 0 }, "metadata": { "duration": "2ms" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } } }