{ "openapi": "3.1.0", "info": { "title": "SerenAI API", "description": "SerenAI API - Database management, agent commerce, and AI-powered data access", "contact": { "name": "SerenAI", "email": "hello@serendb.com" }, "license": { "name": "UNLICENSED", "identifier": "UNLICENSED" }, "version": "0.1.0" }, "servers": [ { "url": "/", "description": "API Root" } ], "paths": { "/auth/accept-invite": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/accept-invite\nAccept an organization invite for the authenticated user.", "operationId": "accept_organization_invite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptOrganizationInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization invite accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AcceptOrganizationInviteResult" } } } }, "400": { "description": "Invalid or expired invite" }, "401": { "description": "Unauthorized" }, "404": { "description": "Invite not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/account-security": { "get": { "tags": [ "Auth" ], "summary": "GET /auth/account-security\nReturn account-level auth state (password presence and linked social providers).", "operationId": "get_account_security", "responses": { "200": { "description": "Account security state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AccountSecurity" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/agent": { "post": { "tags": [ "agent" ], "summary": "POST /auth/agent\nRegister a new AI agent account.", "description": "This endpoint allows AI agents to self-register using the user's real email\naddress and receive an API key immediately. Registration:\n- Requires a user-controlled email address up front\n- Automatically creates a personal organization\n- Returns an API key named \"agent\" for immediate use\n- Sends an email verification link immediately after signup\n\n**Important:** Save the `api_key` immediately - it is only shown once!", "operationId": "agent_register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegisterRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentRegisterResponse" } } } }, "400": { "description": "Invalid request (validation error)" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "agent" ], "summary": "Update an agent's profile (e.g. set a real email address).", "description": "When the email is changed, `email_verified` is set to `false` and a\nverification email with a clickable link is sent. The user verifies\nby clicking the link — no separate API call is needed.\nA verified email is required before making Stripe deposits.", "operationId": "agent_update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent updated" }, "400": { "description": "Invalid email" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/change-password": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/change-password\nChange the authenticated user's password and revoke active refresh sessions", "operationId": "change_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Password updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PasswordUpdated" } } } }, "400": { "description": "Invalid current password or weak new password" }, "401": { "description": "Unauthorized" }, "403": { "description": "Password login is not enabled for this account" }, "404": { "description": "User not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/forgot-password\nRequest a password reset email", "operationId": "forgot_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Password reset email sent if account exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PasswordResetSent" } } } }, "400": { "description": "Invalid request" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/login\nLogin with email and password.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LoginResult" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Email verification required" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/logout\nRevoke all sessions for current user.", "operationId": "logout", "responses": { "200": { "description": "Sessions revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LogoutResult" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "GET /auth/me\nGet current authenticated user information with default organization", "operationId": "get_current_user", "responses": { "200": { "description": "Current user information with default organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UserMe" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/refresh\nExchange refresh token for new access token and refresh token (rotation).", "operationId": "refresh_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Tokens rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_TokenRefresh" } } } }, "401": { "description": "Missing, invalid, expired, or reused refresh token" } } } }, "/auth/resend-verification": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/resend-verification\nResend email verification link", "operationId": "resend_verification_email", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationRequest" } } }, "required": true }, "responses": { "200": { "description": "Verification email sent if account exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_VerificationSent" } } } }, "400": { "description": "Invalid request" } } } }, "/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/reset-password\nReset password using a valid token", "operationId": "reset_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PasswordReset" } } } }, "400": { "description": "Invalid or expired token" }, "404": { "description": "Token not found" } } } }, "/auth/signup": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/signup\nRegister a new user with email and password", "operationId": "signup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } }, "required": true }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SignupResult" } } } }, "400": { "description": "Invalid request or weak password" }, "409": { "description": "Email already registered" } } } }, "/auth/verify-email": { "post": { "tags": [ "Auth" ], "summary": "POST /auth/verify-email\nVerify email address using a token from the verification email link.\nCalled by an application frontend when the user clicks the link; agents\ndo not need to call this directly.\nOn success, automatically logs the user in and returns tokens", "operationId": "verify_email", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Email verified and user logged in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LoginResult" } } } }, "400": { "description": "Invalid or expired token" } } } }, "/billing/health": { "get": { "tags": [ "billing" ], "summary": "GET /billing/health\nHigh-level billing and metering health summary for Seren Core", "operationId": "get_billing_health", "responses": { "200": { "description": "Billing health retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BillingHealth" } } } }, "500": { "description": "Internal server error" } } } }, "/billing/invoices/generate": { "post": { "tags": [ "billing" ], "summary": "POST /billing/invoices/generate\nGenerate monthly invoices for all organizations", "operationId": "generate_invoices", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateInvoicesRequest" } } }, "required": true }, "responses": { "200": { "description": "Invoices generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_InvoicesGenerated" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal server error" } } } }, "/billing/invoices/{id}": { "get": { "tags": [ "billing" ], "summary": "GET /billing/invoices/:id\nGet invoice details with line items", "operationId": "get_invoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Invoice" } } } }, "404": { "description": "Invoice not found" }, "500": { "description": "Internal server error" } } } }, "/billing/invoices/{id}/issue": { "post": { "tags": [ "billing" ], "summary": "POST /billing/invoices/:id/issue\nIssue a draft invoice", "operationId": "issue_invoice", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice issued successfully" }, "404": { "description": "Invoice not found" }, "500": { "description": "Internal server error" } } } }, "/billing/invoices/{id}/pay": { "post": { "tags": [ "payments" ], "summary": "POST /billing/invoices/:id/pay\nCreate a payment intent for an invoice", "operationId": "create_payment_intent", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PaymentIntentCreated" } } } }, "400": { "description": "Invoice not in payable state" }, "404": { "description": "Invoice not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/invoices/{id}/payments": { "get": { "tags": [ "payments" ], "summary": "GET /billing/invoices/:id/payments\nGet payment history for an invoice", "operationId": "get_payment_history", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment history retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PaymentHistory" } } } }, "404": { "description": "Invoice not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/payment-methods": { "get": { "tags": [ "payments" ], "summary": "GET /billing/payment-methods\nList payment methods for the organization", "operationId": "list_payment_methods", "responses": { "200": { "description": "Payment methods retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_PaymentMethod" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "payments" ], "summary": "POST /billing/payment-methods\nAdd a payment method for the organization", "operationId": "add_payment_method", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPaymentMethodRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment method added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PaymentMethodAdded" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/payment-methods/{id}": { "delete": { "tags": [ "payments" ], "summary": "DELETE /billing/payment-methods/{id}\nRemove a payment method from the organization", "operationId": "delete_payment_method", "parameters": [ { "name": "id", "in": "path", "description": "Payment method ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Payment method removed" }, "404": { "description": "Payment method not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/charges": { "post": { "tags": [ "publisher-payments" ], "summary": "POST /billing/publishers/{slug}/charges", "operationId": "create_charge", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChargeRequest" } } }, "required": true }, "responses": { "200": { "description": "Charge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherChargeInfo" } } } }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient balance" }, "403": { "description": "Forbidden" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/charges/{charge_id}": { "get": { "tags": [ "publisher-payments" ], "summary": "GET /billing/publishers/{slug}/charges/{charge_id}", "operationId": "get_charge_status", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } }, { "name": "charge_id", "in": "path", "description": "Charge ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Charge retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherChargeInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Charge not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/charges/{charge_id}/refund": { "post": { "tags": [ "publisher-payments" ], "summary": "POST /billing/publishers/{slug}/charges/{charge_id}/refund", "operationId": "refund_charge", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } }, { "name": "charge_id", "in": "path", "description": "Charge ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundChargeRequest" } } }, "required": true }, "responses": { "200": { "description": "Charge refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherChargeInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Charge not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/charges/{charge_id}/slash": { "post": { "tags": [ "publisher-payments" ], "summary": "POST /billing/publishers/{slug}/charges/{charge_id}/slash", "operationId": "slash_charge", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } }, { "name": "charge_id", "in": "path", "description": "Original charge ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlashChargeRequest" } } }, "required": true }, "responses": { "204": { "description": "Slash applied" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient balance" }, "403": { "description": "Forbidden" }, "404": { "description": "Charge not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/payouts": { "post": { "tags": [ "publisher-payments" ], "summary": "POST /billing/publishers/{slug}/payouts", "operationId": "create_payout", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Payout created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherPayoutInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/publishers/{slug}/payouts/{payout_id}": { "get": { "tags": [ "publisher-payments" ], "summary": "GET /billing/publishers/{slug}/payouts/{payout_id}", "operationId": "get_payout_status", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } }, { "name": "payout_id", "in": "path", "description": "Payout ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payout retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherPayoutInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Payout not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/billing/usage/{organization_id}": { "get": { "tags": [ "billing" ], "summary": "GET /billing/usage/:organization_id\nGet usage summary for an organization", "operationId": "get_usage_summary", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Usage summary retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_UsageSummary" } } } }, "404": { "description": "Organization not found" }, "500": { "description": "Internal server error" } } } }, "/databases": { "get": { "tags": [ "Databases" ], "summary": "List all databases across all projects for the authenticated user", "description": "Returns all databases the user has access to, with project and branch context included.\nThis provides a single view of all databases without needing to query each project/branch separately.", "operationId": "list_all_databases", "responses": { "200": { "description": "List of all databases with context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_DatabaseWithContext" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/eval/community-prior": { "get": { "tags": [ "Eval" ], "summary": "Get an aggregate community routing prior for a task/model pair.", "operationId": "get_community_prior", "parameters": [ { "name": "task_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/TaskType" } }, { "name": "model_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Community routing prior", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CommunityPriorResponse" } } } }, "400": { "description": "Invalid query parameters" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/eval/matrix": { "get": { "tags": [ "Eval" ], "summary": "Get the global eval routing matrix.", "operationId": "get_matrix", "responses": { "200": { "description": "Eval matrix", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_EvalMatrixResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/eval/signals": { "post": { "tags": [ "Eval" ], "summary": "Ingest eval signals from Seren Desktop clients.", "operationId": "post_signals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalSignalRequest" } } }, "required": true }, "responses": { "201": { "description": "Signals accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_EvalSignalResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/federation": { "get": { "tags": [ "federation" ], "summary": "GET /federation\nList federated resources with optional filtering.\nUsed for cross-publisher resource discovery.", "operationId": "list_resources", "parameters": [ { "name": "publisher_slug", "in": "query", "description": "Filter by publisher slug", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_type", "in": "query", "description": "Filter by resource type (e.g., \"bounty\", \"dataset\")", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "description": "Filter by status (default: \"active\")", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Resources retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_FederatedResourceWithPublisherResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "federation" ], "summary": "POST /federation\nUpsert a federated resource for a publisher.\nPublishers use this to register/update their resources for cross-publisher discovery.", "operationId": "upsert_resource", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertFederatedResourceRequest" } } }, "required": true }, "responses": { "200": { "description": "Resource upserted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FederatedResourceResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized - must be a publisher" }, "500": { "description": "Internal server error" } } } }, "/federation/history": { "get": { "tags": [ "federation" ], "summary": "GET /federation/history\nList append-only federation history events.", "operationId": "list_history", "parameters": [ { "name": "publisher_slug", "in": "query", "description": "Filter by publisher slug", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_type", "in": "query", "description": "Filter by resource type", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "external_id", "in": "query", "description": "Filter by external resource ID", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "operation", "in": "query", "description": "Filter by history operation: insert, update, delete", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "History retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_FederatedResourceHistoryResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } } } }, "/federation/history/stats": { "get": { "tags": [ "federation" ], "summary": "GET /federation/history/stats\nGet aggregate statistics over federation history.", "operationId": "get_history_stats", "parameters": [ { "name": "publisher_slug", "in": "query", "description": "Filter by publisher slug (optional)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_type", "in": "query", "description": "Filter by resource type (optional)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "History stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FederationHistoryStatsResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/federation/stats": { "get": { "tags": [ "federation" ], "summary": "GET /federation/stats\nGet federation statistics, optionally filtered by publisher.", "operationId": "get_stats", "parameters": [ { "name": "publisher_slug", "in": "query", "description": "Filter by publisher slug (optional - if omitted, returns stats across all publishers)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Stats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FederationStatsResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/federation/{id}": { "get": { "tags": [ "federation" ], "summary": "GET /federation/{id}\nGet a specific federated resource by ID.", "operationId": "get_resource", "parameters": [ { "name": "id", "in": "path", "description": "Federated resource ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resource retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FederatedResourceResponse" } } } }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/federation/{resource_type}/{external_id}": { "delete": { "tags": [ "federation" ], "summary": "DELETE /federation/{resource_type}/{external_id}\nDelete a federated resource by type and external ID.\nOnly the owning publisher can delete their resources.", "operationId": "delete_resource", "parameters": [ { "name": "resource_type", "in": "path", "description": "Resource type", "required": true, "schema": { "type": "string" } }, { "name": "external_id", "in": "path", "description": "External resource ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted successfully" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized to delete this resource" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/notifications/{notification_id}/read": { "post": { "tags": [ "notifications" ], "operationId": "mark_notification_read", "parameters": [ { "name": "notification_id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Notification marked read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NotificationReadResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Notification not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/connections": { "get": { "tags": [ "OAuth" ], "summary": "List user's OAuth connections", "description": "Returns all OAuth providers the user has connected to.", "operationId": "list_connections", "responses": { "200": { "description": "List of user's OAuth connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/connections/{connection_id}": { "delete": { "tags": [ "OAuth" ], "summary": "Revoke an OAuth connection by connection ID.", "operationId": "revoke_connection_by_id", "parameters": [ { "name": "connection_id", "in": "path", "description": "OAuth connection UUID to disconnect", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeResponse" } } } }, "404": { "description": "Connection not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/connections/{connection_id}/default": { "put": { "tags": [ "OAuth" ], "summary": "Set the default OAuth connection", "description": "Marks one of the authenticated user's OAuth connections as the default for its provider.", "operationId": "set_default_connection", "parameters": [ { "name": "connection_id", "in": "path", "description": "OAuth connection UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Default connection updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultConnectionResponse" } } } }, "404": { "description": "Connection not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/providers": { "get": { "tags": [ "OAuth" ], "summary": "List available OAuth providers", "description": "Returns all active OAuth providers that users can connect to,\nincluding global providers and providers from organizations the user belongs to.", "operationId": "list_providers", "responses": { "200": { "description": "List of available OAuth providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/providers/{provider_id}/authorize": { "get": { "tags": [ "OAuth" ], "summary": "Initiate OAuth authorization flow by provider ID (supports org-scoped providers)", "operationId": "initiate_oauth_by_id", "parameters": [ { "name": "provider_id", "in": "path", "description": "OAuth provider UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "redirect_uri", "in": "query", "description": "Where to redirect after OAuth completes", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to OAuth provider" }, "400": { "description": "Invalid or missing redirect URI" }, "404": { "description": "Provider not found" }, "503": { "description": "OAuth account access is unavailable" } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/providers/{provider_id}/callback": { "get": { "tags": [ "OAuth" ], "summary": "Handle OAuth callback by provider ID (supports org-scoped providers)", "operationId": "oauth_callback_by_id", "parameters": [ { "name": "provider_id", "in": "path", "description": "OAuth provider UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "code", "in": "query", "description": "Authorization code from provider", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "State parameter for CSRF verification", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to frontend with success/error" }, "400": { "description": "Invalid callback parameters" }, "404": { "description": "Provider not found" } } } }, "/oauth/{provider}/authorize": { "get": { "tags": [ "OAuth" ], "summary": "Initiate OAuth authorization flow", "description": "Redirects the user to the OAuth provider's consent screen.\nAfter authorization, the provider will redirect back to the callback URL.", "operationId": "initiate_oauth", "parameters": [ { "name": "provider", "in": "path", "description": "OAuth provider slug (e.g., 'neon')", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "description": "Where to redirect after OAuth completes", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to OAuth provider" }, "400": { "description": "Invalid or missing redirect URI" }, "404": { "description": "Provider not found" }, "503": { "description": "OAuth account access is unavailable" } }, "security": [ { "bearer_auth": [] } ] } }, "/oauth/{provider}/callback": { "get": { "tags": [ "OAuth" ], "summary": "Handle OAuth callback", "description": "Called by the OAuth provider after the user authorizes.\nExchanges the authorization code for tokens and stores them.", "operationId": "oauth_callback", "parameters": [ { "name": "provider", "in": "path", "description": "OAuth provider slug", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Authorization code from provider", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "State parameter for CSRF verification", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to frontend with success/error" }, "400": { "description": "Invalid callback parameters" } } } }, "/organizations": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations\nList all organizations for the authenticated user", "operationId": "list_organizations", "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Organization" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/default/api-keys": { "get": { "tags": [ "Auth" ], "summary": "List API keys for the user's default organization", "description": "Requires a signed-in user access token. API keys cannot manage API keys.", "operationId": "list_default_org_api_keys", "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_ApiKeyInfo" } } } }, "400": { "description": "User has no organization" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Create a new API key for the user's default organization", "description": "This convenience endpoint resolves \"default\" to the user's first organization. It requires a signed-in user access token; API keys cannot manage API keys.", "operationId": "create_default_org_api_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiKeyCreated" } } } }, "400": { "description": "User has no organization" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/default/api-keys/{key_id}": { "delete": { "tags": [ "Auth" ], "summary": "Revoke an API key from the user's default organization", "description": "Requires a signed-in user access token. API keys cannot manage API keys.", "operationId": "revoke_default_org_api_key", "parameters": [ { "name": "key_id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API key revoked" }, "400": { "description": "User has no organization" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "API key not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/default/api-keys/{key_id}/scopes": { "patch": { "tags": [ "Auth" ], "summary": "Replace scopes on an API key in the user's default organization.", "description": "Requires a signed-in user access token. API keys cannot update their own privileges.", "operationId": "update_default_org_api_key_scopes", "parameters": [ { "name": "key_id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyScopesRequest" } } }, "required": true }, "responses": { "200": { "description": "API key scopes replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiKeyInfo" } } } }, "400": { "description": "Invalid scope set" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "API key not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/agent-credential-secrets": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/agent-credential-secrets", "operationId": "list_agent_credential_secrets", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCredentialSecretScope" } ] } } ], "responses": { "200": { "description": "Managed-agent credential secrets retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AgentCredentialSecret" } } } }, "403": { "description": "Only organization owners or admins can list credential secrets" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/agent-credential-secrets", "operationId": "upsert_agent_credential_secret", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAgentCredentialSecretRequest" } } }, "required": true }, "responses": { "200": { "description": "Managed-agent credential secret upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCredentialSecret" } } } }, "400": { "description": "Invalid secret name or value" }, "403": { "description": "Only organization owners or admins can manage credential secrets" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/agent-credential-secrets/{secret_id}": { "delete": { "tags": [ "Organizations" ], "summary": "DELETE /organizations/{organization_id}/agent-credential-secrets/{secret_id}", "operationId": "delete_agent_credential_secret", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "secret_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed-agent credential secret deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCredentialSecretDeleted" } } } }, "403": { "description": "Only organization owners or admins can manage credential secrets" }, "404": { "description": "Credential secret not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/agents/tasks": { "get": { "tags": [ "Agent Tasks" ], "summary": "GET /organizations/{organization_id}/agents/tasks", "operationId": "list_tasks", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Tasks retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AgentTask" } } } }, "403": { "description": "Not authorized" } } } }, "/organizations/{organization_id}/agents/tasks/{task_id}": { "get": { "tags": [ "Agent Tasks" ], "summary": "GET /organizations/{organization_id}/agents/tasks/{task_id}", "operationId": "get_task", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentTask" } } } }, "404": { "description": "Task not found" } } } }, "/organizations/{organization_id}/agents/tasks/{task_id}/cancel": { "post": { "tags": [ "Agent Tasks" ], "summary": "POST /organizations/{organization_id}/agents/tasks/{task_id}/cancel", "operationId": "cancel_task", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentTask" } } } }, "400": { "description": "Already terminal" }, "404": { "description": "Not found" } } } }, "/organizations/{organization_id}/agents/tasks/{task_id}/events": { "get": { "tags": [ "Agent Tasks" ], "summary": "GET /organizations/{organization_id}/agents/tasks/{task_id}/events", "operationId": "list_task_events", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Events retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AgentTaskEvent" } } } }, "404": { "description": "Not found" } } } }, "/organizations/{organization_id}/agents/tasks/{task_id}/resume": { "post": { "tags": [ "Agent Tasks" ], "summary": "POST /organizations/{organization_id}/agents/tasks/{task_id}/resume", "operationId": "submit_task_input", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitTaskInputRequest" } } }, "required": true }, "responses": { "202": { "description": "Task input accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentTask" } } } }, "400": { "description": "Task is not awaiting input or cannot be resumed" }, "403": { "description": "Not authorized" }, "404": { "description": "Task not found" } } } }, "/organizations/{organization_id}/agents/tasks/{task_id}/stream": { "get": { "tags": [ "Agent Tasks" ], "summary": "GET /organizations/{organization_id}/agents/tasks/{task_id}/stream", "operationId": "stream_task", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SSE event stream" } } } }, "/organizations/{organization_id}/api-keys": { "get": { "tags": [ "Auth" ], "summary": "List API keys for a specific organization", "description": "Requires a signed-in user access token. API keys cannot manage API keys.", "operationId": "list_org_api_keys", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_ApiKeyInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Create a new API key for a specific organization", "description": "Requires a signed-in user access token. API keys cannot manage API keys.", "operationId": "create_org_api_key", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiKeyCreated" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/api-keys/{key_id}": { "delete": { "tags": [ "Auth" ], "summary": "Revoke an organization API key", "description": "Requires a signed-in user access token. API keys cannot manage API keys.", "operationId": "revoke_org_api_key", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API key revoked" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "API key not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/api-keys/{key_id}/scopes": { "patch": { "tags": [ "Auth" ], "summary": "Replace the least-privilege scopes on an organization API key.", "description": "Requires a signed-in user access token. A user may update only their own\nactive user API keys; API keys cannot update their own privileges.", "operationId": "update_org_api_key_scopes", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyScopesRequest" } } }, "required": true }, "responses": { "200": { "description": "API key scopes replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiKeyInfo" } } } }, "400": { "description": "Invalid scope set" }, "401": { "description": "Unauthorized" }, "403": { "description": "A signed-in user session is required" }, "404": { "description": "API key not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/audit-logs": { "get": { "tags": [ "Audit Logs" ], "summary": "List audit logs for an organization", "operationId": "list_audit_logs", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "actor_id", "in": "query", "description": "Filter by actor ID", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "action", "in": "query", "description": "Filter by action (e.g., \"project.create\")", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_type", "in": "query", "description": "Filter by resource type (e.g., \"project\", \"branch\")", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_id", "in": "query", "description": "Filter by resource ID", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "action_category", "in": "query", "description": "Filter by action category", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "start_date", "in": "query", "description": "Filter by start date (ISO 8601)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "description": "Filter by end date (ISO 8601)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default 50, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Audit logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AuditLogList" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/audit-logs/{log_id}": { "get": { "tags": [ "Audit Logs" ], "summary": "Get a specific audit log entry", "operationId": "get_audit_log", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "log_id", "in": "path", "description": "Audit log ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit log retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AuditLog" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Audit log not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/billing/endpoints/{endpoint_id}/events": { "get": { "tags": [ "billing" ], "summary": "GET /organizations/{organization_id}/billing/endpoints/{endpoint_id}/events\nDebug endpoint: show recent usage_events and compute_usage_events for an endpoint", "operationId": "get_endpoint_billing_events", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Billing events retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_EndpointBillingEvents" } } } }, "404": { "description": "Endpoint not found for organization" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/catalog": { "get": { "tags": [ "Agent Catalog" ], "summary": "List catalog entries for an organization.", "operationId": "list_catalog_entries", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace", "in": "query", "description": "Filter by namespace", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by entry kind", "required": false, "schema": { "$ref": "#/components/schemas/AgentCatalogEntryKind" } }, { "name": "name", "in": "query", "description": "Filter by entry name", "required": false, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "Filter by mutable tag pointer", "required": false, "schema": { "type": "string" } }, { "name": "include_deprecated", "in": "query", "description": "Include deprecated entries", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Catalog entries for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogListResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Agent Catalog" ], "summary": "Create a new catalog entry.", "operationId": "create_catalog_entry", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalogEntryCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Catalog entry created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogEntry" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Entry with the same identity already exists" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/catalog/{entry_id}": { "get": { "tags": [ "Agent Catalog" ], "summary": "Fetch a single catalog entry by its UUID.", "operationId": "get_catalog_entry", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entry_id", "in": "path", "description": "Catalog entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Catalog entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogEntry" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Catalog entry not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Agent Catalog" ], "summary": "Delete a catalog entry.", "operationId": "delete_catalog_entry", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entry_id", "in": "path", "description": "Catalog entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Catalog entry deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Catalog entry not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Agent Catalog" ], "summary": "Apply a partial update to a catalog entry. Identity (namespace/name/version)\nis immutable; only mutable fields change.", "operationId": "update_catalog_entry", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entry_id", "in": "path", "description": "Catalog entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalogEntryUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Catalog entry updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogEntry" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Catalog entry not found" }, "409": { "description": "Tag pointer collision" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/catalog/{namespace}/{name}/by-tag/{tag}": { "get": { "tags": [ "Agent Catalog" ], "summary": "Resolve a mutable tag pointer to the concrete catalog entry it points at.\nTags like `stable` or `latest` are mutable; this endpoint returns whichever\nversion the tag currently names. Returns 404 when no entry within\n`(namespace, name)` carries the tag.", "operationId": "resolve_catalog_tag", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace", "in": "path", "description": "Catalog namespace", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Catalog entry name", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "path", "description": "Mutable tag pointer to resolve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog entry the tag points at", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogEntry" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "No entry carries the named tag" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/catalog/{namespace}/{name}/promote": { "post": { "tags": [ "Agent Catalog" ], "summary": "Atomically promote a mutable tag pointer from one immutable version\nto another within `(namespace, name)`. Distinct from a generic PATCH so\nthe action surfaces as a promotion in audit history rather than a\ngeneric edit.", "operationId": "promote_catalog_tag", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace", "in": "path", "description": "Catalog namespace", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Catalog entry name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalogTagPromotionRequest" } } }, "required": true }, "responses": { "200": { "description": "Tag promoted; response is the post-promotion entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCatalogEntry" } } } }, "400": { "description": "Invalid request (from_version == to_version, malformed tokens)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Destination version not found" }, "409": { "description": "from_version no longer holds the tag; refresh and retry" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/consumption": { "get": { "tags": [ "billing" ], "summary": "GET /organizations/{organization_id}/consumption\nAggregated organization-level consumption over a billing window.", "operationId": "get_organization_consumption", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Optional ISO-8601 start date (YYYY-MM-DD), defaults to first day of current month.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "description": "Optional ISO-8601 end date (YYYY-MM-DD), defaults to today (UTC).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Organization consumption retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationConsumption" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills", "operationId": "list_custom_skills", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Custom skills retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationCustomSkill" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/custom-skills", "operationId": "create_custom_skill", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationCustomSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Custom skill created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkill" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills/{skill_id}", "operationId": "get_custom_skill", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Custom skill retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkill" } } } }, "404": { "description": "Custom skill not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "PATCH /organizations/{organization_id}/custom-skills/{skill_id}", "operationId": "update_custom_skill", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationCustomSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Custom skill updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkill" } } } }, "404": { "description": "Custom skill not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}/revisions": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions", "operationId": "list_custom_skill_revisions", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Custom skill revisions retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationCustomSkillRevisionSummary" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/custom-skills/{skill_id}/revisions", "operationId": "create_custom_skill_revision", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationCustomSkillRevisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Custom skill revision created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkillRevision" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}", "operationId": "get_custom_skill_revision", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision_id", "in": "path", "description": "Revision ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Custom skill revision retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkillRevision" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/bundle": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/bundle", "operationId": "download_custom_skill_revision_bundle", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision_id", "in": "path", "description": "Revision ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revision bundle download", "content": { "application/gzip": {} } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/file": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/file?path=...", "operationId": "get_custom_skill_revision_file", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision_id", "in": "path", "description": "Revision ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revision file retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkillFileContent" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/publish": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/publish", "operationId": "publish_custom_skill_revision", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skill_id", "in": "path", "description": "Custom skill ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision_id", "in": "path", "description": "Revision ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revision published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationCustomSkill" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/employee-collaboration-policy": { "get": { "tags": [ "Organizations" ], "operationId": "get_employee_collaboration_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization employee collaboration policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationEmployeeCollaborationPolicy" } } } }, "403": { "description": "User is not a member of the organization" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Organizations" ], "operationId": "update_employee_collaboration_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationEmployeeCollaborationPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated organization employee collaboration policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationEmployeeCollaborationPolicy" } } } }, "400": { "description": "Invalid policy or no current employee assignment" }, "403": { "description": "Only a signed-in organization owner or administrator can update the policy" }, "409": { "description": "Policy revision is stale" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/employee-collaboration/assignments": { "get": { "tags": [ "Organizations" ], "operationId": "list_employee_collaboration_assignments", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Managed agent collaboration assignments, optionally including revoked assignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationEmployeeCollaborationAssignment" } } } }, "403": { "description": "Only a signed-in organization owner or administrator can list assignments" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/employee-collaboration/assignments/{deployment_id}": { "put": { "tags": [ "Organizations" ], "operationId": "upsert_employee_collaboration_assignment", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deployment_id", "in": "path", "description": "Managed agent deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrganizationEmployeeCollaborationAssignmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Created or updated employee collaboration assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationEmployeeCollaborationAssignment" } } } }, "400": { "description": "Deployment is not a managed agent with a stable agent identity" }, "403": { "description": "Only a signed-in organization owner or administrator can manage assignments" }, "409": { "description": "Assignment generation is stale or the assignment requires explicit reactivation" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Organizations" ], "operationId": "revoke_employee_collaboration_assignment", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deployment_id", "in": "path", "description": "Managed agent deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_assignment_generation", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Whether an active assignment was revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_bool" } } } }, "400": { "description": "Expected assignment generation is invalid" }, "403": { "description": "Only a signed-in organization owner or administrator can manage assignments" }, "409": { "description": "Assignment generation is stale" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/employee-collaboration/assignments/{deployment_id}/reactivate": { "post": { "tags": [ "Organizations" ], "operationId": "reactivate_employee_collaboration_assignment", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deployment_id", "in": "path", "description": "Managed agent deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrganizationEmployeeCollaborationAssignmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Reactivated employee collaboration assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationEmployeeCollaborationAssignment" } } } }, "400": { "description": "Expected assignment generation is missing or invalid" }, "403": { "description": "Only a signed-in organization owner or administrator can manage assignments" }, "409": { "description": "Assignment is active or its generation is stale" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/invites": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/invites\nList pending and historical organization invites.", "operationId": "list_invites", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization invites retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationInvite" } } } }, "403": { "description": "User is not allowed to view invites" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/invites\nCreate a new organization invite and send an email via the configured mailer.", "operationId": "create_invite", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInviteRequest" } } }, "required": true }, "responses": { "201": { "description": "Invite created and email sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationInvite" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "User is not allowed to create invites" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/members": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/members\nList organization members with basic user details.", "operationId": "list_members", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization members retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationMemberWithUser" } } } }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/members/{member_id}/role": { "put": { "tags": [ "RBAC" ], "summary": "Assign a role to an organization member", "operationId": "assign_role", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "member_id", "in": "path", "description": "Member user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role assigned successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires org.manage_members permission" }, "404": { "description": "Member or role not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/memory-capture-policy": { "get": { "tags": [ "Organizations" ], "operationId": "get_memory_capture_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization automatic memory-capture policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationMemoryCapturePolicy" } } } }, "403": { "description": "User is not a member of the organization" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Organizations" ], "operationId": "update_memory_capture_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for the authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationMemoryCapturePolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated organization automatic memory-capture policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationMemoryCapturePolicy" } } } }, "400": { "description": "Invalid policy" }, "403": { "description": "User is not allowed to update the organization" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/oauth/providers": { "get": { "tags": [ "oauth-providers" ], "summary": "GET /organizations/{organization_id}/oauth/providers", "description": "List all OAuth providers for an organization.", "operationId": "list_org_oauth_providers", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of OAuth providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OAuthProviderResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "oauth-providers" ], "summary": "POST /organizations/{organization_id}/oauth/providers", "description": "Create a new OAuth provider for an organization.", "operationId": "create_org_oauth_provider", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "OAuth provider created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OAuthProviderResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of the organization" }, "409": { "description": "Conflict - provider with this slug already exists" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/oauth/providers/{provider_id}": { "get": { "tags": [ "oauth-providers" ], "summary": "GET /organizations/{organization_id}/oauth/providers/{provider_id}", "description": "Get a specific OAuth provider for an organization.", "operationId": "get_org_oauth_provider", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "path", "description": "OAuth provider ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OAuth provider details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OAuthProviderResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of the organization" }, "404": { "description": "Provider not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "oauth-providers" ], "summary": "DELETE /organizations/{organization_id}/oauth/providers/{provider_id}", "description": "Delete an OAuth provider for an organization.", "operationId": "delete_org_oauth_provider", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "path", "description": "OAuth provider ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OAuth provider deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of the organization" }, "404": { "description": "Provider not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "oauth-providers" ], "summary": "PATCH /organizations/{organization_id}/oauth/providers/{provider_id}", "description": "Update an OAuth provider for an organization.", "operationId": "update_org_oauth_provider", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "path", "description": "OAuth provider ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth provider updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OAuthProviderResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of the organization" }, "404": { "description": "Provider not found" }, "409": { "description": "Conflict - provider with this slug already exists" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp-policy": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/otp-policy", "operationId": "get_organization_otp_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization OTP policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpPolicy" } } } }, "403": { "description": "User is not allowed to view the organization OTP policy" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Organizations" ], "summary": "PUT /organizations/{organization_id}/otp-policy", "operationId": "update_organization_otp_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationOtpPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated organization OTP policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpPolicy" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "User is not allowed to update the organization OTP policy" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp/enrollment": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/otp/enrollment", "operationId": "begin_organization_otp_enrollment", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization OTP enrollment challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpEnrollmentChallenge" } } } }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp/enrollment/confirm": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/otp/enrollment/confirm", "operationId": "confirm_organization_otp_enrollment", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationOtpCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization OTP enrollment confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpStatus" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp/members/{user_id}/reset": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/otp/members/{user_id}/reset", "operationId": "reset_organization_member_otp", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "description": "Target user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization OTP reset completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpResetResponse" } } } }, "403": { "description": "User is not allowed to reset organization OTP" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp/status": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/otp/status", "operationId": "get_organization_otp_status", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scope", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationOtpScope" } } ], "responses": { "200": { "description": "Organization OTP status for the current user and scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpStatus" } } } }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/otp/verify": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/otp/verify", "operationId": "verify_organization_otp_scope", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationOtpVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization OTP scope verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationOtpStatus" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "OTP required or organization membership missing" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/permissions/check/{permission}": { "get": { "tags": [ "RBAC" ], "summary": "Check if the current user has a specific permission", "operationId": "check_permission", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission", "in": "path", "description": "Permission name to check", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Permission check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_bool" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/permissions/mine": { "get": { "tags": [ "RBAC" ], "summary": "Get current user's permissions in an organization", "operationId": "get_my_permissions", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "User's permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_String" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/plan": { "get": { "tags": [ "Plans" ], "summary": "GET /organizations/:org_id/plan\nGet the current plan for an organization", "operationId": "get_organization_plan", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization plan retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationPlanWithDetails" } } } }, "404": { "description": "Organization or plan not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Plans" ], "summary": "POST /organizations/:org_id/plan\nUpgrade or downgrade an organization's plan", "operationId": "change_organization_plan", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Plan changed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationPlanWithDetails" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Organization or plan not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/private-models-policy": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/{organization_id}/private-models-policy", "operationId": "get_private_models_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization private models policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationPrivateModelsPolicy" } } } }, "403": { "description": "User is not a member of the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Organizations" ], "summary": "PUT /organizations/{organization_id}/private-models-policy", "operationId": "update_private_models_policy", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationPrivateModelsPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated organization private models policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationPrivateModelsPolicy" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "User is not allowed to update the organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/publishers": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/:org_id/publishers\nList publishers owned by an organization", "operationId": "list_org_publishers", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publishers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_PublisherResponse" } } } }, "403": { "description": "Not authorized" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/:org_id/publishers\nCreate a new publisher", "operationId": "create_publisher", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublisherRequest" } } }, "required": true }, "responses": { "201": { "description": "Publisher created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Not authorized" }, "409": { "description": "Publisher slug already exists" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/publishers/{publisher_id}": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id\nGet publisher details", "operationId": "get_org_publisher", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publisher retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherResponse" } } } }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "Organizations" ], "summary": "PUT /organizations/:org_id/publishers/:publisher_id\nUpdate a publisher", "operationId": "update_publisher", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublisherRequest" } } }, "required": true }, "responses": { "200": { "description": "Publisher updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Organizations" ], "summary": "DELETE /organizations/:org_id/publishers/:publisher_id\nSoft delete a publisher", "operationId": "delete_publisher", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publisher deleted successfully" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue": { "get": { "tags": [ "Agent Analytics" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id/analytics/revenue\nGet revenue metrics with period-over-period comparison.", "operationId": "get_revenue_metrics", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "description": "Number of days to analyze (default: 30)", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Revenue metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_RevenueMetrics" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue-by-day": { "get": { "tags": [ "Agent Analytics" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id/analytics/revenue-by-day\nGet daily revenue breakdown.", "operationId": "get_revenue_by_day", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "description": "Number of days to analyze (default: 30)", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Daily revenue breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_RevenueByDay" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/publishers/{publisher_id}/analytics/top-agents": { "get": { "tags": [ "Agent Analytics" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id/analytics/top-agents\nGet top agents by spending.", "operationId": "get_top_agents", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of agents to return (default: 10)", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Top agents by spending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_TopAgent" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/publishers/{publisher_id}/earnings": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id/earnings\nList earnings for a publisher (per asset).", "operationId": "get_org_publisher_earnings", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Earnings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_PublisherEarningsResponse" } } } }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/publishers/{publisher_id}/logo": { "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/{organization_id}/publishers/{publisher_id}/logo\nUpload a logo for a publisher", "operationId": "upload_publisher_logo", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoUploadRequest" } } }, "required": true }, "responses": { "200": { "description": "Logo uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LogoUploadResponse" } } } }, "400": { "description": "Invalid image format or size" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/publishers/{publisher_id}/payouts": { "get": { "tags": [ "Organizations" ], "summary": "GET /organizations/:org_id/publishers/:publisher_id/payouts\nList payout requests for a publisher.", "operationId": "list_org_publisher_payouts", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 50)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Payouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_PublisherPayoutResponse" } } } }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Organizations" ], "summary": "POST /organizations/:org_id/publishers/:publisher_id/payouts\nRequest a payout for a publisher's earnings.", "operationId": "create_org_publisher_payout", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublisherPayoutRequest" } } }, "required": true }, "responses": { "201": { "description": "Payout request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherPayoutResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/publishers/{publisher_id}/pricing": { "put": { "tags": [ "Organizations" ], "summary": "PUT /organizations/:org_id/publishers/:publisher_id/pricing\nUpdate publisher pricing config for a specific asset", "operationId": "update_publisher_pricing", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePricingRequest" } } }, "required": true }, "responses": { "200": { "description": "Pricing updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PricingConfigResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/quota": { "get": { "tags": [ "Plans" ], "summary": "GET /organizations/:org_id/quota\nGet current quota usage for an organization", "operationId": "get_quota_usage", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Quota usage retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_QuotaUsage" } } } }, "404": { "description": "Organization or plan not found" }, "500": { "description": "Internal server error" } } } }, "/organizations/{organization_id}/roles": { "get": { "tags": [ "RBAC" ], "summary": "List roles for an organization (includes built-in roles)", "operationId": "list_organization_roles", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_RbacRole" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "RBAC" ], "summary": "Create a custom role", "operationId": "create_organization_role", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequest" } } }, "required": true }, "responses": { "201": { "description": "Role created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_RbacRole" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires org.manage_roles permission" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/roles/{role_id}": { "get": { "tags": [ "RBAC" ], "summary": "Get a specific role", "operationId": "get_role", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "description": "Role ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Role retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_RbacRole" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Role not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "RBAC" ], "summary": "Delete a custom role", "operationId": "delete_organization_role", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "description": "Role ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Role deleted successfully" }, "400": { "description": "Cannot delete built-in role" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires org.manage_roles permission" }, "404": { "description": "Role not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "RBAC" ], "summary": "Update a custom role", "operationId": "update_role", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "description": "Role ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_RbacRole" } } } }, "400": { "description": "Invalid request or cannot modify built-in role" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - requires org.manage_roles permission" }, "404": { "description": "Role not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/templates/analytics/{publisher_id}": { "get": { "tags": [ "templates" ], "summary": "GET /organizations/{organization_id}/templates/analytics/{publisher_id}\nGet template analytics for a specific publisher", "operationId": "get_publisher_template_analytics", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_id", "in": "path", "description": "Publisher ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Analytics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherAnalytics" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not authorized" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/vpc-endpoints": { "get": { "tags": [ "VPC" ], "operationId": "list_org_vpc_endpoints", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "region", "in": "query", "description": "Filter endpoints by region", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of VPC endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "VPC" ], "operationId": "create_org_vpc_endpoint", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationVpcEndpointRequest" } } }, "required": true }, "responses": { "201": { "description": "VPC endpoint recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/vpc-endpoints/{endpoint_id}": { "get": { "tags": [ "VPC" ], "operationId": "get_org_vpc_endpoint", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "VPC endpoint details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "VPC endpoint not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "VPC" ], "operationId": "delete_org_vpc_endpoint", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "VPC endpoint removed" }, "401": { "description": "Unauthorized" }, "404": { "description": "VPC endpoint not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints": { "get": { "tags": [ "VPC" ], "summary": "List VPC endpoints for an organization filtered by region (alias path)", "operationId": "list_org_vpc_endpoints_by_region", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "region_id", "in": "path", "description": "Region", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of VPC endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints/{endpoint_id}": { "get": { "tags": [ "VPC" ], "summary": "Get VPC endpoint details with region in path (alias)", "operationId": "get_org_vpc_endpoint_by_region", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "region_id", "in": "path", "description": "Region", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "VPC endpoint details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "VPC endpoint not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "VPC" ], "summary": "Delete VPC endpoint with region in path (alias)", "operationId": "delete_org_vpc_endpoint_by_region", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "region_id", "in": "path", "description": "Region", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "VPC endpoint removed" }, "401": { "description": "Unauthorized" }, "404": { "description": "VPC endpoint not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/vpc/vpc_endpoints": { "get": { "tags": [ "VPC" ], "summary": "List VPC endpoints for an organization (alias path with underscores)", "operationId": "list_org_vpc_endpoints_alias", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of VPC endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_OrganizationVpcEndpoint" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Organization not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks for an organization", "operationId": "list_webhooks", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhooks retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_WebhookInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "operationId": "create_webhook", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WebhookCreated" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/webhooks/{webhook_id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a specific webhook", "operationId": "get_webhook", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WebhookInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "operationId": "delete_webhook", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Webhook deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "operationId": "update_webhook", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WebhookInfo" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List recent deliveries for a webhook", "operationId": "list_webhook_deliveries", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deliveries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_WebhookDelivery" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/organizations/{organization_id}/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Regenerate webhook secret", "operationId": "rotate_webhook_secret", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID or 'default' for authenticated user's default organization", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Secret rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WebhookCreated" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not a member of this organization" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/payments/supported": { "get": { "tags": [ "payments" ], "summary": "GET /payments/supported\nReturns supported x402 payment kinds for facilitator discovery.", "operationId": "get_supported", "responses": { "200": { "description": "Supported payment kinds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/permissions": { "get": { "tags": [ "RBAC" ], "summary": "List all permissions", "operationId": "list_permissions", "responses": { "200": { "description": "Permissions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Permission" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/plans": { "get": { "tags": [ "Plans" ], "summary": "GET /plans\nList all available subscription plans", "operationId": "list_plans", "responses": { "200": { "description": "Plans retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Plan" } } } }, "500": { "description": "Internal server error" } } } }, "/plans/{plan_id}": { "get": { "tags": [ "Plans" ], "summary": "GET /plans/:plan_id\nGet details of a specific plan", "operationId": "get_plan", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Plan retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Plan" } } } }, "404": { "description": "Plan not found" }, "500": { "description": "Internal server error" } } } }, "/publishers": { "get": { "tags": [ "publishers" ], "summary": "GET /publishers\nList publishers with full details and pricing (store view)", "operationId": "list_store_publishers", "parameters": [ { "name": "is_verified", "in": "query", "description": "Filter by verification status", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "category", "in": "query", "description": "Filter by publisher category", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublisherCategory" } ] } }, { "name": "search", "in": "query", "description": "Search by name or slug", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Publishers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_PublisherResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } } } }, "/publishers/suggest": { "get": { "tags": [ "publishers" ], "summary": "GET /publishers/suggest\nSuggest publishers based on a task or query", "operationId": "suggest_publishers", "parameters": [ { "name": "query", "in": "query", "description": "The task or query to match against publisher capabilities.\nExamples: \"scrape website\", \"AI research\", \"PDF extraction\"", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Type of suggestions: \"publisher\", \"agent\", or \"both\" (default: \"both\")\nNote: Agent suggestions are planned but not yet implemented.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (default: 5, max: 20)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Publisher suggestions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SuggestResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } } } }, "/publishers/{slug}": { "get": { "tags": [ "publishers" ], "summary": "GET /publishers/{slug}\nGet publisher by slug (store view with full details)", "operationId": "get_store_publisher", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publisher retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherResponse" } } } }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "publishers" ], "summary": "Handle requests to the publisher root.", "description": "For database publishers, this executes a query from the request body.\nFor API publishers, this proxies to the root endpoint.\nFor agent publishers (compute_type=agent), this creates a task and returns 202 Accepted.\nFor MCP publishers, this returns an error (use specific tool/resource endpoints).", "operationId": "publisher_root_handler", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug identifier", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublisherRootRequest" } } }, "required": true }, "responses": { "200": { "description": "Request processed successfully (database/API)", "content": { "application/json": { "schema": {} } } }, "202": { "description": "Agent task accepted (async)", "content": { "application/json": { "schema": {} } } }, "402": { "description": "Payment required" }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/publishers/{slug}/estimate": { "post": { "tags": [ "publishers" ], "summary": "Estimate query cost without payment", "operationId": "estimate_query", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequestBody" } } }, "required": true }, "responses": { "200": { "description": "Cost estimate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" } } } }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/publishers/{slug}/logo": { "get": { "tags": [ "publishers" ], "summary": "GET /publishers/{slug}/logo\nFetch publisher logo (inline data or redirect to URL)\nAccepts either publisher slug or UUID for backwards compatibility", "operationId": "get_store_publisher_logo", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug or UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publisher logo bytes" }, "302": { "description": "Redirect to external logo URL" }, "404": { "description": "Logo not found" } } } }, "/publishers/{slug}/{path}": { "get": { "tags": [ "publishers" ], "operationId": "proxy_to_publisher_get", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug identifier", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path to proxy to the publisher", "required": true, "schema": { "type": "string" } }, { "name": "x-seren-oauth-connection-id", "in": "header", "description": "Optional OAuth connection UUID for BYOC publishers", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "connection_id", "in": "query", "description": "Optional OAuth connection UUID for MCP publisher routes", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Request proxied successfully. Response shape depends on publisher type and sub-path; first-class publisher endpoints document typed schemas.", "content": { "application/json": { "schema": {} } } }, "402": { "description": "Payment required" }, "403": { "description": "Publisher is geo-restricted and routing is not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoRestrictedError" } } } }, "404": { "description": "Publisher or endpoint not found" }, "409": { "description": "Multiple OAuth connections are available and no selector/default was provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleOAuthConnectionsAmbiguousResponse" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "publishers" ], "operationId": "proxy_to_publisher_post", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug identifier", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Path to proxy to the publisher", "required": true, "schema": { "type": "string" } }, { "name": "x-seren-oauth-connection-id", "in": "header", "description": "Optional OAuth connection UUID for BYOC publishers", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "connection_id", "in": "query", "description": "Optional OAuth connection UUID for MCP publisher routes", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Request proxied successfully. Response shape depends on publisher type and sub-path; first-class publisher endpoints document typed schemas.", "content": { "application/json": { "schema": {} } } }, "402": { "description": "Payment required" }, "403": { "description": "Publisher is geo-restricted and routing is not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoRestrictedError" } } } }, "404": { "description": "Publisher or endpoint not found" }, "409": { "description": "Multiple OAuth connections are available and no selector/default was provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleOAuthConnectionsAmbiguousResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List all active sessions for the current user", "operationId": "list_sessions", "responses": { "200": { "description": "Sessions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Session" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/sessions/revoke-all": { "post": { "tags": [ "Sessions" ], "summary": "Revoke all sessions (logout everywhere)", "operationId": "revoke_all_sessions", "responses": { "200": { "description": "All sessions revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SessionsRevoked" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/sessions/{session_id}": { "delete": { "tags": [ "Sessions" ], "summary": "Revoke a specific session", "operationId": "revoke_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID to revoke", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SessionsRevoked" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/sessions/{session_id}/revoke-others": { "post": { "tags": [ "Sessions" ], "summary": "Revoke all sessions except a specified one", "operationId": "revoke_other_sessions", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID to keep (current session)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Other sessions revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SessionsRevoked" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Session not found or doesn't belong to user" } }, "security": [ { "bearer_auth": [] } ] } }, "/templates": { "get": { "tags": [ "templates" ], "summary": "GET /templates\nList available templates in the catalog", "operationId": "list_templates", "parameters": [ { "name": "verified_only", "in": "query", "description": "Filter to verified templates only", "required": false, "schema": { "type": "boolean" } }, { "name": "language", "in": "query", "description": "Filter by language (python, typescript, javascript)", "required": false, "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "description": "Minimum price in atomic units", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "max_price", "in": "query", "description": "Maximum price in atomic units", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "search", "in": "query", "description": "Search in name and description", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort order (popularity, price_asc, price_desc, newest, oldest)", "required": false, "schema": { "$ref": "#/components/schemas/TemplateSortBy" } }, { "name": "limit", "in": "query", "description": "Maximum number of templates to return (default: 50)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Templates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AgentTemplateSummary" } } } }, "500": { "description": "Internal server error" } } } }, "/templates/publish": { "post": { "tags": [ "templates" ], "summary": "POST /templates/publish\nPublish a new agent template", "operationId": "publish_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } }, "required": true }, "responses": { "201": { "description": "Template published successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CreateTemplateResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "409": { "description": "Template slug already exists" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/templates/{slug}": { "get": { "tags": [ "templates" ], "summary": "GET /templates/{slug}\nGet template details by slug", "operationId": "get_template", "parameters": [ { "name": "slug", "in": "path", "description": "Template slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CreateTemplateResponse" } } } }, "404": { "description": "Template not found" }, "500": { "description": "Internal server error" } } } }, "/templates/{slug}/invoke": { "post": { "tags": [ "templates" ], "summary": "POST /templates/{slug}/invoke\nInvoke an agent template.", "description": "Supports two modes:\n- **Bearer auth present**: uses the authenticated user's SerenBucks balance.\n- **No bearer auth**: uses x402 (requires `X-AGENT-WALLET` + payment headers).", "operationId": "invoke_template", "parameters": [ { "name": "slug", "in": "path", "description": "Template slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Template invoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_InvokeTemplateResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication failed" }, "402": { "description": "Payment required" }, "404": { "description": "Template not found" }, "500": { "description": "Internal server error" }, "503": { "description": "Sandbox execution failed" } } } }, "/wallet/balance": { "get": { "tags": [ "agent-wallet" ], "summary": "Get wallet balance (funded + promotional)", "operationId": "get_wallet_balance", "responses": { "200": { "description": "Wallet balance retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletBalanceResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/bonus/payment-method": { "post": { "tags": [ "agent-wallet" ], "summary": "Claim payment method bonus (if not already claimed)", "operationId": "claim_payment_method_bonus", "responses": { "200": { "description": "Payment method bonus claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BonusClaimResponse" } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Bonus already claimed" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/bonus/signup": { "post": { "tags": [ "agent-wallet" ], "summary": "Claim signup bonus (if not already claimed)", "operationId": "claim_signup_bonus", "responses": { "200": { "description": "Signup bonus claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BonusClaimResponse" } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Bonus already claimed" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/daily/claim": { "post": { "tags": [ "agent-wallet" ], "summary": "Claim daily free credits", "operationId": "claim_daily", "responses": { "200": { "description": "Daily credits claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_DailyClaimResponse" } } } }, "400": { "description": "Not eligible for daily claim" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/daily/eligibility": { "get": { "tags": [ "agent-wallet" ], "summary": "Check if user can claim daily credits", "operationId": "check_daily_eligibility", "responses": { "200": { "description": "Eligibility checked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_DailyClaimEligibilityResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/deposit": { "post": { "tags": [ "agent-wallet" ], "summary": "Deposit funds via Stripe", "operationId": "create_deposit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositRequest" } } }, "required": true }, "responses": { "200": { "description": "Deposit initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_DepositResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Verified email required" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/deposit/crypto": { "post": { "tags": [ "agent-wallet" ], "summary": "Deposit configured asset via on-chain payment flow", "description": "Allows agents to deposit the configured asset directly on-chain to their prepaid balance.\nFollows the 402 payment protocol:\n1. First request (no payment header) returns 402 with payment requirements\n2. Second request (with payment header) settles on-chain and credits balance", "operationId": "onchain_deposit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnchainDepositRequest" } } }, "required": true }, "responses": { "200": { "description": "Deposit successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnchainDepositResponse" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponseWithInfo" } } } }, "404": { "description": "Publisher not found" }, "500": { "description": "Internal server error" } } } }, "/wallet/lookup/{agent_wallet}": { "get": { "tags": [ "publisher-payments" ], "summary": "GET /wallet/lookup/{agent_wallet}\nLook up an agent's available balance (for publisher pre-checks)", "operationId": "get_agent_balance", "parameters": [ { "name": "agent_wallet", "in": "path", "description": "Agent wallet address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublisherAgentBalance" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Publisher not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/recover": { "post": { "tags": [ "agent-wallet" ], "summary": "POST /wallet/recover\nRecover an agent account using a recovery code.", "description": "This endpoint allows agents who have lost their API key to recover their account\nusing the recovery code they saved when setting up wallet recovery.\n\n**What this does:**\n- Verifies the recovery code\n- Revokes all existing API keys (for security)\n- Issues a new API key\n- Rotates the recovery code (old code is invalidated)\n\n**Important:** Save both the new API key AND the new recovery code - they're only shown once!", "operationId": "wallet_recover", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRecoverRequest" } } }, "required": true }, "responses": { "200": { "description": "Account recovered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletRecoverResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid recovery code" }, "500": { "description": "Internal server error" } } } }, "/wallet/recovery": { "post": { "tags": [ "agent-wallet" ], "summary": "Set up account recovery (recovery code and/or email).", "description": "- If you don't have a `recovery_code` yet, this endpoint generates one and returns it **once**.\n- If you already have a `recovery_code`, it will not be shown again.\n- You can optionally set/update a recovery `email` for human account recovery.\n\nUse the recovery code with `POST /wallet/recover` to rotate access after losing your API key.", "operationId": "set_recovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRecoveryRequest" } } }, "required": true }, "responses": { "200": { "description": "Recovery set up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_RecoveryResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/referral": { "get": { "tags": [ "agent-wallet" ], "summary": "Get user's referral info and code", "operationId": "get_referral_info", "responses": { "200": { "description": "Referral info retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ReferralInfoResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/referral/apply": { "post": { "tags": [ "agent-wallet" ], "summary": "Apply a referral code to the current user", "operationId": "apply_referral_code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyReferralRequest" } } }, "required": true }, "responses": { "200": { "description": "Referral code applied" }, "400": { "description": "Invalid referral code" }, "401": { "description": "Unauthorized" }, "409": { "description": "Already has a referrer" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/settlements/{receipt_id}": { "get": { "tags": [ "agent-wallet" ], "summary": "Get the settlement state for a priced publisher operation.", "operationId": "get_settlement_receipt", "parameters": [ { "name": "receipt_id", "in": "path", "description": "Settlement receipt ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement receipt retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SettlementReceiptResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Settlement receipt not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transactions": { "get": { "tags": [ "agent-wallet" ], "summary": "Get transaction history including credits and debits", "operationId": "get_transactions", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of transactions to return (default 50, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page. When present, offset is ignored.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_usage", "in": "query", "description": "Include raw usage/micropayment debits (default false).\nWhen false, usage debits are aggregated by day and publisher.", "required": false, "schema": { "type": "boolean" } }, { "name": "exact_total", "in": "query", "description": "Compute an exact total row count. Defaults to false because exact counts\ncan require scanning large wallet histories.", "required": false, "schema": { "type": "boolean" } }, { "name": "start_date", "in": "query", "description": "Filter: only transactions on or after this date (YYYY-MM-DD, interpreted as UTC midnight)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "description": "Filter: only transactions strictly before this date (YYYY-MM-DD, interpreted as UTC midnight).\nTo include a full day, set end_date to the day *after* the last day you want.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Transaction history retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransactionHistoryResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transactions/export": { "get": { "tags": [ "agent-wallet" ], "summary": "Export transactions as a CSV file for a date range", "operationId": "export_transactions", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (YYYY-MM-DD, inclusive, UTC midnight)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "description": "End date (YYYY-MM-DD, exclusive, UTC midnight)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "CSV file download", "content": { "text/csv": {} } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transactions/summary": { "get": { "tags": [ "agent-wallet" ], "summary": "Get summary statistics for transactions in a date range", "operationId": "get_transaction_summary", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (YYYY-MM-DD, inclusive, UTC midnight)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end_date", "in": "query", "description": "End date (YYYY-MM-DD, exclusive, UTC midnight)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Transaction summary retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_TransactionSummaryResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transfers": { "get": { "tags": [ "agent-wallet" ], "summary": "List SerenBucks wallet transfers.", "operationId": "list_wallet_transfers", "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WalletTransferDirection" } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Transfers retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransferListResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "agent-wallet" ], "summary": "Execute a SerenBucks wallet transfer.", "operationId": "execute_wallet_transfer", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique key for safely retrying transfer execution", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransferRequest" } } }, "required": true }, "responses": { "200": { "description": "Transfer executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransferExecuteResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Idempotency conflict" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transfers/invite/claim": { "post": { "tags": [ "agent-wallet" ], "summary": "Claim a pending SerenBucks transfer invite.", "operationId": "claim_wallet_transfer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransferClaimRequest" } } }, "required": true }, "responses": { "200": { "description": "Pending transfer claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransferClaimResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Verified email required or email mismatch" }, "404": { "description": "Invite not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transfers/pending/{pending_transfer_id}/recall": { "post": { "tags": [ "agent-wallet" ], "summary": "Recall a pending SerenBucks transfer.", "operationId": "recall_wallet_transfer", "parameters": [ { "name": "pending_transfer_id", "in": "path", "description": "Pending transfer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending transfer recalled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransferRecallResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Pending transfer not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/wallet/transfers/preview": { "post": { "tags": [ "agent-wallet" ], "summary": "Preview a SerenBucks wallet transfer.", "operationId": "preview_wallet_transfer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransferRequest" } } }, "required": true }, "responses": { "200": { "description": "Transfer preview retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_WalletTransferPreviewResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/webhooks/event-types": { "get": { "tags": [ "Webhooks" ], "summary": "List available event types", "operationId": "list_event_types", "responses": { "200": { "description": "Event types retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_String" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/webhooks/stripe": { "post": { "tags": [ "webhooks" ], "summary": "POST /webhooks/stripe\nHandle Stripe webhook events", "operationId": "handle_stripe_webhook", "responses": { "200": { "description": "Webhook processed" }, "400": { "description": "Invalid webhook signature" }, "500": { "description": "Internal server error" } } } }, "/webhooks/{route_id}": { "get": { "tags": [ "Connector Webhooks" ], "summary": "Supports provider verification callbacks that use GET.", "operationId": "get_connector_webhook", "parameters": [ { "name": "route_id", "in": "path", "description": "Opaque connector webhook route id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider-specific webhook verification response" }, "202": { "description": "Webhook verification accepted" }, "400": { "description": "Invalid route id" }, "404": { "description": "Unknown, disabled, or stale route" }, "502": { "description": "Connector gateway rejected or failed the callback" }, "503": { "description": "Connector route temporarily unavailable" } } }, "post": { "tags": [ "Connector Webhooks" ], "summary": "Accepts provider webhook callbacks for managed agent channel connectors.", "description": "This route is intentionally public because providers call it directly. The\nroute id maps to server-side connector routing metadata; provider-specific\nsignature verification happens inside the selected connector plugin.", "operationId": "post_connector_webhook", "parameters": [ { "name": "route_id", "in": "path", "description": "Opaque connector webhook route id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider-specific webhook response" }, "202": { "description": "Webhook event accepted" }, "400": { "description": "Invalid route id" }, "404": { "description": "Unknown, disabled, or stale route" }, "502": { "description": "Connector gateway rejected or failed the callback" }, "503": { "description": "Connector route temporarily unavailable" } } } }, "/publishers/seren-db/projects": { "get": { "tags": [ "seren-db" ], "summary": "List all projects in the organization.", "operationId": "seren_db_list_projects", "responses": { "200": { "description": "Projects listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a new SerenDB project.", "operationId": "seren_db_create_project", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreatedResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}": { "get": { "tags": [ "seren-db" ], "summary": "Get a project by ID.", "operationId": "seren_db_get_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-db" ], "summary": "Delete a project.", "operationId": "seren_db_delete_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update a project.", "operationId": "seren_db_update_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branch-protection": { "get": { "tags": [ "seren-db" ], "summary": "List branch protection rules for a project.", "operationId": "seren_db_list_branch_protection_rules", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch protection rules listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_BranchProtection" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches": { "get": { "tags": [ "seren-db" ], "summary": "List all branches in a project.", "operationId": "seren_db_list_branches", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branches listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a new branch in a project.", "operationId": "seren_db_create_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchRequest" } } }, "required": true }, "responses": { "201": { "description": "Branch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCreationResultResponse" } } } }, "400": { "description": "Bad request" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/count": { "get": { "tags": [ "seren-db" ], "summary": "Get branch count for a project.", "operationId": "seren_db_get_branch_count", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch count retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}": { "get": { "tags": [ "seren-db" ], "summary": "Get a specific branch.", "operationId": "seren_db_get_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-db" ], "summary": "Delete a branch.", "operationId": "seren_db_delete_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Rename a branch.", "operationId": "seren_db_rename_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameBranchRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/archived": { "patch": { "tags": [ "seren-db" ], "summary": "Set a branch archived state.", "operationId": "seren_db_set_branch_archived", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBranchArchivedRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch archived state updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/connection-string": { "get": { "tags": [ "seren-db" ], "summary": "Get a branch connection string.", "operationId": "seren_db_get_connection_string", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pooled", "in": "query", "description": "Use pooled connection if true", "required": false, "schema": { "type": "boolean" } }, { "name": "role", "in": "query", "description": "Optional role name override", "required": false, "schema": { "type": "string" } }, { "name": "database", "in": "query", "description": "Optional database name override", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection string retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ConnectionString" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/databases": { "get": { "tags": [ "seren-db" ], "summary": "List all databases on a branch.", "operationId": "seren_db_list_databases", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Databases listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabasesWithOwnerResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a new database on a branch.", "operationId": "seren_db_create_database", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatabaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Database created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseCreatedResponse" } } } }, "400": { "description": "Bad request" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}": { "get": { "tags": [ "seren-db" ], "summary": "Get a specific database.", "operationId": "seren_db_get_database", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "did", "in": "path", "description": "Database ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Database retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseWithOwnerResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "seren-db" ], "summary": "Update a database (change owner).", "operationId": "seren_db_update_database", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "did", "in": "path", "description": "Database ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatabaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Database updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseWithOwnerResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-db" ], "summary": "Delete a database.", "operationId": "seren_db_delete_database", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "did", "in": "path", "description": "Database ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Database deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/details": { "get": { "tags": [ "seren-db" ], "summary": "Get branch details.", "operationId": "seren_db_get_branch_details", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BranchDetail" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints": { "get": { "tags": [ "seren-db" ], "summary": "List all endpoints on a branch.", "operationId": "seren_db_list_endpoints", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoints listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_EndpointResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a new compute endpoint on a branch.", "operationId": "seren_db_create_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" } } }, "required": true }, "responses": { "201": { "description": "Endpoint created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointCreatedResponse" } } } }, "400": { "description": "Bad request" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}": { "delete": { "tags": [ "seren-db" ], "summary": "Delete an endpoint.", "operationId": "seren_db_delete_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update an endpoint's settings.", "operationId": "seren_db_update_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" } } }, "required": true }, "responses": { "200": { "description": "Endpoint updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_EndpointResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/health": { "get": { "tags": [ "seren-db" ], "summary": "Get endpoint health.", "operationId": "seren_db_get_endpoint_health", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint health retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/metrics": { "get": { "tags": [ "seren-db" ], "summary": "Get endpoint metrics.", "operationId": "seren_db_get_endpoint_metrics", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint metrics retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/start": { "post": { "tags": [ "seren-db" ], "summary": "Start a suspended endpoint.", "operationId": "seren_db_start_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointStatusInfoResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/status": { "get": { "tags": [ "seren-db" ], "summary": "Get endpoint status.", "operationId": "seren_db_get_endpoint_status", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointStatusInfoResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/stop": { "post": { "tags": [ "seren-db" ], "summary": "Stop (suspend) an endpoint.", "operationId": "seren_db_stop_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointStatusInfoResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/expiration": { "patch": { "tags": [ "seren-db" ], "summary": "Set branch expiration.", "operationId": "seren_db_set_branch_expiration", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBranchExpirationRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch expiration set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/lsn_by_timestamp": { "get": { "tags": [ "seren-db" ], "summary": "Get LSN by timestamp for a branch.", "operationId": "seren_db_get_lsn_by_timestamp", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "timestamp", "in": "query", "description": "Timestamp in ISO-8601 format", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "LSN retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LsnByTimestamp" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/protection": { "get": { "tags": [ "seren-db" ], "summary": "Get branch protection rule for a branch.", "operationId": "seren_db_get_branch_protection", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch protection rule retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BranchProtection" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create branch protection rule for a branch.", "operationId": "seren_db_create_branch_protection", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchProtectionRequest" } } }, "required": true }, "responses": { "201": { "description": "Branch protection rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BranchProtection" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-db" ], "summary": "Delete branch protection rule for a branch.", "operationId": "seren_db_delete_branch_protection", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Branch protection rule deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update branch protection rule for a branch.", "operationId": "seren_db_update_branch_protection", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBranchProtectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch protection rule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BranchProtection" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/publications": { "get": { "tags": [ "seren-db" ], "summary": "List publications for a branch.", "operationId": "seren_db_list_publications", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publications listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_PublicationInfo" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a publication for a branch.", "operationId": "seren_db_create_publication", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicationRequest" } } }, "required": true }, "responses": { "201": { "description": "Publication created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublicationInfo" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/publications/{publication_id}": { "delete": { "tags": [ "seren-db" ], "summary": "Delete a publication from a branch.", "operationId": "seren_db_delete_publication", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publication_id", "in": "path", "description": "Publication ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Publication deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update a publication for a branch.", "operationId": "seren_db_update_publication", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "publication_id", "in": "path", "description": "Publication ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublicationRequest" } } }, "required": true }, "responses": { "200": { "description": "Publication updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PublicationInfo" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/replication-slots": { "get": { "tags": [ "seren-db" ], "summary": "List replication slots for a branch.", "operationId": "seren_db_list_replication_slots", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replication slots listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_ReplicationSlotInfo" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a replication slot for a branch.", "operationId": "seren_db_create_replication_slot", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReplicationSlotRequest" } } }, "required": true }, "responses": { "201": { "description": "Replication slot created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ReplicationSlotInfo" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/replication-slots/{slot_id}": { "delete": { "tags": [ "seren-db" ], "summary": "Delete a replication slot from a branch.", "operationId": "seren_db_delete_replication_slot", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "slot_id", "in": "path", "description": "Replication slot ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Replication slot deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/reset": { "post": { "tags": [ "seren-db" ], "summary": "Reset a branch.", "operationId": "seren_db_reset_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetBranchRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/restore": { "post": { "tags": [ "seren-db" ], "summary": "Restore a branch.", "operationId": "seren_db_restore_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreBranchRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BranchRestored" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/roles": { "get": { "tags": [ "seren-db" ], "summary": "List all roles on a branch.", "operationId": "seren_db_list_roles", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Roles listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleInfosResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Create a new role on a branch.", "operationId": "seren_db_create_role", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDbRoleRequest" } } }, "required": true }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleCreatedResponse" } } } }, "400": { "description": "Bad request" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}": { "delete": { "tags": [ "seren-db" ], "summary": "Delete a role from a branch.", "operationId": "seren_db_delete_role", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rid", "in": "path", "description": "Role ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Role deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}/reset_password": { "post": { "tags": [ "seren-db" ], "summary": "Reset a role's password.", "operationId": "seren_db_reset_role_password", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rid", "in": "path", "description": "Role ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Password reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePasswordResetResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/roles/{role_name}/reveal_password": { "get": { "tags": [ "seren-db" ], "summary": "Reveal a role password by role name.", "operationId": "seren_db_reveal_role_password", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_name", "in": "path", "description": "Role name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role password revealed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePasswordResetResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/set-default": { "post": { "tags": [ "seren-db" ], "summary": "Set a branch as the default for its project.", "operationId": "seren_db_set_default_branch", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch set as default", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/set_as_default": { "post": { "tags": [ "seren-db" ], "summary": "Set a branch as default using set_as_default alias.", "operationId": "seren_db_set_default_branch_alias", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branch set as default", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/branches/{bid}/timestamp_by_lsn": { "get": { "tags": [ "seren-db" ], "summary": "Get timestamp by LSN for a branch.", "operationId": "seren_db_get_timestamp_by_lsn", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bid", "in": "path", "description": "Branch ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lsn", "in": "query", "description": "Log sequence number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timestamp retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_TimestampByLsn" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/connection_uri": { "get": { "tags": [ "seren-db" ], "summary": "Get connection URI for a project.", "operationId": "seren_db_connection_uri", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "branch_id", "in": "query", "description": "Optional branch ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "endpoint_id", "in": "query", "description": "Optional endpoint ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "database_name", "in": "query", "description": "Optional database name", "required": false, "schema": { "type": "string" } }, { "name": "role_name", "in": "query", "description": "Optional role name", "required": false, "schema": { "type": "string" } }, { "name": "pooled", "in": "query", "description": "Use pooled connection if true", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Connection URI retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectConnectionUriDataResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/consumption": { "get": { "tags": [ "seren-db" ], "summary": "Get consumption for a project.", "operationId": "seren_db_get_project_consumption", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "End date (YYYY-MM-DD)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Consumption retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ProjectConsumption" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/databases": { "get": { "tags": [ "seren-db" ], "summary": "List all databases for a project.", "operationId": "seren_db_list_project_databases", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project databases listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/endpoints": { "get": { "tags": [ "seren-db" ], "summary": "List all endpoints for a project.", "operationId": "seren_db_list_project_endpoints", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project endpoints listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/endpoints/{eid}": { "delete": { "tags": [ "seren-db" ], "summary": "Delete a project endpoint.", "operationId": "seren_db_delete_project_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project endpoint deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update a project endpoint.", "operationId": "seren_db_update_project_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" } } }, "required": true }, "responses": { "200": { "description": "Project endpoint updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/endpoints/{eid}/restart": { "post": { "tags": [ "seren-db" ], "summary": "Restart an endpoint by project and endpoint ID.", "operationId": "seren_db_restart_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint restarted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointStatusInfoResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/endpoints/{eid}/start": { "post": { "tags": [ "seren-db" ], "summary": "Start a project endpoint.", "operationId": "seren_db_start_project_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project endpoint started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/endpoints/{eid}/suspend": { "post": { "tags": [ "seren-db" ], "summary": "Suspend a project endpoint.", "operationId": "seren_db_suspend_project_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "eid", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project endpoint suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/ip-allow": { "get": { "tags": [ "seren-db" ], "summary": "List project IP allow list entries.", "operationId": "seren_db_list_ip_allow_list", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "IP allow list listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_IpAllowList" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Add an IP allow list entry.", "operationId": "seren_db_add_ip_allow_list", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddIpAllowListRequest" } } }, "required": true }, "responses": { "201": { "description": "IP allow list entry added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_IpAllowList" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/ip-allow/reset": { "put": { "tags": [ "seren-db" ], "summary": "Replace the project IP allow list.", "operationId": "seren_db_reset_ip_allow_list", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetIpAllowListRequest" } } }, "required": true }, "responses": { "200": { "description": "IP allow list reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_IpAllowList" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/ip-allow/{ip_id}": { "delete": { "tags": [ "seren-db" ], "summary": "Remove an IP allow list entry.", "operationId": "seren_db_remove_ip_allow_list", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ip_id", "in": "path", "description": "IP allow list entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "IP allow list entry removed" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/operations": { "get": { "tags": [ "seren-db" ], "summary": "List operations for a project.", "operationId": "seren_db_list_operations", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operations listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/operations/{operation_id}": { "get": { "tags": [ "seren-db" ], "summary": "Get a specific operation for a project.", "operationId": "seren_db_get_operation", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "description": "Operation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/replication": { "get": { "tags": [ "seren-db" ], "summary": "Get logical replication settings for a project.", "operationId": "seren_db_get_replication_settings", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replication settings retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LogicalReplicationSettings" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-db" ], "summary": "Update logical replication settings for a project.", "operationId": "seren_db_update_replication_settings", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLogicalReplicationRequest" } } }, "required": true }, "responses": { "200": { "description": "Replication settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_LogicalReplicationSettings" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/size": { "get": { "tags": [ "seren-db" ], "summary": "Get project size.", "operationId": "seren_db_get_project_size", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project size retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ProjectSize" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/vpc-endpoints": { "get": { "tags": [ "seren-db" ], "summary": "List project VPC endpoint assignments.", "operationId": "seren_db_list_project_vpc_endpoints", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "VPC endpoint assignments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-db" ], "summary": "Assign a VPC endpoint to a project.", "operationId": "seren_db_assign_project_vpc_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignProjectVpcEndpointRequest" } } }, "required": true }, "responses": { "201": { "description": "VPC endpoint assignment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/vpc-endpoints/{assignment_id}": { "delete": { "tags": [ "seren-db" ], "summary": "Remove a project VPC endpoint assignment.", "operationId": "seren_db_remove_project_vpc_endpoint", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "assignment_id", "in": "path", "description": "Assignment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "VPC endpoint assignment removed" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/vpc_endpoints": { "get": { "tags": [ "seren-db" ], "summary": "List project VPC endpoint assignments (underscore alias).", "operationId": "seren_db_list_project_vpc_endpoints_alias", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "VPC endpoint assignments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/projects/{id}/vpc_endpoints/{vpc_endpoint_id}": { "post": { "tags": [ "seren-db" ], "summary": "Assign a VPC endpoint to a project by endpoint id (underscore alias).", "operationId": "seren_db_assign_project_vpc_endpoint_by_id", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "vpc_endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "VPC endpoint assignment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-db" ], "summary": "Remove a project VPC endpoint assignment by endpoint id (underscore alias).", "operationId": "seren_db_remove_project_vpc_endpoint_by_vpc_id", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "vpc_endpoint_id", "in": "path", "description": "Organization VPC endpoint ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "VPC endpoint assignment removed" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-db/query": { "post": { "tags": [ "seren-db" ], "summary": "Execute a SQL query against a SerenDB database.", "operationId": "seren_db_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_QueryResult" } } } }, "400": { "description": "Bad request / query error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/audit": { "get": { "tags": [ "seren-cloud" ], "summary": "List tamper-evident audit entries for seren-cloud.", "operationId": "seren_cloud_list_audit_entries", "parameters": [ { "name": "limit", "in": "query", "description": "Max audit entries to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "action", "in": "query", "description": "Filter by exact audit action", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across action, actor, and details", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit entries listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AuditEntry" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/audit/verify": { "get": { "tags": [ "seren-cloud" ], "summary": "Verify the tamper-evident audit chain.", "operationId": "seren_cloud_verify_audit", "parameters": [ { "name": "limit", "in": "query", "description": "Max audit entries to verify in sequence order (default: 10000, max: 100000)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Audit verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_VerificationResult" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/audit/{entry_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single tamper-evident audit entry.", "operationId": "seren_cloud_get_audit_entry", "parameters": [ { "name": "entry_id", "in": "path", "description": "Audit entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit entry details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AuditEntry" } } } }, "404": { "description": "Audit entry not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/connectors": { "get": { "tags": [ "seren-cloud" ], "summary": "List supported messaging connectors with credential requirements and\nthis organization's connection status.", "operationId": "seren_cloud_list_connectors", "responses": { "200": { "description": "Supported connectors with credential fields and connection status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ConnectorCatalogResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/connectors/{connector_ref}/verify": { "post": { "tags": [ "seren-cloud" ], "summary": "Verify connector credentials against the provider without storing them.", "operationId": "seren_cloud_verify_connector_credentials", "parameters": [ { "name": "connector_ref", "in": "path", "description": "Connector catalog reference", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyConnectorCredentialsRequest" } } }, "required": true }, "responses": { "200": { "description": "Verification outcome; invalid credentials return ok=false", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_VerifyConnectorCredentialsResponse" } } } }, "400": { "description": "Unsupported connector or malformed request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Unknown connector" }, "502": { "description": "Connector provider is temporarily unavailable" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/credential-secrets": { "get": { "tags": [ "seren-cloud" ], "summary": "List managed-agent credential secret metadata for the organization.", "operationId": "seren_cloud_list_credential_secrets", "parameters": [ { "name": "scope", "in": "query", "description": "Filter by scope: organization or user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credential secret metadata; values are never returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AgentCredentialSecret" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "summary": "Store or rotate a managed-agent credential secret.", "operationId": "seren_cloud_upsert_credential_secret", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAgentCredentialSecretRequest" } } }, "required": true }, "responses": { "200": { "description": "Credential secret stored; the value is encrypted and never echoed back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCredentialSecret" } } } }, "400": { "description": "Invalid secret name or value" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/credential-secrets/{name}": { "delete": { "tags": [ "seren-cloud" ], "summary": "Delete a managed-agent credential secret by name.", "operationId": "seren_cloud_delete_credential_secret", "parameters": [ { "name": "name", "in": "path", "description": "Credential secret name", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "Scope to delete from: organization (default) or user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credential secret deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCredentialSecretDeleted" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Credential secret not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deploy": { "post": { "tags": [ "seren-cloud" ], "summary": "Deploy a skill to seren-cloud.", "operationId": "seren_cloud_deploy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudDeploymentRequest" } } }, "required": true }, "responses": { "202": { "description": "Deployment accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployment-bundles": { "post": { "tags": [ "seren-cloud" ], "summary": "Register a content-addressed deployment bundle before uploading raw bytes.", "operationId": "seren_cloud_create_deployment_bundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudDeploymentBundleRequest" } } }, "required": true }, "responses": { "200": { "description": "Deployment bundle registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CreateCloudDeploymentBundleResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployment-bundles/{id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get deployment bundle metadata without raw content.", "operationId": "seren_cloud_get_deployment_bundle", "parameters": [ { "name": "id", "in": "path", "description": "Deployment bundle ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment bundle metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentBundleDetail" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Deployment bundle not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployment-bundles/{id}/complete": { "post": { "tags": [ "seren-cloud" ], "summary": "Complete a direct-to-S3 upload for a registered deployment bundle.", "operationId": "seren_cloud_complete_deployment_bundle_upload", "parameters": [ { "name": "id", "in": "path", "description": "Deployment bundle ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment bundle upload completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentBundle" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Deployment bundle not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments": { "get": { "tags": [ "seren-cloud" ], "summary": "List all deployments for the authenticated organization.", "operationId": "seren_cloud_list_deployments", "responses": { "200": { "description": "Deployments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentSummary" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get details of a specific deployment.", "operationId": "seren_cloud_get_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-cloud" ], "summary": "Delete a deployment and clean up runtime resources.", "operationId": "seren_cloud_delete", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-cloud" ], "summary": "Update config and/or secrets without redeploying code.", "operationId": "seren_cloud_update_config", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCloudDeploymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Config updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/audit": { "get": { "tags": [ "seren-cloud" ], "summary": "List tamper-evident audit entries scoped to a deployment.", "operationId": "seren_cloud_deployment_audit", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max audit entries to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "action", "in": "query", "description": "Filter by exact audit action", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across action, actor, and details", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deployment audit entries listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AuditEntry" } } } }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/connectors/{connector_ref}": { "put": { "tags": [ "seren-cloud" ], "summary": "Bind encrypted `seren-secrets://` references to a managed agent connector.", "operationId": "seren_cloud_bind_connector_secrets", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connector_ref", "in": "path", "description": "Connector catalog reference", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindConnectorSecretsRequest" } } }, "required": true }, "responses": { "200": { "description": "Connector secret references bound to the managed agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_BoundConnectorSecrets" } } } }, "400": { "description": "Invalid connector secret references" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment or connector not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/conversations": { "get": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_list_conversations", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max conversations to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque keyset cursor returned by the previous page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversations listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudConversationListResponse" } } } }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/conversations/{conversation_id}/messages": { "get": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_get_conversation_messages", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "conversation_id", "in": "path", "description": "Durable conversation ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max messages to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque keyset cursor returned by the previous page", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Message page order, asc or desc (default: desc)", "required": false, "schema": { "$ref": "#/components/schemas/ConversationMessageOrder" } }, { "name": "include_run", "in": "query", "description": "Include full run records for run-backed messages (default: true)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Conversation messages listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudConversationMessagesResponse" } } } }, "404": { "description": "Conversation not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/deployment-bundle-download": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a short-lived direct download URL for a deployment runtime bundle.", "operationId": "seren_cloud_get_deployment_bundle_download", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment bundle download instructions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentBundleDownloadResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment or bundle not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/eval-drift": { "get": { "tags": [ "seren-cloud" ], "summary": "Compare the deployment's current eval-set verdict against the baseline\ncaptured at the last successful apply. Reports `passed`/`failed` deltas\nplus an operator-safe summary message.", "operationId": "seren_cloud_get_deployment_eval_drift", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Drift snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentEvalDrift" } } } }, "400": { "description": "Deployment has no eval gate configured" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/pending_approvals": { "get": { "tags": [ "seren-cloud" ], "summary": "List awaiting-approval runs for a deployment.", "operationId": "seren_cloud_deployment_pending_approvals", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max runs to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "compute_backend", "in": "query", "description": "Filter by compute backend (aws_container, cloudflare_worker, daytona)", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source (api, cli, scheduler, ui, system, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "has_artifacts", "in": "query", "description": "Filter runs by artifact existence", "required": false, "schema": { "type": "boolean" } }, { "name": "started_after", "in": "query", "description": "Filter runs started at/after RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "started_before", "in": "query", "description": "Filter runs started at/before RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across execution_id, status, source, run_name, output, metadata", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Awaiting-approval runs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudPendingApprovalRun" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs": { "get": { "tags": [ "seren-cloud" ], "summary": "List run events (history) for a deployment.", "operationId": "seren_cloud_deployment_runs", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max runs to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "conversation_id", "in": "query", "description": "Filter runs by exact conversation ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Repeat or comma-separate statuses: queued, running, awaiting_approval, completed, failed, cancelled, timeout, blocked, error", "required": false, "schema": { "type": "string" } }, { "name": "compute_backend", "in": "query", "description": "Filter by compute backend (aws_container, cloudflare_worker, daytona)", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source (api, cli, scheduler, ui, system, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "has_artifacts", "in": "query", "description": "Filter runs by artifact existence", "required": false, "schema": { "type": "boolean" } }, { "name": "started_after", "in": "query", "description": "Filter runs started at/after RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "started_before", "in": "query", "description": "Filter runs started at/before RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across execution_id, status, source, run_name, output, metadata", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Runs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentRunEvent" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_run", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunRequest" } ] } } } }, "responses": { "200": { "description": "Run completed (always_on deployments)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunInvocationResponse" } } } }, "202": { "description": "Run triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunInvocationResponse" } } } }, "402": { "description": "Insufficient SerenBucks balance" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single run event for a deployment.", "operationId": "seren_cloud_deployment_run", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run event details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/artifacts": { "get": { "tags": [ "seren-cloud" ], "summary": "List artifacts emitted by a specific deployment run.", "operationId": "seren_cloud_deployment_run_artifacts", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max artifacts to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Run artifacts listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentRunArtifact" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/cancel": { "post": { "tags": [ "seren-cloud" ], "summary": "Cancel a queued/running deployment run.", "operationId": "seren_cloud_deployment_run_cancel", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancellation requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/evals": { "get": { "tags": [ "seren-cloud" ], "summary": "List eval records linked to a specific deployment run.", "operationId": "seren_cloud_deployment_run_evals", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval records linked to the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunEvalsResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/events": { "get": { "tags": [ "seren-cloud" ], "summary": "List structured output events emitted by a specific deployment run.", "operationId": "seren_cloud_deployment_run_events", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max events to return (default: 100, max: 500)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "kind", "in": "query", "description": "Filter by event kind (text, thinking, tool_call_started, tool_call_completed, tool_audit, workflow, error, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "description": "Filter by tool/output item ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across event type, kind, item ID, and payload", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run output events listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudRunOutputEventEnvelope" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/pending_approvals": { "get": { "tags": [ "seren-cloud" ], "summary": "List current pending approvals for a specific deployment run.", "operationId": "seren_cloud_deployment_run_pending_approvals", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current pending approvals for the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunPendingApprovalsResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/resume": { "post": { "tags": [ "seren-cloud" ], "summary": "Resume the exact managed deployment run that owns a durable checkpoint.", "operationId": "seren_cloud_deployment_run_resume", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunResumeRequest" } ] } } } }, "responses": { "200": { "description": "Run resumed and recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "400": { "description": "Malformed resume request or runtime rejected the request before execution" }, "404": { "description": "Not found" }, "409": { "description": "Run does not require durable resume" }, "503": { "description": "Deployment could not be woken for resume" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/state": { "get": { "tags": [ "seren-cloud" ], "summary": "Get the current operational state for a deployment run.", "operationId": "seren_cloud_deployment_run_state", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current run state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunLiveState" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/runs/{run_id}/stream": { "get": { "tags": [ "seren-cloud" ], "summary": "Stream a deployment run's events as a sequenced, resumable Server-Sent Events log.", "description": "Replays run events from the client's cursor (Last-Event-ID = highest sequence already seen), emits `run.state` and `replay_complete` control frames, then tails live events. Each `run.event` frame's `id` is its monotonic sequence number, so an EventSource resumes from the last received id after a disconnect. Multiple subscribers per run are allowed.", "operationId": "seren_cloud_deployment_run_stream", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Last-Event-ID", "in": "header", "description": "Highest event sequence number already received; replay resumes after it.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "SSE stream of sequenced run events", "content": { "text/event-stream": {} } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/schedules": { "get": { "tags": [ "seren-cloud" ], "summary": "List agent-owned future run schedules for a deployment.", "operationId": "seren_cloud_list_agent_schedules", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max schedules to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Agent schedules listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentAgentSchedule" } } } }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "summary": "Create or update an agent-owned future run schedule.", "operationId": "seren_cloud_create_agent_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudDeploymentAgentScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent schedule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentAgentSchedule" } } } }, "400": { "description": "Invalid schedule request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/schedules/{schedule_id}": { "delete": { "tags": [ "seren-cloud" ], "summary": "Cancel an active agent-owned future run schedule.", "operationId": "seren_cloud_cancel_agent_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent schedule cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentAgentSchedule" } } } }, "404": { "description": "Deployment not found" }, "409": { "description": "Schedule is not active" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/secret-refs/preview": { "post": { "tags": [ "seren-cloud" ], "summary": "Preview the complete employee secret reference set without mutating the deployment.", "operationId": "seren_cloud_preview_managed_employee_secret_refs", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewManagedEmployeeSecretRefsRequest" } } }, "required": true }, "responses": { "200": { "description": "Complete secret reference set for delegation signing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedEmployeeSecretRefsPreview" } } } }, "400": { "description": "Invalid employee secret references" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/sessions": { "get": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_interactive_sessions", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max sessions to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Session pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "message_limit", "in": "query", "description": "Max messages returned per session (default: 200, max: 500)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "message_offset", "in": "query", "description": "Message pagination offset per session", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "message_order", "in": "query", "description": "Message page order, asc or desc (default: asc)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interactive sessions listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudInteractiveSessionDetailResponse" } } } }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_create_interactive_session", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudInteractiveSessionOpenRequest" } ] } } } }, "responses": { "201": { "description": "Interactive session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudInteractiveSessionOpenResponse" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/sessions/{session_id}": { "get": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_get_interactive_session", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "description": "Interactive session ID or durable conversation ID", "required": true, "schema": { "type": "string" } }, { "name": "message_limit", "in": "query", "description": "Max messages returned (default: 200, max: 500)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "message_offset", "in": "query", "description": "Message pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "message_order", "in": "query", "description": "Message page order, asc or desc (default: asc)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interactive session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudInteractiveSessionDetailResponse" } } } }, "404": { "description": "Deployment or session not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/sessions/{session_id}/messages": { "post": { "tags": [ "seren-cloud" ], "operationId": "seren_cloud_post_interactive_session_message", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "description": "Interactive session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudInteractiveSessionMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Duplicate interactive session message replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudInteractiveSessionMessageResponse" } } } }, "202": { "description": "Interactive session message accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudInteractiveSessionMessageResponse" } } } }, "409": { "description": "Interactive session is closed or idempotency conflict" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/spend": { "get": { "tags": [ "seren-cloud" ], "summary": "Run a one-shot invocation of a deployment.", "operationId": "seren_cloud_get_deployment_spend", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Aggregated spend summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_DeploymentSpendSummary" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/start": { "post": { "tags": [ "seren-cloud" ], "summary": "Start an always-on deployment (scale to 1 replica).", "operationId": "seren_cloud_start", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "400": { "description": "Bad request (not always_on)" }, "402": { "description": "Insufficient SerenBucks balance" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/stop": { "post": { "tags": [ "seren-cloud" ], "summary": "Stop an always-on deployment (scale to 0 replicas).", "operationId": "seren_cloud_stop", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "400": { "description": "Bad request (not always_on)" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/deployments/{id}/storage": { "get": { "tags": [ "seren-cloud" ], "summary": "Get the storage attachment for a managed agent.", "operationId": "seren_cloud_get_storage", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed agent storage attachment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedStorageAttachment" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment or storage attachment not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "seren-cloud" ], "summary": "Attach an organization storage bucket to a managed agent and optionally\nkeep its workspace portable across runtime restarts.", "operationId": "seren_cloud_attach_storage", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachManagedStorageRequest" } } }, "required": true }, "responses": { "200": { "description": "Storage attached to the managed agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedStorageAttachment" } } } }, "400": { "description": "Invalid storage attachment" }, "403": { "description": "Deployment or organization storage management permission required" }, "404": { "description": "Deployment or storage bucket not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-cloud" ], "summary": "Detach organization storage from a managed agent and revoke its bucket\ngrant.", "operationId": "seren_cloud_detach_storage", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Storage detached from the managed agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "403": { "description": "Deployment or organization storage management permission required" }, "404": { "description": "Deployment or storage attachment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/environments": { "get": { "tags": [ "seren-cloud" ], "summary": "List reusable execution environment profiles.", "operationId": "seren_cloud_list_environments", "responses": { "200": { "description": "Environments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentEnvironment" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "summary": "Create a reusable execution environment profile.", "operationId": "seren_cloud_create_environment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudDeploymentEnvironmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Environment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentEnvironment" } } } }, "400": { "description": "Bad request" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/environments/{id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a reusable execution environment profile.", "operationId": "seren_cloud_get_environment", "parameters": [ { "name": "id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Environment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentEnvironment" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "seren-cloud" ], "summary": "Delete a reusable execution environment profile.", "operationId": "seren_cloud_delete_environment", "parameters": [ { "name": "id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Environment deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-cloud" ], "summary": "Update a reusable execution environment profile.", "operationId": "seren_cloud_update_environment", "parameters": [ { "name": "id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCloudDeploymentEnvironmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Environment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentEnvironment" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets": { "get": { "tags": [ "seren-cloud" ], "summary": "List eval sets for the authenticated organization.", "operationId": "seren_cloud_eval_sets", "parameters": [ { "name": "deployment_id", "in": "query", "description": "Optional deployment scope", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max eval sets to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Eval sets listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudEvalSet" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "summary": "Create a durable eval set for seren-cloud runs.", "operationId": "seren_cloud_create_eval_set", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudEvalSetRequest" } } }, "required": true }, "responses": { "201": { "description": "Eval set created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalSet" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single eval set.", "operationId": "seren_cloud_get_eval_set", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval set details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalSet" } } } }, "404": { "description": "Eval set not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "seren-cloud" ], "summary": "Replace an eval set definition, including schedule and criteria.", "operationId": "seren_cloud_update_eval_set", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCloudEvalSetRequest" } } }, "required": true }, "responses": { "200": { "description": "Eval set updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalSet" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Eval set or deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/cases": { "get": { "tags": [ "seren-cloud" ], "summary": "List eval cases within a set.", "operationId": "seren_cloud_eval_cases", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max eval cases to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Eval cases listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudEvalCase" } } } }, "404": { "description": "Eval set not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/cases/from-run/{run_id}": { "post": { "tags": [ "seren-cloud" ], "summary": "Promote a terminal run into a durable eval case.", "operationId": "seren_cloud_promote_run_to_eval_case", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Source run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteRunToCloudEvalCaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Eval case created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalCase" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Eval set or run not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/cases/{case_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single eval case.", "operationId": "seren_cloud_get_eval_case", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "Eval case ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval case details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalCase" } } } }, "404": { "description": "Eval case not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/runs": { "get": { "tags": [ "seren-cloud" ], "summary": "List eval runs within a set.", "operationId": "seren_cloud_eval_runs", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max eval runs to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Eval runs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudEvalRun" } } } }, "404": { "description": "Eval set not found" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "seren-cloud" ], "summary": "Execute an eval set against a deployment.", "operationId": "seren_cloud_run_eval_set", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudEvalRunRequest" } } }, "required": true }, "responses": { "202": { "description": "Eval run accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalRun" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Eval set or deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/runs/{run_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single eval run.", "operationId": "seren_cloud_get_eval_run", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Eval run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalRun" } } } }, "404": { "description": "Eval run not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/runs/{run_id}/results": { "get": { "tags": [ "seren-cloud" ], "summary": "List case results for an eval run.", "operationId": "seren_cloud_eval_run_results", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Eval run ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max case results to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Eval case results listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudEvalCaseResult" } } } }, "404": { "description": "Eval run not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/eval-sets/{id}/runs/{run_id}/results/{case_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single case result from an eval run.", "operationId": "seren_cloud_get_eval_case_result", "parameters": [ { "name": "id", "in": "path", "description": "Eval set ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "description": "Eval run ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "Eval case ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval case result details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudEvalCaseResult" } } } }, "404": { "description": "Eval case result not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/inbox/approvals": { "get": { "tags": [ "seren-cloud" ], "summary": "List every awaiting approval the operator owns across all approval kinds.", "description": "Returns `ToolCall` entries (derived from `awaiting_approval` runs) and\n`BlockedEgress` entries (from `blocked_egress_inbox_entries`) merged into\na single timeline ordered by `created_at DESC`. Pagination is cursor-only:\nthe response includes `next_cursor` when more entries are available, and\nthe caller passes it back in `?cursor=`.", "operationId": "seren_cloud_approval_inbox_list", "parameters": [ { "name": "limit", "in": "query", "description": "Max entries per page (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response. Cursors expire after 24h; reject malformed or expired cursors with 400.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approval inbox entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApprovalInboxListResponse" } } } }, "400": { "description": "Malformed limit or cursor" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/inbox/approvals/{entry_id}/decide": { "post": { "tags": [ "seren-cloud" ], "summary": "Record an operator approve/deny decision for a single inbox entry.", "description": "Tool-call entries record an audit row and rely on the existing run-resume\nflow to emit the `approval_decision` event. Blocked-egress entries flip\nthe row's `decision_state` so the runtime wait long-poll releases or\ndrops the corresponding request on its next tick. Re-deciding an\nalready-terminal blocked-egress row returns the current state instead of\n409 so the agent runtime's at-least-once retries are idempotent.", "operationId": "seren_cloud_approval_inbox_decide", "parameters": [ { "name": "entry_id", "in": "path", "description": "Inbox-scoped entry id (e.g. tool::)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalInboxDecisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApprovalInboxDecisionResponse" } } } }, "400": { "description": "Malformed body" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Inbox entry not found" }, "409": { "description": "Entry no longer pending" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/pending_approvals": { "get": { "tags": [ "seren-cloud" ], "summary": "List awaiting-approval runs across all deployments for the organization.", "operationId": "seren_cloud_pending_approvals", "parameters": [ { "name": "limit", "in": "query", "description": "Max runs to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "compute_backend", "in": "query", "description": "Filter by compute backend (aws_container, cloudflare_worker, daytona)", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source (api, cli, scheduler, ui, system, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "has_artifacts", "in": "query", "description": "Filter runs by artifact existence", "required": false, "schema": { "type": "boolean" } }, { "name": "started_after", "in": "query", "description": "Filter runs started at/after RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "started_before", "in": "query", "description": "Filter runs started at/before RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across execution_id, status, source, run_name, output, metadata", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Awaiting-approval runs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudPendingApprovalRun" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs": { "get": { "tags": [ "seren-cloud" ], "summary": "List all runs across all deployments for the organization.", "operationId": "seren_cloud_runs", "parameters": [ { "name": "limit", "in": "query", "description": "Max runs to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "conversation_id", "in": "query", "description": "Filter runs by exact conversation ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Repeat or comma-separate statuses: queued, running, awaiting_approval, completed, failed, cancelled, timeout, blocked, error", "required": false, "schema": { "type": "string" } }, { "name": "compute_backend", "in": "query", "description": "Filter by compute backend (aws_container, cloudflare_worker, daytona)", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source (api, cli, scheduler, ui, system, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "has_artifacts", "in": "query", "description": "Filter runs by artifact existence", "required": false, "schema": { "type": "boolean" } }, { "name": "started_after", "in": "query", "description": "Filter runs started at/after RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "started_before", "in": "query", "description": "Filter runs started at/before RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across execution_id, status, source, run_name, output, metadata", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All runs listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentRunEvent" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Get a single run event by ID (cross-agent).", "operationId": "seren_cloud_run_detail", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run event details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/artifacts": { "get": { "tags": [ "seren-cloud" ], "summary": "List artifacts emitted by a run event.", "operationId": "seren_cloud_run_artifacts", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max artifacts to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Run artifacts listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentRunArtifact" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/audit": { "get": { "tags": [ "seren-cloud" ], "summary": "List tamper-evident audit entries scoped to a run.", "operationId": "seren_cloud_run_audit", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max audit entries to return (default: 50, max: 200)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "action", "in": "query", "description": "Filter by exact audit action", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across action, actor, and details", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run audit entries listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_AuditEntry" } } } }, "404": { "description": "Run event not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/cancel": { "post": { "tags": [ "seren-cloud" ], "summary": "Cancel a queued/running run by ID.", "operationId": "seren_cloud_run_cancel", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancellation requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/compare/{compare_run_id}": { "get": { "tags": [ "seren-cloud" ], "summary": "Compare two run replay/eval captures by ID (cross-agent).", "operationId": "seren_cloud_run_compare", "parameters": [ { "name": "run_id", "in": "path", "description": "Baseline run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "compare_run_id", "in": "path", "description": "Candidate run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replay comparison summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunReplayComparison" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/evals": { "get": { "tags": [ "seren-cloud" ], "summary": "List eval records linked to a run event.", "operationId": "seren_cloud_run_evals", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eval records linked to the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunEvalsResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/events": { "get": { "tags": [ "seren-cloud" ], "summary": "List structured output events emitted by a run event.", "operationId": "seren_cloud_run_events", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max events to return (default: 100, max: 500)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "kind", "in": "query", "description": "Filter by event kind (text, thinking, tool_call_started, tool_call_completed, tool_audit, workflow, error, unknown)", "required": false, "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "description": "Filter by tool/output item ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive search across event type, kind, item ID, and payload", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run output events listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudRunOutputEventEnvelope" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/pending_approvals": { "get": { "tags": [ "seren-cloud" ], "summary": "List current pending approvals for a run event.", "operationId": "seren_cloud_run_pending_approvals", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current pending approvals for the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunPendingApprovalsResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/resume": { "post": { "tags": [ "seren-cloud" ], "summary": "Resume the exact managed run that owns a durable checkpoint.", "operationId": "seren_cloud_run_resume", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunResumeRequest" } ] } } } }, "responses": { "200": { "description": "Run resumed and recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentRunEvent" } } } }, "400": { "description": "Malformed resume request or runtime rejected the request before execution" }, "404": { "description": "Not found" }, "409": { "description": "Run does not require durable resume" }, "503": { "description": "Deployment could not be woken for resume" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/state": { "get": { "tags": [ "seren-cloud" ], "summary": "Get the current operational state for a run event.", "operationId": "seren_cloud_run_state", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current run state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudRunLiveState" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/runs/{run_id}/stream": { "get": { "tags": [ "seren-cloud" ], "summary": "Stream a run's events as a sequenced, resumable Server-Sent Events log.", "description": "Replays run events from the client's cursor (Last-Event-ID = highest sequence already seen), emits `run.state` and `replay_complete` control frames, then tails live events. Each `run.event` frame's `id` is its monotonic sequence number, so an EventSource resumes from the last received id after a disconnect. Multiple subscribers per run are allowed.", "operationId": "seren_cloud_run_stream", "parameters": [ { "name": "run_id", "in": "path", "description": "Run event ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Last-Event-ID", "in": "header", "description": "Highest event sequence number already received; replay resumes after it.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "SSE stream of sequenced run events", "content": { "text/event-stream": {} } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-cloud/storage/buckets": { "get": { "tags": [ "seren-cloud" ], "summary": "List organization storage buckets that can be attached to a managed agent.", "operationId": "seren_cloud_list_storage_buckets", "responses": { "200": { "description": "Organization storage buckets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_ManagedStorageBucket" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "502": { "description": "Storage is temporarily unavailable" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/capabilities": { "get": { "tags": [ "seren-agent" ], "summary": "Inspect available orchestration features and runtime limits.", "operationId": "seren_agent_capabilities", "responses": { "200": { "description": "Capabilities retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AgentCapabilitiesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deploy": { "post": { "tags": [ "seren-agent" ], "summary": "Create or update an orchestrated deployment (forwarded to seren-cloud).", "operationId": "seren_agent_deploy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSpec" } } }, "required": true }, "responses": { "202": { "description": "Deployment accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Deployment could not be initialized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments": { "get": { "tags": [ "seren-agent" ], "summary": "List orchestrated deployments and their runtime metadata.", "operationId": "seren_agent_list_deployments", "responses": { "200": { "description": "Deployments listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_CloudDeploymentSummary" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}": { "delete": { "tags": [ "seren-agent" ], "summary": "Delete a managed seren-agent deployment and clean up runtime resources.", "operationId": "seren_agent_delete_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/activity": { "get": { "tags": [ "seren-agent" ], "summary": "Get recent activity for a managed seren-agent deployment.", "description": "Returns recent managed-agent activity with run status, timing, cost, token, and artifact-count summaries. This endpoint omits prompt, output, and tool payload details; use seren-cloud run-history APIs for full runtime history.", "operationId": "seren_agent_get_deployment_activity", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max run activity entries to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Managed deployment activity retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentActivityReport" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/health": { "get": { "tags": [ "seren-agent" ], "summary": "Get health for a managed seren-agent deployment.", "description": "Returns a managed-agent health projection for a seren-agent deployment. Use seren-cloud deployment APIs for raw runtime state and run history.", "operationId": "seren_agent_get_deployment_health", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment health retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentHealthReport" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed": { "get": { "tags": [ "seren-agent" ], "summary": "Get the resolved managed spec for a seren-agent deployment.", "description": "Returns the resolved managed-agent configuration for a seren-agent deployment. Use seren-cloud deployment APIs for raw runtime operations.", "operationId": "seren_agent_get_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment detail retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentDetail" } } } }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "seren-agent" ], "summary": "Update the editable managed spec for a seren-agent deployment.", "operationId": "seren_agent_update_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSpecUpdate" } } }, "required": true }, "responses": { "200": { "description": "Managed deployment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/files": { "patch": { "tags": [ "seren-agent" ], "summary": "Update files for a managed deployment.", "operationId": "seren_agent_patch_managed_deployment_files", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBundlePatch" } } }, "required": true }, "responses": { "200": { "description": "Managed deployment files updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/preview": { "post": { "tags": [ "seren-agent" ], "summary": "Preview a managed update before applying it.", "operationId": "seren_agent_preview_managed_deployment_update", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSpecUpdate" } } }, "required": true }, "responses": { "200": { "description": "Managed deployment update preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentUpdatePreview" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/revisions": { "get": { "tags": [ "seren-agent" ], "summary": "List immutable revision snapshots for a managed deployment.", "operationId": "seren_agent_list_managed_deployment_revisions", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment revisions listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_ManagedAgentDeploymentRevisionSummary" } } } }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/rollback": { "post": { "tags": [ "seren-agent" ], "summary": "Roll a managed deployment back to a prior revision.", "operationId": "seren_agent_rollback_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackSerenAgentDeploymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Managed deployment rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentSummary" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment or revision not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/rollback/preview": { "post": { "tags": [ "seren-agent" ], "summary": "Preview rolling a managed deployment back to a prior revision.", "operationId": "seren_agent_preview_managed_deployment_rollback", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackSerenAgentDeploymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Managed deployment rollback preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentRollbackPreview" } } } }, "400": { "description": "Bad request" }, "403": { "description": "Managed deployment is opaque to this caller" }, "404": { "description": "Deployment or revision not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/runtime-policy-reconciliation": { "post": { "tags": [ "seren-agent" ], "summary": "Apply an eligible runtime-policy reconciliation as a normal managed\ndeployment revision.", "operationId": "seren_agent_apply_runtime_policy_reconciliation", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Runtime-policy reconciliation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentRuntimePolicyReconciliationResult" } } } }, "400": { "description": "Deployment is not eligible" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" }, "409": { "description": "Stored timeout conflicts with the declared policy" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/managed/runtime-policy-reconciliation/preview": { "post": { "tags": [ "seren-agent" ], "summary": "Preview safe reconciliation for a deployment created before canonical\nruntime-policy deadline metadata.", "operationId": "seren_agent_preview_runtime_policy_reconciliation", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Runtime-policy reconciliation preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentRuntimePolicyReconciliationPreview" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/resources": { "get": { "tags": [ "seren-agent" ], "summary": "Get platform resources available to a managed seren-agent deployment.", "description": "Returns a managed-agent resource summary. This endpoint is a managed-agent projection; use seren-cloud deployment APIs for full runtime operations.", "operationId": "seren_agent_get_deployment_resources", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment resources retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentDeploymentResources" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/start": { "post": { "tags": [ "seren-agent" ], "summary": "Start a managed seren-agent deployment.", "operationId": "seren_agent_start_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/stop": { "post": { "tags": [ "seren-agent" ], "summary": "Stop a managed seren-agent deployment.", "operationId": "seren_agent_stop_managed_deployment", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CloudDeploymentActionStatusResponse" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/tool-groups": { "get": { "tags": [ "seren-agent" ], "summary": "List tool groups currently assigned to a managed seren-agent deployment.", "description": "Returns the resolved tool-group read model for a managed seren-agent deployment. Today these groups are derived from the deployment's tool_presets config inputs; future explicit tool-group assignments will use the same response shape.", "operationId": "seren_agent_list_deployment_tool_groups", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed deployment tool groups retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentToolGroupResponse" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/tools": { "get": { "tags": [ "seren-agent" ], "summary": "List tools currently visible to a managed seren-agent deployment.", "description": "Returns the declared tool catalog for a managed seren-agent deployment, including source, approval, and side-effect metadata. This endpoint is a managed-agent projection; use seren-cloud run APIs for runtime execution.", "operationId": "seren_agent_list_deployment_tools", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "description": "Optional case-insensitive search over tool names, descriptions, and sources", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed deployment tool catalog retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentToolCatalogResponse" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/deployments/{id}/tools/{tool_name}": { "get": { "tags": [ "seren-agent" ], "summary": "Describe one tool currently visible to a managed seren-agent deployment.", "description": "Returns one declared tool descriptor for a managed seren-agent deployment, including source, approval, and side-effect metadata. This endpoint is a managed-agent projection; use seren-cloud run APIs for runtime execution.", "operationId": "seren_agent_describe_deployment_tool", "parameters": [ { "name": "id", "in": "path", "description": "Deployment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tool_name", "in": "path", "description": "Tool name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed deployment tool descriptor retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentToolCatalogEntry" } } } }, "400": { "description": "Deployment is not managed by seren-agent" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Deployment or tool not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/health": { "get": { "tags": [ "seren-agent" ], "summary": "Get organization-level health for managed seren-agent deployments.", "description": "Returns an organization-level managed-agent health projection. Use seren-cloud deployment APIs for raw runtime state and run history.", "operationId": "seren_agent_health", "responses": { "200": { "description": "Managed agent health retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ManagedAgentHealthReport" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/private-models": { "get": { "tags": [ "seren-agent" ], "summary": "List the private model catalog available through seren-private-models.", "operationId": "seren_agent_private_models", "parameters": [ { "name": "region", "in": "query", "description": "Optional private model region for live discovery. Defaults to us-east-1.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private model catalog retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PrivateModelCatalogResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-agent/test-run": { "post": { "tags": [ "seren-agent" ], "summary": "Run an unsaved managed seren-agent draft once before deploying.", "operationId": "seren_agent_test_run", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSerenAgentDraftRunRequest" } } }, "required": true }, "responses": { "200": { "description": "Draft test run completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_TestSerenAgentDraftRunResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Draft runtime could not be initialized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-models/chat/completions": { "post": { "tags": [ "publishers" ], "operationId": "seren_models_chat_completions", "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Publisher chat completion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiResultResponse" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Payment required" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-private-models/chat/completions": { "post": { "tags": [ "publishers" ], "operationId": "post_chat_completions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateModelsChatCompletionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Publisher chat completion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ApiResultResponse" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Private models are not configured for this organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-private-models/models": { "get": { "tags": [ "publishers" ], "operationId": "get_private_models", "responses": { "200": { "description": "Available private models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PrivateModelsListResponse" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Private models are not configured for this organization" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-passwords/account": { "put": { "tags": [ "Account" ], "summary": "Set up the caller's account in the org vault database.", "description": "The first call creates the user's identity, seeds the account_secrets row,\nand provisions the default Personal vault in one transaction. If the\naccount is already initialized, the endpoint returns the existing setup\nstate and does not overwrite any key material.", "operationId": "account_setup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSetupRequest" } } }, "required": true }, "responses": { "200": { "description": "Account setup state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAccountSetup" } } } }, "400": { "description": "Malformed setup body" }, "403": { "description": "Agents may not set up user accounts" }, "409": { "description": "Partial existing state; refusing to overwrite" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/account/recovery/complete": { "post": { "tags": [ "Account" ], "summary": "Complete account recovery: replace account_secrets with a freshly wrapped\nblob and rotate the recovery key.", "description": "Verifies the recovery proof signature over the open challenge plus the\nnew KEM public key, and rejects completions that reuse the existing\nrecovery_key_wrap or recovery_kdf_params (so a leaked recovery sheet must\nalso be retired).", "operationId": "account_recovery_complete", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCompleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated account secrets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAccountSecretsRecord" } } } }, "400": { "description": "Recovery blob attempted to rotate identity keys, or recovery key was not rotated" }, "401": { "description": "Invalid recovery proof" }, "403": { "description": "Agents may not complete account recovery" }, "404": { "description": "No active identity or matching recovery request" }, "409": { "description": "Recovery request was consumed or expired during verification" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/account/recovery/initiate": { "post": { "tags": [ "Account" ], "summary": "Open an account recovery request and receive a random challenge.", "description": "The client signs the challenge plus the new KEM public key in\n`/account/recovery/complete` to prove possession of the existing account\nsigning key (recovered using the recovery key).", "operationId": "account_recovery_initiate", "responses": { "200": { "description": "Recovery challenge issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseRecoveryInitiate" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agents may not initiate account recovery" }, "404": { "description": "No active identity for this user" } } } }, "/publishers/seren-passwords/account/secrets": { "get": { "tags": [ "Account" ], "summary": "Fetch the caller's opaque account_secrets blob.", "description": "Returns the wrapped account, KEM, signing, and recovery keys; the server\nstores them only as ciphertext. A 404 here means the user has not yet\nset up an account in this org's vault database - the client should call\n`PUT /account` to do that.", "operationId": "account_get_secrets", "responses": { "200": { "description": "Account secrets blob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAccountSecretsRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Account not initialized in this org yet" } } }, "put": { "tags": [ "Account" ], "summary": "Rotate the caller's wrapped account secrets.", "description": "Requires an existing account and an Ed25519 update proof produced by the\ncurrent account signing key. First-time setup belongs on `PUT /account`;\nthis endpoint never creates identities or vault memberships.", "operationId": "account_update_secrets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSecretsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated account secrets blob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAccountSecretsRecord" } } } }, "400": { "description": "Malformed body or timestamp outside the freshness window" }, "401": { "description": "Invalid account-secrets update proof" }, "403": { "description": "Agents may not update account secrets" }, "404": { "description": "Account is not initialized in this org" }, "409": { "description": "Partial existing state, or a stale/replayed update proof" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/approvals": { "get": { "tags": [ "Approvals" ], "summary": "List pending approval requests visible to the caller.", "operationId": "approval_list_pending", "responses": { "200": { "description": "Pending approvals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApprovalRecordList" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Caller has no active account identity" } } }, "post": { "tags": [ "Approvals" ], "summary": "Open an approval request for an item or vault target.", "operationId": "approval_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "Created approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApprovalRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have visibility into the target vault" }, "404": { "description": "Target item or vault not found" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/approvals/{approval_id}": { "get": { "tags": [ "Approvals" ], "summary": "Fetch one approval by id. The one-shot wrapped key is scrubbed unless the\ncaller is the requester.", "operationId": "approval_get", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApprovalRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Approval not found" } } } }, "/publishers/seren-passwords/approvals/{approval_id}/approve": { "post": { "tags": [ "Approvals" ], "summary": "Approve a pending approval request and supply the one-shot wrapped key.", "operationId": "approval_approve", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApprovalRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of the target vault" }, "404": { "description": "Approval or target not found" }, "409": { "description": "Approval is no longer pending" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/approvals/{approval_id}/approve-context": { "get": { "tags": [ "Approvals" ], "operationId": "approval_approve_context", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Material needed to construct the one_shot_wrapped_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApproveContext" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of the target vault" }, "404": { "description": "Approval, target, or requester identity not found" } } } }, "/publishers/seren-passwords/approvals/{approval_id}/deny": { "post": { "tags": [ "Approvals" ], "summary": "Deny a pending approval request.", "operationId": "approval_deny", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseApprovalRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of the target vault" }, "404": { "description": "Approval or target not found" }, "409": { "description": "Approval is no longer pending" } } } }, "/publishers/seren-passwords/approvals/{approval_id}/wait": { "get": { "tags": [ "Approvals" ], "summary": "Stream approval state changes over SSE until the request decides or the\nserver-side wait window elapses. Only the requester may wait.", "operationId": "approval_wait", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Server-sent events stream", "content": { "text/event-stream": {} } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only the requester may wait on this approval" }, "404": { "description": "Approval not found" } } } }, "/publishers/seren-passwords/audit/events": { "get": { "tags": [ "Audit" ], "summary": "List audit log entries visible to the caller, filtered by actor, action,\ntarget, and time window.", "operationId": "audit_event_list", "parameters": [ { "name": "actor_identity_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "target_kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "target_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Audit log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAuditLogEntryList" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Caller has no active account identity" } } } }, "/publishers/seren-passwords/audit/verify": { "get": { "tags": [ "Audit" ], "summary": "Verify the audit log hash chain for this organization database.", "description": "The result proves current chain consistency. It does not provide external\nanchoring or per-row non-repudiation.", "operationId": "audit_chain_verify", "responses": { "200": { "description": "Audit hash-chain verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAuditChainVerifyResult" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may verify audit chain" } } } }, "/publishers/seren-passwords/delegations": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_request_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDelegationRequest" } } }, "required": true }, "responses": { "200": { "description": "Created delegation request and one-time consent capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestCreated" } } } }, "400": { "description": "Invalid public key or display name" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user callers may create delegation requests" }, "422": { "description": "Request body failed validation" }, "503": { "description": "Consent capability signing is not configured" } } } }, "/publishers/seren-passwords/delegations/approve": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_consent_approve", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveDelegationConsentRequest" } } }, "required": true }, "responses": { "200": { "description": "Approved cross-user or cross-organization delegation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestRecord" } } } }, "400": { "description": "Malformed grants, unsupported cross-organization admin access, or invalid signatures" }, "401": { "description": "Human user authentication required" }, "403": { "description": "Caller is not an admin of every selected vault" }, "404": { "description": "Consent capability is invalid" }, "409": { "description": "Consent retry does not match the claimed approval" }, "410": { "description": "Consent capability is expired or already used" }, "422": { "description": "Request body failed validation" }, "423": { "description": "A selected vault is rotating" } } } }, "/publishers/seren-passwords/delegations/consent": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_consent_read", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationConsentCapabilityRequest" } } }, "required": true }, "responses": { "200": { "description": "Minimum public metadata for a valid pending consent capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationConsentView" } } } }, "401": { "description": "Human user authentication required" }, "404": { "description": "Consent capability is invalid" }, "410": { "description": "Consent capability is expired or already used" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/delegations/deny": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_consent_deny", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationConsentCapabilityRequest" } } }, "required": true }, "responses": { "200": { "description": "Denied delegation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestRecord" } } } }, "401": { "description": "Human user authentication required" }, "404": { "description": "Consent capability is invalid" }, "410": { "description": "Consent capability is expired, claimed, or already used" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/delegations/{request_id}": { "get": { "tags": [ "Delegations" ], "operationId": "delegation_request_get", "parameters": [ { "name": "request_id", "in": "path", "description": "Delegation request id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delegation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user callers may read delegation requests" }, "404": { "description": "Delegation request not found" } } } }, "/publishers/seren-passwords/delegations/{request_id}/approve": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_request_approve", "parameters": [ { "name": "request_id", "in": "path", "description": "Delegation request id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveDelegationRequest" } } }, "required": true }, "responses": { "200": { "description": "Approved delegation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestRecord" } } } }, "400": { "description": "Invalid approval request" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not authorized to approve" }, "404": { "description": "Delegation request not found" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/delegations/{request_id}/deny": { "post": { "tags": [ "Delegations" ], "operationId": "delegation_request_deny", "parameters": [ { "name": "request_id", "in": "path", "description": "Delegation request id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Denied delegation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseDelegationRequestRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user callers may deny delegation requests" }, "404": { "description": "Delegation request not found" } } } }, "/publishers/seren-passwords/identities": { "get": { "tags": [ "Identities" ], "summary": "List active identities visible to the caller (org-scoped).", "operationId": "identity_list", "responses": { "200": { "description": "Identities in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecordList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agent callers may not enumerate identities" } } } }, "/publishers/seren-passwords/identities/agents": { "get": { "tags": [ "Identities" ], "summary": "List the calling user's owned, active agent identities, each with the\nvaults that agent currently has access to. Powers `seren passwords agent\nlist`. Returns only public key material and grant metadata; no wrapped key\nmaterial ever appears in the response.", "operationId": "agent_identity_list", "responses": { "200": { "description": "Owned agent identities and their vault grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAgentSummaryList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may list agents" } } }, "post": { "tags": [ "Identities" ], "summary": "Create an agent identity owned by the calling user. The server verifies\nan Ed25519 signature over the canonical request bytes before persisting\nthe new identity; the signature itself is not stored in the audit row.", "operationId": "agent_identity_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentIdentityRequest" } } }, "required": true }, "responses": { "200": { "description": "Newly created agent identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecord" } } } }, "400": { "description": "Malformed body, canonical signature payload, or signature verification failure" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may create agents" }, "404": { "description": "Caller has no active account identity" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/identities/agents/freeze": { "post": { "tags": [ "Identities" ], "summary": "Revoke every active agent identity owned by the calling user.", "operationId": "agent_identity_freeze", "responses": { "200": { "description": "Owned active agent identities revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAgentFreeze" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may freeze agents" }, "404": { "description": "Caller has no active account identity" } } } }, "/publishers/seren-passwords/identities/agents/hosted": { "post": { "tags": [ "Identities" ], "summary": "Create a hosted agent identity owned by the calling user. The server\ngenerates the agent keypairs and stores only KMS-wrapped private-key\nenvelopes. The user signs the creation intent before the server persists\nanything.", "operationId": "agent_identity_create_hosted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedAgentIdentityRequest" } } }, "required": true }, "responses": { "200": { "description": "Newly created hosted agent identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecord" } } } }, "400": { "description": "Malformed body, canonical signature payload, signature verification failure, or hosted-agent KMS unavailable" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may create agents" }, "404": { "description": "Caller has no active account identity" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/identities/agents/hosted/ensure": { "post": { "tags": [ "Identities" ], "summary": "Return the active hosted agent identity for a user-defined provenance\ncontext, creating it when absent.", "operationId": "agent_identity_ensure_hosted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedAgentIdentityRequest" } } }, "required": true }, "responses": { "200": { "description": "Existing or newly created hosted agent identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecord" } } } }, "400": { "description": "Malformed body, missing provenance context, canonical signature payload, signature verification failure, or hosted-agent KMS unavailable" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may ensure agents" }, "404": { "description": "Caller has no active account identity" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/identities/me": { "get": { "tags": [ "Identities" ], "summary": "Fetch the effective active identity for the caller. Agent callers receive\ntheir agent identity, hosted API-key callers receive the hosted identity\nbound to that key, and browser user sessions receive the user identity.", "operationId": "identity_get_me", "responses": { "200": { "description": "Caller's active identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Agent identity not found, revoked, or user has no active account identity" } } } }, "/publishers/seren-passwords/identities/{identity_id}": { "get": { "tags": [ "Identities" ], "summary": "Fetch a single identity by id.", "operationId": "identity_get", "parameters": [ { "name": "identity_id", "in": "path", "description": "Identity id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Identity record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseIdentityRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agent callers may not look up other identities" }, "404": { "description": "Identity not found" } } } }, "/publishers/seren-passwords/identities/{identity_id}/revoke": { "post": { "tags": [ "Identities" ], "summary": "Revoke an identity owned by the calling user.", "description": "Soft-revocation: the identity stays in the directory for audit reasons\nbut is rejected on subsequent authenticated calls and access checks.", "operationId": "identity_revoke", "parameters": [ { "name": "identity_id", "in": "path", "description": "Identity id to revoke", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not own the target identity" }, "404": { "description": "Identity not found" } } } }, "/publishers/seren-passwords/invitations/pending": { "get": { "tags": [ "Invitations" ], "summary": "List invitations the caller has issued that are awaiting a vault-key\nre-wrap on the inviter side.", "operationId": "invitation_list_pending", "responses": { "200": { "description": "Pending invitations awaiting wrap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseInvitationViewList" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Caller has no active account identity" } } } }, "/publishers/seren-passwords/invitations/redeem": { "post": { "tags": [ "Invitations" ], "summary": "Redeem an invitation token. The caller becomes the awaited identity that\nthe inviter then re-wraps the vault key for.", "operationId": "invitation_redeem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemRequest" } } }, "required": true }, "responses": { "200": { "description": "Redeemed invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseInvitationView" } } } }, "400": { "description": "Missing or malformed invitation_token" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agents may not redeem invitations" }, "404": { "description": "Token does not match any active invitation" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/invitations/{invitation_id}/complete": { "post": { "tags": [ "Invitations" ], "summary": "Complete a redeemed invitation by storing the vault key wrapped for the\nrecipient identity. Same-org recipients become local memberships; cross-org\nrecipients become owner-side foreign memberships plus a recipient discovery\npointer.", "operationId": "invitation_complete", "parameters": [ { "name": "invitation_id", "in": "path", "description": "Invitation id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "Completed membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseMembershipRecord" } } } }, "400": { "description": "Malformed request or grant signature" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Invitation not found" }, "409": { "description": "Recipient already has an active membership" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "Return the live OpenAPI 3.1 document for this service. Body is the raw\ndocument (not wrapped in `DataResponse`) so it can be fed directly into\noff-the-shelf code generators that expect a vanilla OpenAPI payload.", "operationId": "openapi_get", "responses": { "200": { "description": "OpenAPI 3.1 document for this service", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ {} ] } }, "/publishers/seren-passwords/resolve": { "post": { "tags": [ "Resolve" ], "summary": "Resolve a single `seren-secrets://...` reference. The request signature is\nverified against the caller identity's signing key; resolution gates on\nvault membership and the approval policy.", "operationId": "resolve_secret", "parameters": [ { "name": "X-Seren-Correlation-Id", "in": "header", "description": "Optional invocation correlation id for audit lineage", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "Wrapped material for the referenced field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseResolve" } } } }, "400": { "description": "Malformed uri or signature outside the freshness window" }, "401": { "description": "Invalid resolve signature or caller revoked" }, "403": { "description": "Approval required; see error.approval_request_id" }, "404": { "description": "Vault or item not found" }, "409": { "description": "No wrapped vault key available for the caller" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Resolve read rate limit exceeded" } } } }, "/publishers/seren-passwords/resolve/batch": { "post": { "tags": [ "Resolve" ], "summary": "Resolve a batch of references in one round-trip. Each entry is signed and\naudited independently; per-entry failures surface in the result list\nrather than failing the whole batch.", "operationId": "resolve_batch", "parameters": [ { "name": "X-Seren-Correlation-Id", "in": "header", "description": "Optional invocation correlation id for audit lineage", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "Per-entry resolve results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseBatchResolve" } } } }, "400": { "description": "Batch is empty or exceeds the per-call cap" }, "401": { "description": "Caller is not authenticated" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Resolve read rate limit exceeded" } } } }, "/publishers/seren-passwords/secrets-gateway/delegation-config": { "get": { "tags": [ "Secrets Gateway" ], "operationId": "secrets_gateway_delegation_config", "responses": { "200": { "description": "GrantDelegate metadata for client-signed secret resolution delegations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseSecretsGatewayDelegationConfig" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Secret gateway material issuer is not configured" } } } }, "/publishers/seren-passwords/shares": { "post": { "tags": [ "Shares" ], "summary": "Create a live item share. If recipient key material is supplied the share\nis immediately active; otherwise the returned signed token lets the\nrecipient claim it later.", "operationId": "share_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareRequest" } } }, "required": true }, "responses": { "200": { "description": "Created live share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseLiveShareCreated" } } } }, "400": { "description": "Malformed request or share tokens unavailable" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access to the vault" }, "404": { "description": "Vault or item not found" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/shares/claim": { "post": { "tags": [ "Shares" ], "summary": "Claim a live share token into the caller's current password DB.", "operationId": "share_claim", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimLiveShareRequest" } } }, "required": true }, "responses": { "200": { "description": "Claimed live share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseLiveShareView" } } } }, "400": { "description": "Malformed token or request" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agents may not claim shares" }, "404": { "description": "Share not found or not claimable" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/outbound": { "get": { "tags": [ "Shares" ], "summary": "List outbound shares rooted in the caller's current organization.", "operationId": "share_list_outbound", "parameters": [ { "name": "vault_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Outbound live shares", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseLiveShareViewList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agent callers cannot list outbound shares" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/received": { "get": { "tags": [ "Shares" ], "summary": "List live shares claimed by the caller in the current password database.", "operationId": "share_list_received", "responses": { "200": { "description": "Received live shares", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseReceivedShareViewList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agent callers cannot read human received-share inboxes" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/recipients/lookup": { "post": { "tags": [ "Shares" ], "operationId": "share_recipient_lookup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRecipientLookupRequest" } } }, "required": true }, "responses": { "200": { "description": "Verified recipient public key lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseShareRecipientLookup" } } } }, "400": { "description": "Malformed request or invalid email" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agents cannot look up share recipients" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/{share_id}": { "get": { "tags": [ "Shares" ], "summary": "Read a live shared item through the recipient-local pointer.", "operationId": "share_get", "parameters": [ { "name": "share_id", "in": "path", "description": "Share id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Shared encrypted item plus wrapped item key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseSharedItemView" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Share not found, revoked, or not addressed to the caller" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/{share_id}/complete": { "post": { "tags": [ "Shares" ], "summary": "Complete a recipient-claimed email share by adding the sender-wrapped\nitem content key.", "operationId": "share_complete", "parameters": [ { "name": "share_id", "in": "path", "description": "Share id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteLiveShareRequest" } } }, "required": true }, "responses": { "200": { "description": "Completed live share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseLiveShareView" } } } }, "400": { "description": "Malformed request" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Agent callers cannot complete shares" }, "404": { "description": "Share not found or not ready" }, "422": { "description": "Request body failed validation" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/shares/{share_id}/revoke": { "post": { "tags": [ "Shares" ], "summary": "Revoke a live share. The recipient-local pointer may remain until the\nrecipient next syncs, but live reads re-check the owner DB and fail.", "operationId": "share_revoke", "parameters": [ { "name": "share_id", "in": "path", "description": "Share id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked live share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseLiveShareView" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Share not found or caller cannot revoke it" }, "429": { "description": "Shared-item read rate limit exceeded" } } } }, "/publishers/seren-passwords/sync": { "get": { "tags": [ "Sync" ], "summary": "Aggregate read used by clients on cold start: identities, vaults,\nmemberships, item overviews, and the server's clock. Item bodies\n(content ciphertexts) are intentionally excluded; clients fetch them\non demand via `GET /vaults/{vault_id}/items/{item_id}` or `/resolve`.", "operationId": "sync_get", "responses": { "200": { "description": "Aggregate sync payload. Item entries are summaries only; content ciphertexts are not included and must be fetched on demand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseSync" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Caller has no active account identity" } } } }, "/publishers/seren-passwords/vaults": { "get": { "tags": [ "Vaults" ], "summary": "List vaults the caller is an active member of, each with the caller's\nwrapped vault key inlined.", "operationId": "vault_list", "responses": { "200": { "description": "Vaults visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseVaultRecordList" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "User has no active account identity" } } }, "post": { "tags": [ "Vaults" ], "summary": "Create a new vault and seed an admin membership for the creator with the\nsupplied wrapped vault key.", "operationId": "vault_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVaultRequest" } } }, "required": true }, "responses": { "200": { "description": "Newly created vault", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseVaultRecord" } } } }, "400": { "description": "Body fails validation (e.g. org vault requires admin seed)" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Only user identities may create vaults" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}": { "get": { "tags": [ "Vaults" ], "summary": "Fetch a single vault by id (only visible to active members).", "operationId": "vault_get", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vault record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseVaultRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Vault not found or caller is not a member" } } }, "delete": { "tags": [ "Vaults" ], "summary": "Soft-archive a vault. Requires admin membership.", "operationId": "vault_archive", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" } } }, "patch": { "tags": [ "Vaults" ], "summary": "Update encrypted vault display metadata. Requires admin membership.", "operationId": "vault_update", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultPatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "400": { "description": "Body missing both name and description" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/foreign-memberships/{recipient_organization_id}/{recipient_identity_id}": { "delete": { "tags": [ "Memberships" ], "summary": "Revoke a cross-organization member's access to a vault. Requires admin\nmembership in the owner org and updates the recipient-local discovery\npointer after the owner-side revoke commits.", "operationId": "membership_revoke_foreign", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipient_organization_id", "in": "path", "description": "Recipient organization id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipient_identity_id", "in": "path", "description": "Recipient identity id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault or foreign membership not found" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/invitations": { "get": { "tags": [ "Invitations" ], "summary": "List all invitations issued for a vault. Admin only.", "operationId": "invitation_list_for_vault", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vault invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseInvitationViewList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" } } }, "post": { "tags": [ "Invitations" ], "summary": "Mint an out-of-band invitation token for an email address; the response\nechoes the plain token once so the inviter can deliver it out of band.", "operationId": "invitation_create", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "Invitation token (one-shot)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseInvitationCreated" } } } }, "400": { "description": "Malformed request or invitation tokens unavailable" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" }, "409": { "description": "Invitation id or token already exists" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items": { "get": { "tags": [ "Items" ], "summary": "List item summaries in a vault, optionally filtered by lifecycle state,\nblind index, or `updated_since` for delta-sync.", "operationId": "item_list", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "title_blind_index", "in": "query", "description": "Optional base64-encoded blind-index for exact title lookup.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "description": "Lifecycle state to list. Defaults to active. `trashed` returns\nitems in the trash (DELETE'd but not yet hard-deleted); `archived`\nreturns archived items (the existing `archived_at` lifecycle).", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ListStateParam" } ] } }, { "name": "updated_since", "in": "query", "description": "RFC3339 timestamp. When set, only items with `updated_at`\nstrictly greater than this point appear in the result. Delta-sync\ncallers should pass the most recent `updated_at` they have\nalready ingested; the boundary row is excluded so polling does\nnot re-deliver it.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } } ], "responses": { "200": { "description": "Item summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemSummaryList" } } } }, "400": { "description": "Malformed query (e.g. invalid blind index)" }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Vault not found or caller is not a member" } } }, "post": { "tags": [ "Items" ], "summary": "Create an encrypted item in a vault. Requires write membership and is\nblocked while the vault is in `rotating` state. Emits a weak `ETag`\nheader derived from `updated_at` so the client can immediately PATCH\nthe freshly-created row without an extra GET.", "operationId": "item_create", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Created item record", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak ETag derived from updated_at; echo back via If-Match on PATCH" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Vault not found" }, "409": { "description": "wrapping_key_version did not match vault_key_version" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}": { "get": { "tags": [ "Items" ], "summary": "Fetch one item by id. Emits a weak `ETag` header derived from\n`updated_at` for use with `If-Match` on PATCH.", "operationId": "item_get", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Item record", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak ETag derived from updated_at; echo back via If-Match on PATCH" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Approval required; see error.approval_request_id" }, "404": { "description": "Vault or item not found" }, "429": { "description": "Item read rate limit exceeded" } } }, "delete": { "tags": [ "Items" ], "summary": "Trash an item. A second DELETE on a trashed item hard-deletes the row.", "operationId": "item_delete", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Body is `{\"data\":{\"state\":\"trashed\"}}` on the first DELETE against an active item, and `{\"data\":{\"state\":\"hard_deleted\"}}` on a second DELETE against an already-trashed item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Vault or item not found" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } }, "patch": { "tags": [ "Items" ], "summary": "Update an item's ciphertext. Honors `If-Match` for optimistic concurrency\n(412 when stale) and rejects writes during rotation (423).", "operationId": "item_update", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "description": "Weak ETag from a prior GET; rejected with 412 if it does not match updated_at", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated item record", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak ETag derived from the new updated_at" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "400": { "description": "Malformed If-Match header" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Vault or item not found" }, "409": { "description": "wrapping_key_version did not match vault_key_version" }, "412": { "description": "If-Match etag does not match the stored updated_at" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List attachment metadata for an item (without blob bytes).", "operationId": "attachment_list", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAttachmentViewList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Approval required; see error.approval_request_id" }, "404": { "description": "Item or vault not found, or caller has no active account identity" }, "429": { "description": "Attachment read rate limit exceeded" } } }, "post": { "tags": [ "Attachments" ], "summary": "Upload an encrypted attachment blob plus its wrapped content key.", "description": "Requires write membership on the vault and is blocked while the vault is\nin `rotating` state.", "operationId": "attachment_create", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Created attachment metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAttachmentView" } } } }, "400": { "description": "Empty or oversized blob" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Vault or item not found" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments/{attachment_id}": { "get": { "tags": [ "Attachments" ], "summary": "Fetch one attachment with its encrypted blob bytes.", "operationId": "attachment_get", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachment_id", "in": "path", "description": "Attachment id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment with blob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseAttachmentWithBlobView" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Approval required; see error.approval_request_id" }, "404": { "description": "Attachment, item, or vault not found" }, "429": { "description": "Attachment read rate limit exceeded" } } }, "delete": { "tags": [ "Attachments" ], "summary": "Delete an attachment. Requires write membership and is blocked while the\nvault is in `rotating` state.", "operationId": "attachment_delete", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachment_id", "in": "path", "description": "Attachment id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Attachment, item, or vault not found" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/duplicate": { "post": { "tags": [ "Items" ], "summary": "Duplicate an encrypted item. The duplicate receives a new item id; because\nitem ciphertext is AAD-bound to item id, the client supplies ciphertexts\nencrypted for that new id and a content-key wrap sealed under the\ndestination vault key.", "operationId": "item_duplicate", "parameters": [ { "name": "vault_id", "in": "path", "description": "Source vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Source item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Duplicated item record", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak ETag derived from the duplicate updated_at" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "400": { "description": "Malformed duplicate request" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Source or target vault/item not found" }, "409": { "description": "wrapping_key_version did not match target vault_key_version" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Source or target vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/history": { "get": { "tags": [ "Items" ], "summary": "List archived prior content ciphertexts for an item, oldest first.", "operationId": "item_history_list", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "History entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseHistoryEntryList" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Approval required; see error.approval_request_id" }, "404": { "description": "Vault or item not found" }, "429": { "description": "Item read rate limit exceeded" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/move": { "post": { "tags": [ "Items" ], "summary": "Move an encrypted item to another vault. The item id and body ciphertext\nstay stable; the client supplies vault-key-scoped ciphertexts and the\ncontent-key wrap re-sealed under the target vault key.", "operationId": "item_move", "parameters": [ { "name": "vault_id", "in": "path", "description": "Source vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Moved item record", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak ETag derived from the moved item updated_at" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "400": { "description": "Malformed move request" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Source or target vault/item not found" }, "409": { "description": "wrapping_key_version did not match target vault_key_version" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Source or target vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/restore": { "post": { "tags": [ "Items" ], "summary": "Restore a trashed item. Active and archived items return 409.", "operationId": "item_restore", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Restored item record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseItemRecord" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller does not have write access" }, "404": { "description": "Vault or item not found" }, "409": { "description": "Item is already active or is archived" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/memberships": { "get": { "tags": [ "Memberships" ], "summary": "List active memberships for a vault.", "operationId": "membership_list", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Membership list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseMembershipRecordList" } } } }, "401": { "description": "Caller is not authenticated" }, "404": { "description": "Vault not found or caller is not a member" } } }, "post": { "tags": [ "Memberships" ], "summary": "Grant a vault membership to an identity. Requires admin membership on the\nvault and is blocked while the vault is in `rotating` state.", "operationId": "membership_grant", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipGrantRequest" } } }, "required": true }, "responses": { "200": { "description": "Granted membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseMembershipRecord" } } } }, "400": { "description": "granted_signature fails verification" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" }, "409": { "description": "Identity already has an active membership" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/memberships/{identity_id}": { "put": { "tags": [ "Memberships" ], "summary": "Change an active membership's access level atomically. Requires a fresh\ngrant signature from an active vault admin and is blocked during rotation.", "operationId": "membership_update_access", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "identity_id", "in": "path", "description": "Identity whose access level to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipGrantRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseMembershipRecord" } } } }, "400": { "description": "Path identity does not match the body or granted_signature fails verification" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault or active membership not found" }, "409": { "description": "Access is unchanged or the update would remove the final active admin" }, "422": { "description": "Request body failed validation" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } }, "delete": { "tags": [ "Memberships" ], "summary": "Revoke a member's access to a vault. Requires admin membership.", "operationId": "membership_revoke", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "identity_id", "in": "path", "description": "Identity whose membership to revoke", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault or membership not found" }, "409": { "description": "Revocation would remove the final active admin" }, "423": { "description": "Vault is locked due to ongoing key rotation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/rotate-key/cancel": { "post": { "tags": [ "Rotation" ], "summary": "Abandon an in-progress rotation and re-open the vault for writes.", "operationId": "vault_rotation_cancel", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationCancelRequest" } } }, "required": true }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found or rotation_token did not match" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/rotate-key/complete": { "post": { "tags": [ "Rotation" ], "summary": "Atomically commit a rotation: re-wrap every member's vault key,\nre-encrypt every item, attachment metadata, and invitation email under\nthe new vault key, and re-wrap every attachment content key.", "operationId": "vault_rotation_complete", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationCompleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseJsonValue" } } } }, "400": { "description": "Submitted membership/item set does not match the vault" }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found or rotation_token did not match" }, "422": { "description": "Request body failed validation" } } } }, "/publishers/seren-passwords/vaults/{vault_id}/rotate-key/initiate": { "post": { "tags": [ "Rotation" ], "summary": "Begin a key rotation on a vault: marks the vault `rotating`, mints a\nrotation_token, and blocks vault writes from this point on.", "operationId": "vault_rotation_initiate", "parameters": [ { "name": "vault_id", "in": "path", "description": "Vault id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rotation token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponseRotationInitiate" } } } }, "401": { "description": "Caller is not authenticated" }, "403": { "description": "Caller is not an admin of this vault" }, "404": { "description": "Vault not found" }, "423": { "description": "Vault is already rotating" } } } }, "/publishers/seren-skills": { "get": { "tags": [ "skills" ], "operationId": "publisher_root", "responses": { "200": { "description": "Publisher metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/admin/skills/orphan-folders": { "get": { "tags": [ "skills" ], "summary": "Operator inventory of canonical-repo paths the gateway has no\nclaim on.", "description": "Authorization: any caller with `X-Seren-User-Role: admin` (platform\nadmin set by Seren Core's `ADMIN_USER_IDS`). The endpoint is\n**read-only** and does not return per-org data — every orphan is by\ndefinition a path the gateway has lost track of, so scoping it to one\norganization would defeat the visibility purpose. Unauthorized callers\nreceive 403.\n\nOn success returns:\n\n```json\n{\n \"head_commit_sha\": \"...\",\n \"head_tree_sha\": \"...\",\n \"orphan_folders\": [\n {\n \"folder_slug\": \"org-deadbeef\",\n \"skill_folder_name\": \"grid-trader\",\n \"paths\": [\"org-deadbeef/grid-trader/SKILL.md\", \"...\"]\n }\n ]\n}\n```\n\nFailure modes:\n\n- 403 if the caller lacks `X-Seren-User-Role=admin`.\n- 400 if GitHub publishing is not configured for this deployment.\n- 500 if GitHub returned a truncated tree listing (we cannot\n trust a partial view for an inventory pass — same posture as\n `derive_orphan_paths` in `github_status`).", "operationId": "list_orphan_folders", "responses": { "200": { "description": "Operator orphan-folders inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_OrphanFoldersResponse" } } } }, "403": { "description": "Caller lacks platform admin role" } } } }, "/publishers/seren-skills/git-identity": { "get": { "tags": [ "skills" ], "operationId": "get_author_identity", "responses": { "200": { "description": "Git author identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AuthorIdentity" } } } } } }, "put": { "tags": [ "skills" ], "operationId": "upsert_author_identity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAuthorIdentityRequest" } } }, "required": true }, "responses": { "200": { "description": "Upserted Git author identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_AuthorIdentity" } } } } } } }, "/publishers/seren-skills/organizations/{org_id}/folder": { "get": { "tags": [ "skills" ], "operationId": "get_org_folder", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } }, "put": { "tags": [ "skills" ], "operationId": "replace_org_folder", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrgFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } }, "post": { "tags": [ "skills" ], "operationId": "create_org_folder", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrgFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } }, "patch": { "tags": [ "skills" ], "operationId": "update_org_folder", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrgFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/organizations/{org_id}/folder/transfer": { "post": { "tags": [ "skills" ], "operationId": "transfer_org_folder", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrgFolderRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "403": { "description": "Caller is not org-admin, personal-owner of {org_id}, or platform admin" }, "404": { "description": "Slug is not held by any folder row" }, "409": { "description": "Slug is held by a real organization, not a placeholder" } } } }, "/publishers/seren-skills/skill.md": { "get": { "tags": [ "skills" ], "operationId": "skill_md", "responses": { "200": { "description": "Publisher skill definition", "content": { "text/markdown": {} } } } } }, "/publishers/seren-skills/skills": { "get": { "tags": [ "skills" ], "operationId": "list_skills", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "visibility", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVisibility" } ] } }, { "name": "mine", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ListSkillsSort" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Skills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_SkillSummary" } } } } } }, "post": { "tags": [ "skills" ], "operationId": "create_skill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Created skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillDetail" } } } } } } }, "/publishers/seren-skills/skills/{slug}": { "get": { "tags": [ "skills" ], "operationId": "get_skill", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillDetail" } } } } } }, "delete": { "tags": [ "skills" ], "operationId": "delete_skill", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Soft-deleted skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } }, "patch": { "tags": [ "skills" ], "operationId": "update_skill", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillDetail" } } } } } } }, "/publishers/seren-skills/skills/{slug}/agent-grants": { "get": { "tags": [ "skills" ], "operationId": "list_agent_grants", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed agent grants for an organization-authorized skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_SkillAgentGrant" } } } } } } }, "/publishers/seren-skills/skills/{slug}/agent-grants/{agent_identity_id}": { "put": { "tags": [ "skills" ], "operationId": "upsert_agent_grant", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "agent_identity_id", "in": "path", "description": "Managed agent identity", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSkillAgentGrantRequest" } } }, "required": true }, "responses": { "200": { "description": "Created or updated managed agent skill grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillAgentGrant" } } } } } }, "delete": { "tags": [ "skills" ], "operationId": "revoke_agent_grant", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "agent_identity_id", "in": "path", "description": "Managed agent identity", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_grant_generation", "in": "query", "description": "Generation observed by the caller before revocation.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Managed agent skill grant revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_bool" } } } } } } }, "/publishers/seren-skills/skills/{slug}/collaborators": { "get": { "tags": [ "skills" ], "operationId": "list_collaborators", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill collaborators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Collaborator" } } } } } } }, "/publishers/seren-skills/skills/{slug}/collaborators/{user_id}": { "put": { "tags": [ "skills" ], "operationId": "upsert_collaborator", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Collaborator user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCollaboratorRequest" } } }, "required": true }, "responses": { "200": { "description": "Upserted collaborator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Collaborator" } } } } } }, "delete": { "tags": [ "skills" ], "operationId": "delete_collaborator", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Collaborator user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted collaborator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/skills/{slug}/download": { "get": { "tags": [ "skills" ], "operationId": "download_skill", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Downloadable skill bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillBundle" } } } } } } }, "/publishers/seren-skills/skills/{slug}/download/file": { "get": { "tags": [ "skills" ], "operationId": "download_skill_file", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Bundle-relative file path from the manifest", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One bundle file body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillBundleFileDownload" } } } } } } }, "/publishers/seren-skills/skills/{slug}/download/manifest": { "get": { "tags": [ "skills" ], "operationId": "download_skill_manifest", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bundle manifest without file bodies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillBundleManifest" } } } } } } }, "/publishers/seren-skills/skills/{slug}/drafts/{draft_id}": { "get": { "tags": [ "skills" ], "operationId": "get_draft", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "description": "Draft ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Chat conflict draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_ChatDraftResponse" } } } } } } }, "/publishers/seren-skills/skills/{slug}/drafts/{draft_id}/merge-state": { "get": { "tags": [ "skills" ], "operationId": "get_merge_state", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "description": "Draft ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Merge state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_MergeStateResponse" } } } } } } }, "/publishers/seren-skills/skills/{slug}/drafts/{draft_id}/resolve-conflict": { "post": { "tags": [ "skills" ], "operationId": "resolve_conflict", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "description": "Draft ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveConflictRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolved conflict version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CreateVersionResponse" } } } } } } }, "/publishers/seren-skills/skills/{slug}/edit": { "get": { "tags": [ "skills" ], "operationId": "get_skill_edit_document", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Editor-facing document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillEditDocument" } } } }, "403": { "description": "Owner access required" } } } }, "/publishers/seren-skills/skills/{slug}/files": { "get": { "tags": [ "skills" ], "summary": "`GET /skills/{slug}/files` -- list every file in the current\nversion's bundle, plus a synthetic `SKILL.md` entry.", "operationId": "list_files", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bundle file listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_FileListing" } } } } } } }, "/publishers/seren-skills/skills/{slug}/files/{path}": { "get": { "tags": [ "skills" ], "summary": "`GET /skills/{slug}/files/{path...}` -- one file's bytes.", "operationId": "get_file", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Bundle path or 'SKILL.md'", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Single bundle file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_GetFileResponse" } } } } } }, "put": { "tags": [ "skills" ], "summary": "`PUT /skills/{slug}/files/{path...}` -- replace or add one file.", "operationId": "put_file", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Bundle path or 'SKILL.md'", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Per-file edit result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FileEditResponse" } } } } } }, "delete": { "tags": [ "skills" ], "summary": "`DELETE /skills/{slug}/files/{path...}` -- drop one file.", "operationId": "delete_file", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Bundle path; SKILL.md is rejected with 400", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Per-file delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_FileEditResponse" } } } } } } }, "/publishers/seren-skills/skills/{slug}/github": { "get": { "tags": [ "skills" ], "operationId": "github_status", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub publish ledger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/skills/{slug}/github/reconcile-orphans": { "post": { "tags": [ "skills" ], "summary": "`POST /skills/{slug}/github/reconcile-orphans` -- ops endpoint\nthat mechanically removes canonical-repo paths the gateway no\nlonger claims for this skill. Issue #22 acceptance:", "description": "- Owner, org-admin, or platform-admin authz (same\n `ensure_can_operate_skill_catalog` pattern as\n `/github/sync-from-main` and `/github/retry`).\n- `confirm: true` is required. `false` or missing returns 409.\n- The handler re-derives the **live** orphan-path set against the\n canonical-repo HEAD and returns 409 if it does not match the\n `expected_orphan_paths` payload (optimistic concurrency mirrors\n `expected_current_version_id`).\n- On match (and `dry_run: false`): stages one signed commit on\n the canonical branch deleting every path. Author/committer is\n the forward-publish bot pair so reverse-sync skips the commit\n via `is_forward_publish_commit`.\n- On `dry_run: true`: skips the commit and returns the planned\n shape (paths + parent commit SHA + audit row id) without\n touching GitHub.\n- Records a `skill_orphan_reconciliations` audit row in both\n modes (issue #22 acceptance criterion + migration 011).", "operationId": "reconcile_orphans", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileOrphansRequest" } } }, "required": true }, "responses": { "200": { "description": "Reconcile result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } }, "409": { "description": "Mismatch or unconfirmed request", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/publishers/seren-skills/skills/{slug}/github/retry": { "post": { "tags": [ "skills" ], "operationId": "retry_github_publish", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub publish retry queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/skills/{slug}/github/sync-from-main": { "post": { "tags": [ "skills" ], "summary": "`POST /skills/{slug}/github/sync-from-main` -- ops endpoint that\nre-fetches the canonical GitHub bundle at HEAD and reconciles it\ninto a new gateway version. No-op when the resulting\n`content_hash_bundle` matches the current version. Requires owner,\norg-admin, or `X-Seren-User-Role=admin`.", "operationId": "sync_from_main", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub sync-from-main result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/skills/{slug}/purchase": { "post": { "tags": [ "skills" ], "operationId": "purchase_skill", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchase result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_PurchaseResponse" } } } }, "402": { "description": "Insufficient balance" } } } }, "/publishers/seren-skills/skills/{slug}/sponsor": { "put": { "tags": [ "skills" ], "operationId": "update_sponsor", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSponsorRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated sponsor settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SkillDetail" } } } } } } }, "/publishers/seren-skills/skills/{slug}/update-requests": { "get": { "tags": [ "skills" ], "operationId": "list_update_requests", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_UpdateRequest" } } } } } }, "post": { "tags": [ "skills" ], "operationId": "create_update_request", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Created update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UpdateRequest" } } } } } } }, "/publishers/seren-skills/skills/{slug}/versions": { "get": { "tags": [ "skills" ], "operationId": "list_versions", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_SkillVersion" } } } } } }, "post": { "tags": [ "skills" ], "operationId": "create_version", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "Created skill version or conflict draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_CreateVersionResponse" } } } } } } }, "/publishers/seren-skills/skills/{slug}/versions/{version}/manifest": { "get": { "tags": [ "skills" ], "operationId": "get_version_manifest", "parameters": [ { "name": "slug", "in": "path", "description": "Skill slug", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "Version string", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Version manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/update-requests/{request_id}": { "get": { "tags": [ "skills" ], "operationId": "get_update_request", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Update request detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UpdateRequestDetail" } } } } } } }, "/publishers/seren-skills/update-requests/{request_id}/accept": { "post": { "tags": [ "skills" ], "operationId": "accept_update_request", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptUpdateRequestRequest" } } }, "required": true }, "responses": { "200": { "description": "Accepted update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UpdateRequest" } } } } } } }, "/publishers/seren-skills/update-requests/{request_id}/comments": { "get": { "tags": [ "skills" ], "operationId": "list_update_request_comments", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Update request comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_UpdateRequestComment" } } } } } }, "post": { "tags": [ "skills" ], "operationId": "create_update_request_comment", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommentRequest" } } }, "required": true }, "responses": { "200": { "description": "Created comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Value" } } } } } } }, "/publishers/seren-skills/update-requests/{request_id}/diff": { "get": { "tags": [ "skills" ], "operationId": "get_update_request_diff", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Update request diff payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UpdateRequestDiff" } } } } } } }, "/publishers/seren-skills/update-requests/{request_id}/reject": { "post": { "tags": [ "skills" ], "operationId": "reject_update_request", "parameters": [ { "name": "request_id", "in": "path", "description": "Update request ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rejected update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UpdateRequest" } } } } } } }, "/publishers/seren-skills/usage": { "get": { "tags": [ "skills" ], "operationId": "list_usage_events", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Usage events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_UsageEvent" } } } } } } }, "/publishers/seren-skills/usage/summary": { "get": { "tags": [ "skills" ], "operationId": "usage_summary", "responses": { "200": { "description": "Current-month usage totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_UsageSummaryResponse" } } } } } } }, "/publishers/seren-notes/attachments/{attachment_id}": { "get": { "tags": [ "attachments" ], "summary": "Get attachment metadata", "operationId": "get_attachment", "parameters": [ { "name": "attachment_id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Attachment" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Attachment not found" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "attachments" ], "summary": "Delete an attachment", "operationId": "delete_attachment", "parameters": [ { "name": "attachment_id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Attachment not found" } }, "security": [ { "api_key": [] } ] }, "patch": { "tags": [ "attachments" ], "summary": "Update attachment metadata", "operationId": "update_attachment", "parameters": [ { "name": "attachment_id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAttachmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Attachment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Attachment" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Attachment not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/attachments/{attachment_id}/data": { "get": { "tags": [ "attachments" ], "summary": "Download attachment data", "operationId": "download_attachment", "parameters": [ { "name": "attachment_id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment binary data" }, "304": { "description": "Not modified (ETag match)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Attachment not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/attachments/{attachment_id}/thumbnail": { "get": { "tags": [ "attachments" ], "summary": "Download attachment thumbnail (generated on-demand)", "operationId": "download_thumbnail", "parameters": [ { "name": "attachment_id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "width", "in": "query", "description": "Maximum width in pixels (default: 200, max: 800)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "height", "in": "query", "description": "Maximum height in pixels (default: 200, max: 800)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Thumbnail image (JPEG)" }, "304": { "description": "Not modified (ETag match)" }, "400": { "description": "Not an image attachment" }, "401": { "description": "Unauthorized" }, "404": { "description": "Attachment not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes": { "get": { "tags": [ "notes" ], "summary": "List notes with filters", "operationId": "list_notes", "parameters": [ { "name": "parent_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of notes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_NoteSummary" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "notes" ], "summary": "Create a new note", "operationId": "create_note", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNoteRequest" } } }, "required": true }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/embeddings/stale": { "get": { "tags": [ "search" ], "summary": "Get notes that need embedding updates", "operationId": "get_stale_embeddings", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum notes to return", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "List of note IDs needing embeddings" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/search": { "get": { "tags": [ "notes" ], "summary": "Full-text search notes", "operationId": "search_notes", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_NoteSummary" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/search/semantic": { "post": { "tags": [ "search" ], "summary": "Semantic search using embedding vector", "operationId": "semantic_search", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchQuery" } } }, "required": true }, "responses": { "200": { "description": "Semantic search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_SemanticSearchResultResponse" } } } }, "400": { "description": "Invalid embedding" }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/tags": { "get": { "tags": [ "tags" ], "summary": "List all tags", "operationId": "list_tags", "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_String" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}": { "get": { "tags": [ "notes" ], "summary": "Get a specific note", "operationId": "get_note", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/NoteFormat" } } ], "responses": { "200": { "description": "Note found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "notes" ], "summary": "Delete a note", "operationId": "delete_note", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Note deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] }, "patch": { "tags": [ "notes" ], "summary": "Update a note", "operationId": "update_note", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Note updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" }, "409": { "description": "Version conflict" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/append": { "post": { "tags": [ "notes" ], "summary": "Append content to a note", "operationId": "append_to_note", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendToNoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Content appended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/attachments": { "get": { "tags": [ "attachments" ], "summary": "List attachments for a note", "operationId": "list_attachments", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of attachments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_Attachment" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "attachments" ], "summary": "Upload an attachment (binary body with headers)", "operationId": "upload_attachment", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Filename", "in": "header", "description": "Original filename", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "MIME type", "required": true, "schema": { "type": "string" } }, { "name": "X-Alt-Text", "in": "header", "description": "Alt text for accessibility", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "201": { "description": "Attachment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Attachment" } } } }, "400": { "description": "Invalid request or file too large" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/attachments/import": { "post": { "tags": [ "attachments" ], "summary": "Import an image from an external URL and store it as an attachment", "operationId": "import_attachment_from_url", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportAttachmentFromUrlRequest" } } }, "required": true }, "responses": { "201": { "description": "Attachment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Attachment" } } } }, "400": { "description": "Invalid request or URL not allowed" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/embedding": { "put": { "tags": [ "search" ], "summary": "Update a note's embedding", "operationId": "update_embedding", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmbeddingRequest" } } }, "required": true }, "responses": { "204": { "description": "Embedding updated" }, "400": { "description": "Invalid embedding" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/embedding/content": { "get": { "tags": [ "search" ], "summary": "Get note content for embedding generation", "operationId": "get_embedding_content", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Note content for embedding" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/shares": { "get": { "tags": [ "shares" ], "summary": "List shares for a note", "operationId": "list_shares", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of shares", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_Vec_NoteShare" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/notes/{note_id}/tags": { "post": { "tags": [ "tags" ], "summary": "Add tags to a note", "operationId": "add_tags", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTagsRequest" } } }, "required": true }, "responses": { "200": { "description": "Tags added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "tags" ], "summary": "Remove tags from a note", "operationId": "remove_tags", "parameters": [ { "name": "note_id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTagsRequest" } } }, "required": true }, "responses": { "200": { "description": "Tags removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/share/{token}": { "get": { "tags": [ "shares" ], "summary": "Get a publicly shared note by cryptographic share token", "description": "This endpoint does not require authentication. The token contains an embedded\norganization_id (cryptographically signed) which is used to route to the correct\ntenant database via serencore's service JWT API. The token is verified before use.", "operationId": "get_public_shared_note", "parameters": [ { "name": "token", "in": "path", "description": "Cryptographic share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shared note found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_SharedNoteResponse" } } } }, "400": { "description": "Invalid token format or signature" }, "403": { "description": "Share does not allow anonymous access" }, "404": { "description": "Share not found, expired, or not public" } } } }, "/publishers/seren-notes/shares": { "post": { "tags": [ "shares" ], "summary": "Create a share for a note", "operationId": "create_share", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareApiRequest" } } }, "required": true }, "responses": { "201": { "description": "Share created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteShare" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Note not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-notes/shares/token/{token}": { "get": { "tags": [ "shares" ], "summary": "Get a share by token (for public access)", "operationId": "get_share_by_token", "parameters": [ { "name": "token", "in": "path", "description": "Share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Share found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteShare" } } } }, "404": { "description": "Share not found or expired" } } } }, "/publishers/seren-notes/shares/{share_id}": { "get": { "tags": [ "shares" ], "summary": "Get a share by ID", "operationId": "get_share", "parameters": [ { "name": "share_id", "in": "path", "description": "Share ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Share found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteShare" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Share not found" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "shares" ], "summary": "Delete (revoke) a share", "operationId": "delete_share", "parameters": [ { "name": "share_id", "in": "path", "description": "Share ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Share deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Share not found" } }, "security": [ { "api_key": [] } ] }, "patch": { "tags": [ "shares" ], "summary": "Update a share", "operationId": "update_share", "parameters": [ { "name": "share_id", "in": "path", "description": "Share ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShareApiRequest" } } }, "required": true }, "responses": { "200": { "description": "Share updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse_NoteShare" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Share not found" } }, "security": [ { "api_key": [] } ] } }, "/publishers/seren-memory": { "get": { "tags": [ "Health" ], "summary": "Describe the Seren Memory service", "operationId": "seren_memory_root", "responses": { "200": { "description": "Service health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_HealthResponse" } } } } } } }, "/publishers/seren-memory/bootstrap": { "post": { "tags": [ "Memory" ], "summary": "Bootstrap private context for a session", "operationId": "seren_memory_session_bootstrap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemorySessionBootstrapParams" } } }, "required": true }, "responses": { "200": { "description": "Session memory context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_SessionContext" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/capture_agent_turn": { "post": { "tags": [ "Memory" ], "summary": "Capture a completed agent turn from a lifecycle hook", "description": "Dedicated ingestion operation for automatic agent capture. Accepts prompt and assistant-response content as separate fields so the current organization policy can independently permit each content class before the service assembles an extraction transcript. Requires a stable source_external_id in the reserved hook: namespace and the current server-issued organization policy_version. Stale callers must refresh the policy and re-sanitize queued content. The operation always stores a metadata source envelope for idempotent retries and stores the assembled raw payload only when both retain_source is requested and organization policy permits it. Source metadata is provenance validated against a separate 16,000-byte serialized bound and does not count against max_transcript_bytes.", "operationId": "seren_memory_capture_agent_turn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryCaptureAgentTurnParams" } } }, "required": true }, "responses": { "200": { "description": "Extracted memory candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ExtractionResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Automatic capture or the requested capture mode is disabled by organization policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "The submitted organization policy revision is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "413": { "description": "The captured transcript and project context exceed the organization policy limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "503": { "description": "The organization policy could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/forget": { "post": { "tags": [ "Memory" ], "summary": "Soft-delete a private memory", "operationId": "seren_memory_forget_memory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryForgetParams" } } }, "required": true }, "responses": { "200": { "description": "Memory forgetting result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ForgetMemoryResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "500": { "description": "Unexpected service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/health": { "get": { "tags": [ "Health" ], "summary": "Check service health", "operationId": "seren_memory_health", "responses": { "200": { "description": "Service health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_HealthResponse" } } } } } } }, "/publishers/seren-memory/health/detailed": { "get": { "tags": [ "Health" ], "summary": "Check detailed service health", "operationId": "seren_memory_health_detailed", "responses": { "200": { "description": "Detailed service health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_HealthResponse" } } } } } } }, "/publishers/seren-memory/ingest/document": { "post": { "tags": [ "Memory" ], "summary": "Ingest a managed rich document", "operationId": "seren_memory_ingest_document", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryIngestDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "Document ingestion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_IngestDocumentOutput" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/jobs/consolidate": { "post": { "tags": [ "Memory" ], "summary": "Consolidate private memories", "operationId": "seren_memory_consolidate_job", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryConsolidateJobRequest" } } }, "required": true }, "responses": { "200": { "description": "Consolidation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ConsolidateJobResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "500": { "description": "Unexpected service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/domains": { "get": { "tags": [ "Knowledge" ], "summary": "List accessible organizational knowledge domains", "operationId": "seren_memory_list_knowledge_domains", "responses": { "200": { "description": "Accessible knowledge domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeDomainsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Knowledge Administration" ], "summary": "Create an organizational knowledge domain", "operationId": "seren_memory_create_knowledge_domain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryCreateKnowledgeDomainRequest" } } }, "required": true }, "responses": { "200": { "description": "Created knowledge domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeDomainResponse" } } } }, "400": { "description": "Invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Organization owner or administrator required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Domain slug already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "413": { "description": "Organization knowledge domain limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/domains/{domain_id}": { "put": { "tags": [ "Knowledge Administration" ], "summary": "Update an organizational knowledge domain", "operationId": "seren_memory_put_knowledge_domain", "parameters": [ { "name": "domain_id", "in": "path", "description": "Knowledge domain identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryUpdateKnowledgeDomainRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated knowledge domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeDomainResponse" } } } }, "400": { "description": "Invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain owner permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/domains/{domain_id}/grants": { "get": { "tags": [ "Knowledge Administration" ], "summary": "List grants for an organizational knowledge domain", "operationId": "seren_memory_list_knowledge_domain_grants", "parameters": [ { "name": "domain_id", "in": "path", "description": "Knowledge domain identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge domain grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeDomainGrantsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain owner permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Knowledge Administration" ], "summary": "Set a grant for an organizational knowledge domain", "operationId": "seren_memory_put_knowledge_domain_grant", "parameters": [ { "name": "domain_id", "in": "path", "description": "Knowledge domain identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainGrantRequest" } } }, "required": true }, "responses": { "200": { "description": "Knowledge domain grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeDomainGrantResponse" } } } }, "400": { "description": "Invalid grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain owner permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/domains/{domain_id}/grants/{principal_type}/{principal_id}": { "delete": { "tags": [ "Knowledge Administration" ], "summary": "Remove a grant from an organizational knowledge domain", "operationId": "seren_memory_delete_knowledge_domain_grant", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "principal_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge domain grant deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_DeleteKnowledgeDomainGrantResponse" } } } }, "400": { "description": "Invalid principal type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain owner permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Domain must retain an owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/entities/open": { "post": { "tags": [ "Knowledge" ], "summary": "Open an organizational knowledge entity", "operationId": "seren_memory_open_knowledge_entity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryOpenKnowledgeEntityRequest" } } }, "required": true }, "responses": { "200": { "description": "Organizational knowledge entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeOperationResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Organizational knowledge is not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "502": { "description": "Knowledge backend unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/model": { "get": { "tags": [ "Knowledge Administration" ], "summary": "Get the desired organizational knowledge model", "operationId": "seren_memory_get_knowledge_model", "parameters": [ { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Organization knowledge model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeModelConfigurationResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain editor permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Knowledge model is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Knowledge Administration" ], "summary": "Set the desired organizational knowledge model", "operationId": "seren_memory_put_knowledge_model", "parameters": [ { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryKnowledgeModel" } } }, "required": true }, "responses": { "200": { "description": "Queued organization knowledge model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeModelConfigurationResponse" } } } }, "400": { "description": "Invalid knowledge model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain editor or organization administrator required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/operations": { "get": { "tags": [ "Knowledge" ], "summary": "List available organizational knowledge operations", "operationId": "seren_memory_list_knowledge_operations", "parameters": [ { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Published organizational knowledge operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeOperationsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Knowledge is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "502": { "description": "Knowledge service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/operations/{operation_name}": { "post": { "tags": [ "Knowledge" ], "summary": "Invoke a published organizational knowledge operation", "operationId": "seren_memory_invoke_knowledge_operation", "parameters": [ { "name": "operation_name", "in": "path", "description": "Published operation name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryInvokeKnowledgeOperationRequest" } } }, "required": true }, "responses": { "200": { "description": "Organizational knowledge operation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeOperationResult" } } } }, "400": { "description": "Invalid operation or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Knowledge is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "502": { "description": "Knowledge service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/records": { "get": { "tags": [ "Knowledge Administration" ], "summary": "List canonical organizational knowledge records", "operationId": "seren_memory_list_knowledge_records", "parameters": [ { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Canonical organization knowledge records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ListKnowledgeRecordsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Human organization member required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/records/{record_key}": { "put": { "tags": [ "Knowledge Administration" ], "summary": "Create or replace a canonical organizational knowledge record", "operationId": "seren_memory_put_knowledge_record", "parameters": [ { "name": "record_key", "in": "path", "description": "Stable record key", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryUpsertKnowledgeRecordRequest" } } }, "required": true }, "responses": { "200": { "description": "Queued canonical knowledge record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeRecordResponse" } } } }, "400": { "description": "Invalid knowledge record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Domain editor permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Knowledge model is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "413": { "description": "Organization knowledge limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Knowledge Administration" ], "summary": "Delete a canonical organizational knowledge record", "operationId": "seren_memory_delete_knowledge_record", "parameters": [ { "name": "record_key", "in": "path", "description": "Stable record key", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge record deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_DeleteKnowledgeRecordResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "403": { "description": "Human organization member required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/knowledge/search": { "post": { "tags": [ "Knowledge" ], "summary": "Search governed organizational knowledge", "operationId": "seren_memory_search_knowledge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemorySearchKnowledgeRequest" } } }, "required": true }, "responses": { "200": { "description": "Organizational knowledge query result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_KnowledgeOperationResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Organizational knowledge is not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "502": { "description": "Knowledge backend unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/learn_from_error": { "post": { "tags": [ "Memory" ], "summary": "Store a verified error and fix", "operationId": "seren_memory_learn_from_error", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryLearnFromErrorParams" } } }, "required": true }, "responses": { "200": { "description": "Learned memory result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_RememberOutput" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/livez": { "get": { "tags": [ "Health" ], "summary": "Check process liveness", "operationId": "seren_memory_livez", "responses": { "200": { "description": "Process is live" } } } }, "/publishers/seren-memory/mcp": { "post": { "tags": [ "MCP" ], "summary": "Call the Seren Memory MCP transport", "operationId": "seren_memory_mcp_handler", "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "MCP protocol response" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories": { "get": { "tags": [ "Memory" ], "summary": "List private memories", "operationId": "seren_memory_list_memories", "parameters": [ { "name": "memory_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_pinned", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "is_consolidated", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "lifecycle_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "org_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Memories matching the requested scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ListMemoriesResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/by-source": { "delete": { "tags": [ "Memory" ], "summary": "Permanently delete retained sources and derived memories", "operationId": "seren_memory_delete_memories_by_source", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDeleteMemoriesBySourceParams" } } }, "required": true }, "responses": { "200": { "description": "Source deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_DeleteBySourceOutcome" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/connections": { "post": { "tags": [ "Memory" ], "summary": "Connect two private memories", "operationId": "seren_memory_link_memories", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryMemoryConnectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Connection result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryConnectionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Memory" ], "summary": "Disconnect two private memories", "operationId": "seren_memory_unlink_memories", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryMemoryConnectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Connection result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryConnectionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/export": { "get": { "tags": [ "Memory" ], "description": "Returns parallel pages from the memory and conversation-source collections. The same limit and offset are applied independently to each collection; continue with next_offset until it is null.", "operationId": "seren_memory_export_memories", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "description": "Shared offset applied independently to memories and conversation sources.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Portable private-memory export page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryExportResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}": { "get": { "tags": [ "Memory" ], "summary": "Get a private memory", "operationId": "seren_memory_get_memory", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Memory record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_Option_MemoryOutput" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "500": { "description": "Unexpected service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Memory" ], "summary": "Permanently delete a private memory", "operationId": "seren_memory_delete_memory", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Memory deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_DeleteMemoryResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "500": { "description": "Unexpected service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}/append": { "post": { "tags": [ "Memory" ], "summary": "Append to a private memory", "operationId": "seren_memory_append_memory", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryAppendMemoryRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated memory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryOutput" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Source-managed memory requires re-ingestion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}/review": { "put": { "tags": [ "Memory" ], "summary": "Set a private memory review status", "description": "Explicit review transition. No ingestion channel grants reviewed trust automatically, and this operation is intentionally not exposed as an MCP tool.", "operationId": "seren_memory_set_memory_review", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemorySetMemoryReviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Review transition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_SetMemoryReviewResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}/revisions": { "get": { "tags": [ "Memory" ], "summary": "List a private memory's revisions", "operationId": "seren_memory_list_memory_revisions", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Memory revisions newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_Vec_MemoryRevision" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}/status": { "put": { "tags": [ "Memory" ], "summary": "Set a private memory lifecycle status", "operationId": "seren_memory_set_memory_status", "parameters": [ { "name": "id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemorySetMemoryStatusRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated memory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_Option_MemoryOutput" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/memories/{id}/timeline": { "get": { "tags": [ "Memory" ], "operationId": "seren_memory_memory_timeline", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } } ], "responses": { "200": { "description": "Temporal memory relationships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_Vec_MemoryEdge" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations": { "post": { "tags": [ "Memory" ], "summary": "Create a durable import migration record", "operationId": "seren_memory_create_migration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryCreateMigrationRequest" } } }, "required": true }, "responses": { "200": { "description": "Created migration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryMigration" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Snapshot or series identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations/{id}": { "get": { "tags": [ "Memory" ], "summary": "Get one migration record with live record counts", "operationId": "seren_memory_get_migration", "parameters": [ { "name": "id", "in": "path", "description": "Migration ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Migration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MigrationStatusResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Migration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations/{id}/embeddings": { "post": { "tags": [ "Memory" ], "summary": "Generate embeddings for imported migration records", "description": "Processes a bounded batch of pending or failed imported memories. Call until embedding_pending and embedding_failed are both zero before completing the migration.", "operationId": "seren_memory_embed_migration_records", "parameters": [ { "name": "id", "in": "path", "description": "Migration ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryEmbedMigrationRecordsRequest" } } }, "required": true }, "responses": { "200": { "description": "Current embedding status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_EmbedMigrationRecordsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Migration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Migration state does not accept embedding work", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "502": { "description": "Embedding service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations/{id}/records": { "post": { "tags": [ "Memory" ], "summary": "Import a batch of already-extracted records under a migration", "description": "Records use the reserved import: namespace and are idempotent per source_external_id. Extraction never runs. The response reports the outcome and durable IDs for every submitted record.", "operationId": "seren_memory_import_migration_records", "parameters": [ { "name": "id", "in": "path", "description": "Migration ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryImportRecordsRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ImportRecordsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Migration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Migration state or stable record identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations/{id}/rollback": { "post": { "tags": [ "Memory" ], "summary": "Remove every record created by a migration run or its series", "description": "Selection is strictly by stored migration provenance; hook, MCP, manual, and unrelated import records can never be selected.", "operationId": "seren_memory_rollback_migration", "parameters": [ { "name": "id", "in": "path", "description": "Migration ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryRollbackMigrationRequest" } } }, "required": true }, "responses": { "200": { "description": "Rollback result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_RollbackMigrationResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Migration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Rollback is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/migrations/{id}/state": { "put": { "tags": [ "Memory" ], "summary": "Transition a migration lifecycle state", "operationId": "seren_memory_set_migration_state", "parameters": [ { "name": "id", "in": "path", "description": "Migration ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemorySetMigrationStateRequest" } } }, "required": true }, "responses": { "200": { "description": "Transition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_MemoryMigration" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "404": { "description": "Migration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Invalid or concurrent state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "Get the Seren Memory OpenAPI document", "operationId": "seren_memory_serve_openapi", "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/publishers/seren-memory/process_conversation": { "post": { "tags": [ "Memory" ], "summary": "Extract private memories from a conversation", "operationId": "seren_memory_process_conversation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryProcessConversationParams" } } }, "required": true }, "responses": { "200": { "description": "Extracted memory candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ExtractionResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/readyz": { "get": { "tags": [ "Health" ], "summary": "Check service readiness", "operationId": "seren_memory_readyz", "responses": { "200": { "description": "Service is ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ReadinessResponse" } } } }, "503": { "description": "A required dependency is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_ReadinessResponse" } } } } } } }, "/publishers/seren-memory/recall": { "post": { "tags": [ "Memory" ], "summary": "Recall relevant private memories", "operationId": "seren_memory_recall", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryRecallParams" } } }, "required": true }, "responses": { "200": { "description": "Relevant memories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_RecallResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/remember": { "post": { "tags": [ "Memory" ], "summary": "Remember durable private context", "operationId": "seren_memory_remember", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryRememberParams" } } }, "required": true }, "responses": { "200": { "description": "Memory operation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_RememberOutput" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/skill.md": { "get": { "tags": [ "Meta" ], "summary": "Get the Seren Memory skill document", "operationId": "seren_memory_skill_md", "responses": { "200": { "description": "Publisher skill definition", "content": { "text/markdown": {} } } } } }, "/publishers/seren-memory/sync/status": { "get": { "tags": [ "Memory" ], "summary": "Get memory synchronization status", "operationId": "seren_memory_sync_status", "responses": { "200": { "description": "Synchronization status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_SyncStatus" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/workspaces/merge": { "post": { "tags": [ "Memory" ], "summary": "Execute a reviewed workspace merge", "description": "Rechecks the state-bound preview under workspace locks, rewrites source envelopes to the canonical target, creates a durable alias for future captures, and records an immutable audit row. Retrying the same accepted plan is idempotent.", "operationId": "seren_memory_execute_workspace_merge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryExecuteWorkspaceMergeRequest" } } }, "required": true }, "responses": { "200": { "description": "Completed workspace merge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_WorkspaceMergeResult" } } } }, "400": { "description": "Invalid workspace keys or plan hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Preview is stale or workspace alias conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-memory/workspaces/merge/preview": { "post": { "tags": [ "Memory" ], "summary": "Preview a controlled workspace merge", "description": "Returns content-free source counts, shared external-session collisions, dependent aliases, and a state-bound plan hash. No records are changed.", "operationId": "seren_memory_preview_workspace_merge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryPreviewWorkspaceMergeRequest" } } }, "required": true }, "responses": { "200": { "description": "Workspace merge preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryDataResponse_WorkspaceMergePreview" } } } }, "400": { "description": "Invalid workspace keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } }, "409": { "description": "Source workspace is already an alias", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenMemoryErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage": { "get": { "tags": [ "Meta" ], "operationId": "seren_storage_root", "responses": { "200": { "description": "Service metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ServiceInfo" } } } } } } }, "/publishers/seren-storage/buckets": { "get": { "tags": [ "Objects" ], "operationId": "seren_storage_list_buckets", "responses": { "200": { "description": "Storage buckets retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_Vec_ObjectStorageBucket" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/agent-grants": { "get": { "tags": [ "Access" ], "operationId": "seren_storage_list_bucket_agent_grants", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee bucket grants retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_Vec_ObjectStorageBucketAgentGrant" } } } }, "403": { "description": "Organization management permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/agent-grants/{agent_identity_id}": { "put": { "tags": [ "Access" ], "operationId": "seren_storage_put_bucket_agent_grant", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "agent_identity_id", "in": "path", "description": "Employee identity ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStoragePutObjectStorageBucketAgentGrantRequest" } } }, "required": true }, "responses": { "200": { "description": "Employee bucket grant stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageBucketAgentGrant" } } } }, "403": { "description": "Organization management permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Access" ], "operationId": "seren_storage_delete_bucket_agent_grant", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "agent_identity_id", "in": "path", "description": "Employee identity ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Employee bucket grant revoked" }, "403": { "description": "Organization management permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/lifecycle": { "put": { "tags": [ "Objects" ], "operationId": "seren_storage_put_bucket_lifecycle", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStoragePutObjectStorageBucketLifecycleRequest" } } }, "required": true }, "responses": { "200": { "description": "Bucket lifecycle updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageBucket" } } } }, "403": { "description": "Organization management permission required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects": { "get": { "tags": [ "Objects" ], "operationId": "seren_storage_list_objects", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "delimiter", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Storage objects and directory prefixes retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObjectPage" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/by-key/download": { "get": { "tags": [ "Objects" ], "operationId": "seren_storage_download_object", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Download URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageDownload" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/multipart-uploads": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_create_multipart_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageCreateObjectStorageMultipartUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Multipart upload initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageMultipartUpload" } } } }, "409": { "description": "Object key already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/uploads": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_create_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageCreateObjectStorageUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Upload intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageUpload" } } } }, "409": { "description": "Object key already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}": { "delete": { "tags": [ "Objects" ], "operationId": "seren_storage_delete_object", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Storage object moved to trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/confirm-upload": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_confirm_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageConfirmObjectStorageUploadRequest" } } }, "required": true }, "responses": { "200": { "description": "Upload confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/copy": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_copy_object", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Source storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Source storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageCopyObjectStorageObjectRequest" } } }, "required": true }, "responses": { "201": { "description": "Storage object copied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } }, "409": { "description": "Destination key already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/download": { "get": { "tags": [ "Objects" ], "operationId": "seren_storage_download_object_by_id", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Download URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageDownload" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/move": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_move_object", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Source storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Source storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageMoveObjectStorageObjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Storage object moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } }, "409": { "description": "Destination key already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload": { "delete": { "tags": [ "Objects" ], "operationId": "seren_storage_abort_multipart_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Multipart upload aborted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload/complete": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_complete_multipart_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Multipart upload completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload/parts/{part_number}": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_create_multipart_part_upload", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "part_number", "in": "path", "description": "Multipart part number", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageCreateObjectStorageMultipartPartRequest" } } }, "required": true }, "responses": { "201": { "description": "Multipart part upload URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageMultipartPartUpload" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/restore": { "post": { "tags": [ "Objects" ], "operationId": "seren_storage_restore_object", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "object_id", "in": "path", "description": "Storage object ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Storage object restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageObject" } } } }, "409": { "description": "Object key is already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/workspace-snapshots": { "get": { "tags": [ "Workspaces" ], "operationId": "seren_storage_list_workspace_snapshots", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "deployment_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Workspace snapshots retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_Vec_ObjectStorageWorkspaceSnapshot" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Workspaces" ], "operationId": "seren_storage_create_workspace_snapshot", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageCreateObjectStorageWorkspaceSnapshotRequest" } } }, "required": true }, "responses": { "201": { "description": "Workspace snapshot registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageWorkspaceSnapshot" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/buckets/{bucket_slug}/workspace-snapshots/latest": { "get": { "tags": [ "Workspaces" ], "operationId": "seren_storage_latest_workspace_snapshot", "parameters": [ { "name": "bucket_slug", "in": "path", "description": "Storage bucket slug", "required": true, "schema": { "type": "string" } }, { "name": "deployment_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Latest workspace snapshot download created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageWorkspaceSnapshotDownload" } } } }, "404": { "description": "Workspace snapshot not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageErrorBody" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/publishers/seren-storage/health": { "get": { "tags": [ "Health" ], "operationId": "seren_storage_health", "responses": { "200": { "description": "Service health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_HealthStatus" } } } } } } }, "/publishers/seren-storage/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "seren_storage_serve_openapi", "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/publishers/seren-storage/usage": { "get": { "tags": [ "Objects" ], "operationId": "seren_storage_usage", "responses": { "200": { "description": "Organization storage usage retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerenStorageDataResponse_ObjectStorageUsage" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AcceptOrganizationInviteRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "AcceptOrganizationInviteResult": { "type": "object", "required": [ "organization_id", "organization_name", "role" ], "properties": { "affiliate_referral_code": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "role": { "type": "string" } } }, "AccountSecurity": { "type": "object", "description": "Response for GET /auth/account-security - account-level auth state for Settings.", "required": [ "has_password", "auth_providers" ], "properties": { "auth_providers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthProvider" }, "description": "Linked social login providers for this account." }, "has_password": { "type": "boolean", "description": "Whether this account can authenticate directly with an email/password." } } }, "AddPaymentMethodRequest": { "type": "object", "required": [ "stripe_payment_method_id", "set_as_default" ], "properties": { "set_as_default": { "type": "boolean" }, "stripe_payment_method_id": { "type": "string" } } }, "AgentCatalogEntry": { "type": "object", "description": "A single catalog entry. The four fields `organization_id`, `namespace`,\n`name`, and `version` together form the immutable identity of an entry.\n`tag` is an optional mutable pointer (for example `stable`) that resolves\nto the underlying version at lookup time.", "required": [ "id", "organization_id", "namespace", "name", "version", "kind", "description", "source", "labels", "annotations", "trust", "deprecated", "created_at", "updated_at" ], "properties": { "annotations": { "description": "Narrative key/value annotations; not indexed and not queryable." }, "category": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "deprecated": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/AgentCatalogEntryKind" }, "labels": { "description": "Queryable key/value labels (e.g. `team=platform`, `env=prod`)." }, "name": { "type": "string" }, "namespace": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "requires": { "$ref": "#/components/schemas/EntryRequires", "description": "Dependencies this entry requires to be useful. Typed so the control\nplane can validate references at apply time without parsing free-form\nJSON. Stored as JSONB; unknown fields are tolerated on read so a\nschema bump does not invalidate old rows." }, "source": { "description": "Where the artifact lives. Free-form JSON so we can evolve the source\nshape (`inline`, `git`, `registry`, ...) without further migrations." }, "tag": { "type": [ "string", "null" ] }, "trust": { "description": "Trust and provenance metadata (`author`, `maintained_by`, `license`,\n`last_audit_at`). Free-form for now; concrete shape comes later." }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } }, "AgentCatalogEntryCreateRequest": { "type": "object", "description": "Request body for creating or upserting a catalog entry. The control plane\nowns the `id`, `organization_id`, timestamps, and `created_by_user_id`.", "required": [ "name", "version", "kind" ], "properties": { "annotations": {}, "category": { "type": [ "string", "null" ] }, "deprecated": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/AgentCatalogEntryKind" }, "labels": {}, "name": { "type": "string" }, "namespace": { "type": [ "string", "null" ] }, "requires": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntryRequires" } ] }, "source": {}, "tag": { "type": [ "string", "null" ] }, "trust": {}, "version": { "type": "string" } }, "additionalProperties": false }, "AgentCatalogEntryKind": { "type": "string", "description": "Closed set of catalog entry kinds. New kinds should be added here only\nwhen there is a clear semantic distinction, not to model variants of an\nexisting kind.", "enum": [ "agent", "skill", "mcp_server", "prompt", "runtime_policy" ] }, "AgentCatalogEntryUpdateRequest": { "type": "object", "description": "Partial update for an existing entry. The identity tuple\n`(organization_id, namespace, name, version)` is fixed; only mutable fields\nmay change. To move a tag pointer set `tag` directly. To clear a tag set\n`clear_tag = true`.", "properties": { "annotations": {}, "category": { "type": [ "string", "null" ] }, "clear_category": { "type": "boolean" }, "clear_tag": { "type": "boolean" }, "deprecated": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "labels": {}, "requires": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntryRequires" } ] }, "source": {}, "tag": { "type": [ "string", "null" ] }, "trust": {} }, "additionalProperties": false }, "AgentCatalogListResponse": { "type": "object", "description": "Response wrapping a list of catalog entries.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCatalogEntry" } } } }, "AgentCatalogTagPromotionRequest": { "type": "object", "description": "Request body for atomic tag promotion. Moves a mutable tag pointer\n(`stable`, `canary`, ...) from one immutable version to another in a\nsingle transaction. Distinct from a generic update so the action is\nauditable as a promotion rather than an arbitrary edit.", "required": [ "from_version", "to_version", "tag" ], "properties": { "from_version": { "type": "string", "description": "Version that currently holds the tag. Must match the current pointer\nor the request fails so promotions are linearizable against caller\nstate." }, "tag": { "type": "string", "description": "Tag being promoted. Must match the catalog tag regex." }, "to_version": { "type": "string", "description": "Version that should hold the tag after the promotion completes." } }, "additionalProperties": false }, "AgentCredentialSecret": { "type": "object", "required": [ "id", "organization_id", "name", "scope", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "scope": { "$ref": "#/components/schemas/AgentCredentialSecretScope" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentCredentialSecretDeleted": { "type": "object", "required": [ "id", "deleted" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } }, "AgentCredentialSecretScope": { "type": "string", "enum": [ "organization", "user" ] }, "AgentCreditSource": { "type": "string", "description": "Source of an agent credit grant (fiat-only, no on-chain deposits)", "enum": [ "fiat_purchase", "signup_bonus", "payment_method_bonus", "daily_claim", "referral_reward", "admin_grant", "promo_code", "tier_bonus", "refund", "publisher_payout", "transfer_in", "transfer_recall", "transfer_refund" ] }, "AgentInfo": { "type": "object", "description": "Agent information returned on successful registration", "required": [ "id", "name", "email", "email_verified", "api_key", "organization_id", "status", "user_type", "created_at" ], "properties": { "api_key": { "type": "string", "description": "The full API key (seren__) - shown ONCE, save it immediately!" }, "created_at": { "type": "string", "format": "date-time", "description": "When the account was created" }, "email": { "type": "string", "description": "The verified-user email attached at signup" }, "email_verified": { "type": "boolean", "description": "Whether the email has been verified yet" }, "id": { "type": "string", "format": "uuid", "description": "The agent's unique ID" }, "name": { "type": "string", "description": "The agent's display name (auto-generated celestial name like \"radiant-sirius-a1b2\")" }, "organization_id": { "type": "string", "format": "uuid", "description": "The organization ID for API calls" }, "status": { "type": "string", "description": "Account status (always \"active\" for new agents)" }, "user_type": { "type": "string", "description": "Agent type (always \"agent\")" } } }, "AgentRegisterRequest": { "type": "object", "description": "Request to register a new AI agent account.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Real user-controlled email address for ownership verification." }, "name": { "type": [ "string", "null" ], "description": "Optional custom display name for the agent.\nIf not provided, a unique celestial-themed name will be generated (e.g., \"radiant-sirius\")." } } }, "AgentRegisterResponse": { "type": "object", "description": "Response from agent registration endpoint", "required": [ "success", "message", "verification_sent", "verification_required", "next_step", "agent", "setup", "skill_files" ], "properties": { "agent": { "$ref": "#/components/schemas/AgentInfo", "description": "The newly created agent account" }, "message": { "type": "string", "description": "Welcome message" }, "next_step": { "type": "string", "description": "Clear next-step guidance for the caller" }, "setup": { "$ref": "#/components/schemas/SetupInstructions", "description": "Setup instructions for getting started" }, "skill_files": { "$ref": "#/components/schemas/SkillFiles", "description": "Links to skill files and documentation" }, "success": { "type": "boolean", "description": "Whether registration was successful" }, "verification_required": { "type": "boolean", "description": "Whether the agent must verify the submitted email before ownership is confirmed" }, "verification_sent": { "type": "boolean", "description": "Whether a verification email was sent" } } }, "AgentTask": { "type": "object", "description": "An agent task — tracks a single agent invocation lifecycle.", "required": [ "id", "organization_id", "publisher_id", "user_id", "status", "trigger_type", "input_message", "cost_compute_atomic", "cost_tool_atomic", "cost_llm_atomic", "cost_total_atomic", "created_at", "updated_at" ], "properties": { "a2a_context_id": { "type": [ "string", "null" ] }, "a2a_task_id": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_cap_atomic": { "type": [ "integer", "null" ], "format": "int64" }, "cost_compute_atomic": { "type": "integer", "format": "int64" }, "cost_llm_atomic": { "type": "integer", "format": "int64" }, "cost_tool_atomic": { "type": "integer", "format": "int64" }, "cost_total_atomic": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "input_message": {}, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": {}, "payment_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/AgentTaskStatus" }, "trigger_type": { "$ref": "#/components/schemas/AgentTriggerType" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "AgentTaskEvent": { "type": "object", "description": "An event in the agent task lifecycle (for SSE streaming).", "required": [ "id", "task_id", "event_type", "payload", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "payload": {}, "task_id": { "type": "string", "format": "uuid" } } }, "AgentTaskStatus": { "type": "string", "description": "Agent task execution status, mirroring A2A TaskState with Seren additions.", "enum": [ "pending", "submitted", "working", "input_required", "completed", "failed", "canceled" ] }, "AgentTemplateSummary": { "type": "object", "description": "Summary view of agent template for catalog listing", "required": [ "id", "slug", "name", "language", "price_atomic", "is_verified", "total_invocations" ], "properties": { "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_verified": { "type": "boolean" }, "language": { "$ref": "#/components/schemas/TemplateLanguage" }, "name": { "type": "string" }, "price_atomic": { "type": "integer", "format": "int64" }, "publisher_name": { "type": [ "string", "null" ] }, "publisher_slug": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "total_invocations": { "type": "integer", "format": "int64" } } }, "AgentTriggerType": { "type": "string", "description": "How the agent task was triggered.", "enum": [ "manual", "api", "mcp", "cli", "desktop", "scheduled", "webhook" ] }, "AgentUpdateRequest": { "type": "object", "description": "Request to update an agent's profile.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address to set and verify.\nA verification email will be sent to this address." } } }, "ApiKeyCreated": { "type": "object", "description": "Response struct for API key creation (includes the full key ONCE)", "required": [ "id", "key_id", "name", "api_key", "organization_id", "key_type", "created_at" ], "properties": { "api_key": { "type": "string", "description": "The full API key (seren__) - shown ONCE." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string" }, "key_type": { "$ref": "#/components/schemas/ApiKeyType" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "ApiKeyInfo": { "type": "object", "description": "Response struct for listing API keys (never includes the secret)", "required": [ "id", "key_id", "name", "key_prefix", "organization_id", "key_type", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "key_type": { "$ref": "#/components/schemas/ApiKeyType" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "ApiKeyType": { "type": "string", "description": "Actor kind for an API key.", "enum": [ "user", "agent" ] }, "ApplyReferralRequest": { "type": "object", "description": "Request to apply a referral code", "required": [ "referral_code" ], "properties": { "referral_code": { "type": "string" } } }, "AssetInfo": { "type": "object", "description": "Minimal asset info for API responses", "required": [ "id", "symbol", "name", "decimals", "network_id", "network_name", "is_native", "is_stablecoin" ], "properties": { "contract_address": { "type": [ "string", "null" ] }, "decimals": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "is_native": { "type": "boolean" }, "is_stablecoin": { "type": "boolean" }, "name": { "type": "string" }, "network_id": { "type": "string" }, "network_name": { "type": "string" }, "symbol": { "type": "string" } } }, "AssignRoleRequest": { "type": "object", "description": "Request to assign a role to a member", "properties": { "role_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Either role_id or role_name must be provided" }, "role_name": { "type": [ "string", "null" ], "description": "Name of the role (owner, admin, editor, viewer, or custom role name)" } } }, "AuditLog": { "type": "object", "description": "Audit log entry from the database", "required": [ "id", "created_at", "actor_type", "action", "resource_type", "status" ], "properties": { "action": { "type": "string" }, "action_category": { "type": [ "string", "null" ] }, "actor_id": { "type": [ "string", "null" ], "format": "uuid" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": [ "string", "null" ] }, "metadata": {}, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "user_agent": { "type": [ "string", "null" ] } } }, "AuditLogList": { "type": "object", "description": "Response for listing audit logs", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "AuthProvider": { "type": "string", "description": "OAuth provider enum matching PostgreSQL enum", "enum": [ "google", "github", "microsoft", "apple" ] }, "BillingHealth": { "type": "object", "description": "High-level billing health summary.", "required": [ "daily_aggregation_ok", "has_recent_daily_run", "daily_aggregation_failures_total", "jobs" ], "properties": { "daily_aggregation_failures_total": { "type": "integer", "format": "int64", "description": "Total failures recorded for the daily aggregation job since process start.", "minimum": 0 }, "daily_aggregation_ok": { "type": "boolean", "description": "True when we have a recent daily aggregation run and no known failures." }, "has_recent_daily_run": { "type": "boolean", "description": "True when the last daily aggregation was within the expected window (<= 30h old)." }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/BillingJobHealth" }, "description": "Failure counters per billing job since process start." }, "last_daily_aggregation_run_utc": { "type": [ "string", "null" ], "description": "Last time daily_aggregated_usage was written, in UTC (RFC3339)." } } }, "BillingJobHealth": { "type": "object", "description": "Billing job health for a single background job.", "required": [ "job", "failures_total" ], "properties": { "failures_total": { "type": "integer", "format": "int64", "minimum": 0 }, "job": { "type": "string" } } }, "BonusClaimResponse": { "type": "object", "description": "Response for claiming bonuses", "required": [ "success", "amount_atomic", "amount_usd", "bonus_type" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "bonus_type": { "type": "string" }, "success": { "type": "boolean" } } }, "ChangePlanRequest": { "type": "object", "description": "Request to upgrade/downgrade an organization's plan", "required": [ "plan_id" ], "properties": { "plan_id": { "type": "string", "format": "uuid" }, "stripe_payment_method_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StripePaymentMethodId" } ] } } }, "CommunityPriorResponse": { "type": "object", "required": [ "alpha", "beta", "sample_size", "sufficient_population" ], "properties": { "alpha": { "type": "number", "format": "double" }, "beta": { "type": "number", "format": "double" }, "last_updated": { "type": [ "string", "null" ], "format": "date-time" }, "sample_size": { "type": "integer", "format": "int64" }, "sufficient_population": { "type": "boolean" } } }, "ComputeType": { "type": "string", "description": "Compute type - specific compute offering when publisher_category = Compute", "enum": [ "template", "workflow", "function", "agent" ] }, "ComputeUsageEventDebugRecord": { "type": "object", "description": "Debug view: compute_usage_events entry for an endpoint", "required": [ "event_type", "event_time" ], "properties": { "event_time": { "type": "string" }, "event_type": { "type": "string" } } }, "ConnectionsResponse": { "type": "object", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthConnectionResponse" } } } }, "ConsumptionPeriodData": { "type": "object", "description": "ConsumptionPeriodData for API responses (simplified)", "required": [ "period_id" ], "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "cloud_compute_cost_usd": { "type": "number", "format": "double" }, "cloud_compute_time_seconds": { "type": "number", "format": "double" }, "compute_time_seconds": { "type": "number", "format": "double" }, "data_transfer_bytes": { "type": "integer", "format": "int64" }, "period_id": { "type": "string" }, "serendb_compute_time_seconds": { "type": "number", "format": "double" }, "synthetic_storage_size_bytes": { "type": "integer", "format": "int64" }, "written_data_bytes": { "type": "integer", "format": "int64" } } }, "ConsumptionSummary": { "type": "object", "description": "ConsumptionSummary represents aggregated usage for a period", "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "cloud_compute_cost_usd": { "type": "number", "format": "double" }, "cloud_compute_time_seconds": { "type": "number", "format": "double" }, "compute_time_seconds": { "type": "number", "format": "double" }, "data_transfer_bytes": { "type": "integer", "format": "int64" }, "serendb_compute_time_seconds": { "type": "number", "format": "double" }, "synthetic_storage_size_bytes": { "type": "integer", "format": "int64" }, "written_data_bytes": { "type": "integer", "format": "int64" } } }, "CostEstimate": { "type": "object", "description": "Cost estimate breakdown", "required": [ "estimated_rows", "asset_symbol", "base_cost", "markup_multiplier", "min_charge", "total_cost", "total_cost_atomic" ], "properties": { "asset_symbol": { "type": "string", "description": "Asset symbol (e.g., USDC, USDT)" }, "base_cost": { "type": "string", "description": "Base cost in asset units (as decimal string)" }, "estimated_rows": { "type": "integer", "format": "int64", "description": "Estimated rows to be returned" }, "markup_multiplier": { "type": "string", "description": "Markup multiplier" }, "min_charge": { "type": "string", "description": "Minimum charge in asset units" }, "total_cost": { "type": "string", "description": "Total cost in asset units (as decimal string)" }, "total_cost_atomic": { "type": "integer", "format": "int64", "description": "Total cost in atomic units" } } }, "CreateApiKeyRequest": { "type": "object", "description": "Request to create a new API key", "required": [ "name" ], "properties": { "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `key_type` is `\"agent\"`. The Seren Secrets identity the agent acts as." }, "expires_in_days": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional lifetime in days. Values must be between 1 and 3650; omit for no expiration." }, "key_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiKeyType", "description": "Actor kind: omit or `\"user\"` for a normal CLI key; `\"agent\"` for an agent key." } ] }, "name": { "type": "string" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional least-privilege scopes. Omit for an unrestricted user API key.\nPublisher invocation scopes, `managed-deployment:`, and the\nexact publisher-administration scopes `organization:read`,\n`publisher-definition:{read,create,update}`, `publisher-pricing:update`,\n`oauth-provider:{read,create,update}`, and `oauth-connection:read` grant\nseparate capabilities and may be combined. No administration wildcard\nor delete scope is supported. Publisher create or update payloads that\nset pricing, billing, or accepted-asset fields also require\n`publisher-pricing:update`." } } }, "CreateChargeRequest": { "type": "object", "required": [ "agent_wallet", "amount_atomic", "description" ], "properties": { "agent_wallet": { "type": "string" }, "amount_atomic": { "type": "integer", "format": "int64" }, "description": { "type": "string" }, "idempotency_key": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreateOAuthProviderRequest": { "type": "object", "description": "Request to create/update an OAuth provider (admin only)", "required": [ "slug", "name", "authorization_url", "token_url", "client_id", "client_secret", "scopes" ], "properties": { "authorization_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Client secret (will be encrypted)" }, "custom_auth_params": { "description": "Custom provider-specific authorization URL parameters (e.g., {\"access_type\": \"offline\"} for Google)" }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pkce_required": { "type": "boolean" }, "revocation_url": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/TokenEndpointAuthMethod" }, "token_url": { "type": "string" }, "userinfo_url": { "type": [ "string", "null" ] } } }, "CreateOrganizationCustomSkillRequest": { "type": "object", "required": [ "slug", "display_name", "initial_revision" ], "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "initial_revision": { "$ref": "#/components/schemas/CreateOrganizationCustomSkillRevisionRequest" }, "slug": { "type": "string" } } }, "CreateOrganizationCustomSkillRevisionRequest": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationCustomSkillFileInput" } }, "publish": { "type": "boolean" } } }, "CreateOrganizationInviteRequest": { "type": "object", "description": "Request body for creating an organization invite.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the invitee." }, "role": { "type": [ "string", "null" ], "description": "Optional role for the invitee (defaults to member)." } } }, "CreateOrganizationVpcEndpointRequest": { "type": "object", "required": [ "region", "endpoint_id" ], "properties": { "endpoint_id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "region": { "type": "string" } } }, "CreatePayoutRequest": { "type": "object", "required": [ "destination_wallet", "amount_atomic", "description" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "description": { "type": "string" }, "destination_wallet": { "type": "string" }, "idempotency_key": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreatePublisherPayoutRequest": { "type": "object", "description": "Request to create a publisher payout.", "required": [ "asset_id" ], "properties": { "amount_atomic": { "type": [ "integer", "null" ], "format": "int64", "description": "Amount to withdraw in atomic units (defaults to max available)" }, "asset_id": { "type": "string", "format": "uuid", "description": "Asset to withdraw (must be an asset accepted by the publisher)" }, "destination_wallet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WalletAddress", "description": "Destination wallet override (defaults to the publisher's configured wallet)" } ] } } }, "CreatePublisherRequest": { "type": "object", "description": "Request to create a new publisher", "required": [ "name", "slug", "wallet_address", "wallet_network_id", "publisher_category" ], "properties": { "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (required for compute_type = agent)" }, "accepted_asset_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Asset IDs the publisher accepts for payment" }, "allowed_passthrough_headers": { "type": "array", "items": { "type": "string" }, "description": "Whitelist of agent-provided headers allowed to pass through to upstream" }, "api_headers": { "description": "Headers for API requests (will be encrypted)" }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": [ "string", "null" ], "description": "Upstream auth mode (\"static\", \"jwt\", \"oauth2_cc\", or \"passthrough\") (default: static)" }, "base_price_per_1000_rows": { "type": [ "string", "null" ] }, "billing_model": { "type": [ "string", "null" ], "description": "Billing model (\"x402_per_request\", \"prepaid_credits\", \"x402_passthrough\", \"pay_per_use\")" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (required for database_type = serendb)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching" }, "categories": { "type": "array", "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "database_config": { "description": "Provider-specific configuration\nFor connection_string auth: { \"connection_string\": \"postgresql://...\" }" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project (default: serendb)" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": [ "string", "null" ], "description": "Gateway fee percentage for upstream x402 payments (pass-through)." }, "grace_period_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "hourly_rate": { "type": [ "string", "null" ] }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "jwt_access_key": { "type": [ "string", "null" ], "description": "JWT access key / issuer claim (plaintext)" }, "jwt_algorithm": { "type": [ "string", "null" ], "description": "JWT signing algorithm (\"HS256\", \"HS384\", \"HS512\") (default: HS256)" }, "jwt_expiration_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "JWT expiration seconds (60-86400, default: 1800)" }, "jwt_secret_key": { "type": [ "string", "null" ], "description": "JWT secret key (will be encrypted)" }, "logo_url": { "type": [ "string", "null" ], "description": "Optional publisher branding URL" }, "low_balance_threshold": { "type": [ "string", "null" ] }, "markup_multiplier": { "type": [ "string", "null" ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "minimum_balance": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "oauth2_client_id": { "type": [ "string", "null" ], "description": "OAuth2 client ID for Client Credentials flow" }, "oauth2_client_secret": { "type": [ "string", "null" ], "description": "OAuth2 client secret for Client Credentials flow (will be encrypted)" }, "oauth2_scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth2 scopes to request during Client Credentials flow" }, "oauth2_token_url": { "type": [ "string", "null" ], "description": "OAuth2 token endpoint URL for Client Credentials flow" }, "oauth_provider_slug": { "type": [ "string", "null" ], "description": "OAuth provider slug for BYOC (Bring Your Own Credentials) authentication.\nWhen set along with requires_user_oauth=true, users must connect their own\nOAuth account before using this publisher." }, "ownership_tracking_enabled": { "type": [ "boolean", "null" ], "description": "Enable resource ownership tracking (legacy gateway parity)" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "price_per_call": { "type": [ "string", "null" ] }, "price_per_delete": { "type": [ "string", "null" ] }, "price_per_execution": { "type": [ "string", "null" ], "description": "Price per execution for agent templates or usage-based billing" }, "price_per_get": { "type": [ "string", "null" ] }, "price_per_patch": { "type": [ "string", "null" ] }, "price_per_post": { "type": [ "string", "null" ] }, "price_per_put": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (required for database_type = serendb)" }, "protected_operations": { "description": "Protected operations configuration - legacy, use endpoints[].is_protected instead" }, "publisher_category": { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute" }, "publisher_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublisherType" } ] }, "request_content_type": { "type": [ "string", "null" ], "description": "Content-Type for upstream API requests (default: application/json)" }, "requires_user_oauth": { "type": "boolean", "description": "If true, users must connect via OAuth before using this publisher (BYOC mode).\nRequires oauth_provider_slug to be set." }, "reserve_max_charge": { "type": [ "string", "null" ], "description": "Maximum amount to reserve up-front for pay_per_use pre-authorization." }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ], "description": "JSONPath to resource ID in response body (for ownership tracking)" }, "resource_id_url_pattern": { "type": [ "string", "null" ], "description": "URL pattern with :resourceId placeholder (for ownership tracking)" }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration for geo-restricted upstream APIs" } ] }, "slug": { "type": "string" }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds (60-86400, default: 3600)" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET, default: POST)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query (default: header)" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token (default: access_token)" }, "undocumented_endpoint_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog (\"allow\" or \"block\")" } ] }, "unresolved_fallback_charge": { "type": [ "string", "null" ], "description": "Fallback charge used when pay_per_use cost cannot be resolved from upstream response or token estimates." }, "upstream_api_key": { "type": [ "string", "null" ], "description": "Upstream static API key (will be encrypted)" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API (e.g., User-Agent)" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Human-readable use case descriptions" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress", "description": "Wallet address for receiving payments" }, "wallet_network_id": { "type": "string", "description": "Network ID for wallet (CAIP-2 format, e.g., \"eip155:8453\" for Base)" } } }, "CreateRoleRequest": { "type": "object", "description": "Request to create a custom role", "required": [ "name", "permissions" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "CreateTemplateRequest": { "type": "object", "description": "Request to create/publish an agent template", "required": [ "slug", "name", "code", "language", "price" ], "properties": { "code": { "type": "string", "description": "Template source code implementing run(input) -> output" }, "computeBackend": { "type": [ "string", "null" ], "description": "Preferred compute backend (e.g., \"daytona\", \"modal\"). If not specified, uses default." }, "dependencies": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Package dependencies (e.g., [\"requests\", \"openai\"])" }, "description": { "type": [ "string", "null" ], "description": "Description of what the template does" }, "language": { "$ref": "#/components/schemas/TemplateLanguage", "description": "Programming language (python, typescript, javascript)" }, "llmConfig": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmConfig", "description": "Optional LLM configuration" } ] }, "name": { "type": "string", "description": "Display name" }, "price": { "type": "string", "description": "Price per invocation (e.g., \"0.05\" for $0.05)" }, "settingsSchema": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TemplateSetting" }, "description": "Publisher-defined user-configurable settings schema" }, "slug": { "type": "string", "description": "URL-friendly slug (unique identifier)" } } }, "CreateTemplateResponse": { "type": "object", "description": "Response after creating a template", "required": [ "id", "slug", "name", "language", "priceAtomic", "isVerified", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "isVerified": { "type": "boolean" }, "language": { "$ref": "#/components/schemas/TemplateLanguage" }, "name": { "type": "string" }, "priceAtomic": { "type": "integer", "format": "int64" }, "slug": { "type": "string" } } }, "CreateWebhookRequest": { "type": "object", "description": "Request to create a webhook", "required": [ "name", "url", "events" ], "properties": { "events": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "url": { "type": "string" } } }, "CurrencyCode": { "type": "string", "description": "A validated currency code.\n\nSupports:\n- ISO 4217 fiat currencies (USD, EUR, GBP, etc.)\n- Common crypto currencies (USDC, SOL, ETH, etc.)\n\n# Examples\n\n```\nuse seren_core::models::CurrencyCode;\n\nlet usd = CurrencyCode::new(\"USD\").unwrap();\nlet usdc = CurrencyCode::new(\"USDC\").unwrap();\nassert!(CurrencyCode::new(\"invalid\").is_err());\n```", "example": "USD" }, "DailyClaimEligibilityResponse": { "type": "object", "description": "Response for daily claim eligibility check", "required": [ "can_claim", "claims_remaining_this_month" ], "properties": { "can_claim": { "type": "boolean" }, "claim_amount_usd": { "type": [ "string", "null" ], "description": "Formatted USD amount that will be granted on a successful daily claim.\nOptional to avoid breaking older clients." }, "claims_remaining_this_month": { "type": "integer", "format": "int32" }, "reason": { "type": [ "string", "null" ] }, "resets_in_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds until the daily claim resets (midnight UTC).\nOnly present when can_claim is false due to already claiming today." } } }, "DailyClaimResponse": { "type": "object", "description": "Response for claiming daily credits", "required": [ "success", "amount_atomic", "amount_usd", "balance_atomic", "balance_usd", "claims_remaining_this_month" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "balance_atomic": { "type": "integer", "format": "int64" }, "balance_usd": { "type": "string" }, "claims_remaining_this_month": { "type": "integer", "format": "int32" }, "success": { "type": "boolean" } } }, "DataResponse_AcceptOrganizationInviteResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "organization_name", "role" ], "properties": { "affiliate_referral_code": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "role": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AccountSecurity": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for GET /auth/account-security - account-level auth state for Settings.", "required": [ "has_password", "auth_providers" ], "properties": { "auth_providers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthProvider" }, "description": "Linked social login providers for this account." }, "has_password": { "type": "boolean", "description": "Whether this account can authenticate directly with an email/password." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentCatalogEntry": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A single catalog entry. The four fields `organization_id`, `namespace`,\n`name`, and `version` together form the immutable identity of an entry.\n`tag` is an optional mutable pointer (for example `stable`) that resolves\nto the underlying version at lookup time.", "required": [ "id", "organization_id", "namespace", "name", "version", "kind", "description", "source", "labels", "annotations", "trust", "deprecated", "created_at", "updated_at" ], "properties": { "annotations": { "description": "Narrative key/value annotations; not indexed and not queryable." }, "category": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "deprecated": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/AgentCatalogEntryKind" }, "labels": { "description": "Queryable key/value labels (e.g. `team=platform`, `env=prod`)." }, "name": { "type": "string" }, "namespace": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "requires": { "$ref": "#/components/schemas/EntryRequires", "description": "Dependencies this entry requires to be useful. Typed so the control\nplane can validate references at apply time without parsing free-form\nJSON. Stored as JSONB; unknown fields are tolerated on read so a\nschema bump does not invalidate old rows." }, "source": { "description": "Where the artifact lives. Free-form JSON so we can evolve the source\nshape (`inline`, `git`, `registry`, ...) without further migrations." }, "tag": { "type": [ "string", "null" ] }, "trust": { "description": "Trust and provenance metadata (`author`, `maintained_by`, `license`,\n`last_audit_at`). Free-form for now; concrete shape comes later." }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentCatalogListResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response wrapping a list of catalog entries.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCatalogEntry" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentCredentialSecret": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "name", "scope", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "scope": { "$ref": "#/components/schemas/AgentCredentialSecretScope" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentCredentialSecretDeleted": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentRegisterResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response from agent registration endpoint", "required": [ "success", "message", "verification_sent", "verification_required", "next_step", "agent", "setup", "skill_files" ], "properties": { "agent": { "$ref": "#/components/schemas/AgentInfo", "description": "The newly created agent account" }, "message": { "type": "string", "description": "Welcome message" }, "next_step": { "type": "string", "description": "Clear next-step guidance for the caller" }, "setup": { "$ref": "#/components/schemas/SetupInstructions", "description": "Setup instructions for getting started" }, "skill_files": { "$ref": "#/components/schemas/SkillFiles", "description": "Links to skill files and documentation" }, "success": { "type": "boolean", "description": "Whether registration was successful" }, "verification_required": { "type": "boolean", "description": "Whether the agent must verify the submitted email before ownership is confirmed" }, "verification_sent": { "type": "boolean", "description": "Whether a verification email was sent" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AgentTask": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "An agent task — tracks a single agent invocation lifecycle.", "required": [ "id", "organization_id", "publisher_id", "user_id", "status", "trigger_type", "input_message", "cost_compute_atomic", "cost_tool_atomic", "cost_llm_atomic", "cost_total_atomic", "created_at", "updated_at" ], "properties": { "a2a_context_id": { "type": [ "string", "null" ] }, "a2a_task_id": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_cap_atomic": { "type": [ "integer", "null" ], "format": "int64" }, "cost_compute_atomic": { "type": "integer", "format": "int64" }, "cost_llm_atomic": { "type": "integer", "format": "int64" }, "cost_tool_atomic": { "type": "integer", "format": "int64" }, "cost_total_atomic": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "input_message": {}, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": {}, "payment_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/AgentTaskStatus" }, "trigger_type": { "$ref": "#/components/schemas/AgentTriggerType" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ApiKeyCreated": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response struct for API key creation (includes the full key ONCE)", "required": [ "id", "key_id", "name", "api_key", "organization_id", "key_type", "created_at" ], "properties": { "api_key": { "type": "string", "description": "The full API key (seren__) - shown ONCE." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string" }, "key_type": { "$ref": "#/components/schemas/ApiKeyType" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ApiKeyInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response struct for listing API keys (never includes the secret)", "required": [ "id", "key_id", "name", "key_prefix", "organization_id", "key_type", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "key_type": { "$ref": "#/components/schemas/ApiKeyType" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AuditLog": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Audit log entry from the database", "required": [ "id", "created_at", "actor_type", "action", "resource_type", "status" ], "properties": { "action": { "type": "string" }, "action_category": { "type": [ "string", "null" ] }, "actor_id": { "type": [ "string", "null" ], "format": "uuid" }, "actor_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": [ "string", "null" ] }, "metadata": {}, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "user_agent": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AuditLogList": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for listing audit logs", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BillingHealth": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "High-level billing health summary.", "required": [ "daily_aggregation_ok", "has_recent_daily_run", "daily_aggregation_failures_total", "jobs" ], "properties": { "daily_aggregation_failures_total": { "type": "integer", "format": "int64", "description": "Total failures recorded for the daily aggregation job since process start.", "minimum": 0 }, "daily_aggregation_ok": { "type": "boolean", "description": "True when we have a recent daily aggregation run and no known failures." }, "has_recent_daily_run": { "type": "boolean", "description": "True when the last daily aggregation was within the expected window (<= 30h old)." }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/BillingJobHealth" }, "description": "Failure counters per billing job since process start." }, "last_daily_aggregation_run_utc": { "type": [ "string", "null" ], "description": "Last time daily_aggregated_usage was written, in UTC (RFC3339)." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BonusClaimResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for claiming bonuses", "required": [ "success", "amount_atomic", "amount_usd", "bonus_type" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "bonus_type": { "type": "string" }, "success": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CommunityPriorResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "alpha", "beta", "sample_size", "sufficient_population" ], "properties": { "alpha": { "type": "number", "format": "double" }, "beta": { "type": "number", "format": "double" }, "last_updated": { "type": [ "string", "null" ], "format": "date-time" }, "sample_size": { "type": "integer", "format": "int64" }, "sufficient_population": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CreateTemplateResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating a template", "required": [ "id", "slug", "name", "language", "priceAtomic", "isVerified", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "isVerified": { "type": "boolean" }, "language": { "$ref": "#/components/schemas/TemplateLanguage" }, "name": { "type": "string" }, "priceAtomic": { "type": "integer", "format": "int64" }, "slug": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_DailyClaimEligibilityResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for daily claim eligibility check", "required": [ "can_claim", "claims_remaining_this_month" ], "properties": { "can_claim": { "type": "boolean" }, "claim_amount_usd": { "type": [ "string", "null" ], "description": "Formatted USD amount that will be granted on a successful daily claim.\nOptional to avoid breaking older clients." }, "claims_remaining_this_month": { "type": "integer", "format": "int32" }, "reason": { "type": [ "string", "null" ] }, "resets_in_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds until the daily claim resets (midnight UTC).\nOnly present when can_claim is false due to already claiming today." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_DailyClaimResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for claiming daily credits", "required": [ "success", "amount_atomic", "amount_usd", "balance_atomic", "balance_usd", "claims_remaining_this_month" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "balance_atomic": { "type": "integer", "format": "int64" }, "balance_usd": { "type": "string" }, "claims_remaining_this_month": { "type": "integer", "format": "int32" }, "success": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_DepositResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for wallet deposit initiation", "required": [ "deposit_id", "checkout_url", "amount_atomic", "bonus_atomic", "total_atomic", "amount_usd", "bonus_usd", "total_usd" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64", "description": "Base deposit amount in atomic units" }, "amount_usd": { "type": "string" }, "bonus_atomic": { "type": "integer", "format": "int64", "description": "Tier bonus in atomic units (if applicable)" }, "bonus_usd": { "type": "string" }, "checkout_url": { "type": "string", "description": "URL to the Stripe hosted checkout page - open this in a browser to complete payment" }, "deposit_id": { "type": "string", "format": "uuid" }, "total_atomic": { "type": "integer", "format": "int64", "description": "Total to be credited in atomic units" }, "total_usd": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_EndpointBillingEvents": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Combined debug response for an endpoint's billing events", "required": [ "organization_id", "endpoint_id", "usage_events", "compute_usage_events" ], "properties": { "compute_usage_events": { "type": "array", "items": { "$ref": "#/components/schemas/ComputeUsageEventDebugRecord" } }, "endpoint_id": { "type": "string" }, "organization_id": { "type": "string" }, "usage_events": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEventDebugRecord" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_EvalMatrixResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "matrix", "generated_at", "total_signals" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "matrix": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EvalMatrixEntry" }, "propertyNames": { "type": "string" } }, "propertyNames": { "type": "string" } }, "total_signals": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_EvalSignalResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "accepted", "rejected" ], "properties": { "accepted": { "type": "integer", "format": "int64" }, "rejected": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_FederatedResourceResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for a single federated resource", "required": [ "id", "publisher_id", "resource_type", "external_id", "metadata", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_FederationHistoryStatsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for federation history aggregate statistics.", "required": [ "total_events", "unique_resources", "unique_publishers", "by_operation", "by_type", "by_status" ], "properties": { "by_operation": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_type": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "total_events": { "type": "integer", "format": "int64" }, "unique_publishers": { "type": "integer", "format": "int64" }, "unique_resources": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_FederationStatsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for federation statistics", "required": [ "total_active", "by_type", "by_status" ], "properties": { "by_status": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_type": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "total_active": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Invoice": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Invoice response with line items", "required": [ "id", "organization_id", "invoice_number", "period_start", "period_end", "subtotal_usd", "tax_usd", "total_usd", "status", "line_items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "organization_id": { "type": "string", "format": "uuid" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "status": { "type": "string" }, "subtotal_usd": { "type": "string" }, "tax_usd": { "type": "string" }, "total_usd": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_InvoicesGenerated": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for invoice generation", "required": [ "invoice_ids", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_InvokeTemplateResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response from invoking a template", "required": [ "result", "cost", "executionTimeMs", "invocationId" ], "properties": { "cost": { "$ref": "#/components/schemas/InvocationCostBreakdown", "description": "Cost breakdown" }, "executionTimeMs": { "type": "integer", "format": "int32", "description": "Execution time in milliseconds" }, "invocationId": { "type": "string", "format": "uuid", "description": "Invocation ID for tracking" }, "result": { "description": "Output from template execution" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_LoginResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "access_token", "refresh_token", "expires_in", "user", "default_organization_id" ], "properties": { "access_token": { "type": "string" }, "default_organization_id": { "type": "string", "format": "uuid", "description": "The user's default organization ID for API calls requiring an organization context.\nThis is typically the first organization the user joined (their personal org)." }, "expires_in": { "type": "integer", "format": "int64" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfo" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_LogoUploadResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Logo upload response", "required": [ "message", "logo_url" ], "properties": { "logo_url": { "type": "string", "description": "URL to access the uploaded logo" }, "message": { "type": "string", "description": "Message indicating success" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_LogoutResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_NotificationReadResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "notification_id", "read_at" ], "properties": { "notification_id": { "type": "string", "format": "uuid" }, "read_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OAuthProviderResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response type for OAuth provider (excludes sensitive fields like client_secret)", "required": [ "id", "slug", "name", "authorization_url", "token_url", "client_id", "scopes", "pkce_required", "token_endpoint_auth_method", "is_active", "created_at", "updated_at" ], "properties": { "authorization_url": { "type": "string" }, "client_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "pkce_required": { "type": "boolean" }, "revocation_url": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" }, "token_url": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "userinfo_url": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationConsumption": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "OrganizationConsumption wraps organization-wide consumption", "required": [ "organization_id", "from", "to", "periods", "current_month" ], "properties": { "current_month": { "$ref": "#/components/schemas/ConsumptionSummary" }, "from": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionPeriodData" } }, "to": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationCustomSkill": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "slug", "display_name", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "latest_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "latest_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "published_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationCustomSkillFileContent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "revision_id", "relative_path", "content_type", "size_bytes", "sha256", "content_base64", "is_text" ], "properties": { "content_base64": { "type": "string" }, "content_type": { "type": "string" }, "is_text": { "type": "boolean" }, "relative_path": { "type": "string" }, "revision_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationCustomSkillRevision": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_custom_skill_id", "organization_id", "revision_number", "status", "skill_md", "skill_md_sha256", "frontmatter", "manifest", "bundle_sha256", "bundle_size_bytes", "created_at", "files" ], "properties": { "bundle_artifact_key": { "type": [ "string", "null" ] }, "bundle_sha256": { "type": "string" }, "bundle_size_bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationCustomSkillFileMetadata" } }, "frontmatter": {}, "id": { "type": "string", "format": "uuid" }, "manifest": {}, "organization_custom_skill_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision_number": { "type": "integer", "format": "int64" }, "skill_md": { "type": "string" }, "skill_md_sha256": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionStatus" }, "title": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationEmployeeCollaborationAssignment": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "deployment_id", "agent_identity_id", "assignment_generation", "organization_knowledge_read", "organization_credential_use", "organization_skill_use", "organization_artifact_write", "allowed_task_labels", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "assignment_generation": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "granted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationEmployeeCollaborationPolicy": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "policy_revision", "enabled", "organization_knowledge_read", "organization_credential_use", "organization_skill_use", "organization_artifact_write", "updated_at" ], "properties": { "enabled": { "type": "boolean", "description": "Organization collaboration is unavailable unless explicitly enabled." }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" }, "policy_revision": { "type": "string", "description": "Opaque revision rotated only when the effective policy changes." }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationInvite": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response type for organization invites (token is not exposed over the API).", "required": [ "id", "organization_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "email": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ] }, "role": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationMemoryCapturePolicy": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "policy_version", "capture_enabled", "retain_source_allowed", "capture_user_prompts", "capture_assistant_responses", "max_transcript_bytes", "cache_ttl_seconds", "offline_grace_seconds", "allowed_agent_platforms", "updated_at" ], "properties": { "allowed_agent_platforms": { "type": "array", "items": { "type": "string" }, "description": "Empty permits every supported platform; otherwise names are lowercase." }, "cache_ttl_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "capture_assistant_responses": { "type": "boolean" }, "capture_enabled": { "type": "boolean" }, "capture_user_prompts": { "type": "boolean" }, "max_transcript_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "offline_grace_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "organization_id": { "type": "string", "format": "uuid" }, "policy_version": { "type": "string", "description": "Opaque revision that automatic capture submissions must present. It\nchanges only when the effective policy changes." }, "retain_source_allowed": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationOtpEnrollmentChallenge": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "user_id", "enrollment_status", "issuer", "account_name", "manual_entry_key", "otpauth_uri" ], "properties": { "account_name": { "type": "string" }, "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "issuer": { "type": "string" }, "manual_entry_key": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "otpauth_uri": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationOtpPolicy": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "enabled_scopes", "default_verification_ttl", "updated_at" ], "properties": { "default_verification_ttl": { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" }, "enabled_scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScope" } }, "organization_id": { "type": "string", "format": "uuid" }, "ttl_overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScopePolicy" } }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationOtpResetResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "user_id", "enrollment_status" ], "properties": { "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "organization_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationOtpStatus": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "user_id", "scope", "is_scope_protected", "enrollment_status", "verification_required", "verification_ttl" ], "properties": { "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "is_scope_protected": { "type": "boolean" }, "locked_until": { "type": [ "string", "null" ], "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "scope": { "$ref": "#/components/schemas/OrganizationOtpScope" }, "user_id": { "type": "string", "format": "uuid" }, "verification_required": { "type": "boolean" }, "verification_ttl": { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" }, "verified_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationPlanWithDetails": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response type that includes both the plan and organization_plan details", "required": [ "organization_plan", "plan" ], "properties": { "organization_plan": { "$ref": "#/components/schemas/OrganizationPlan" }, "plan": { "$ref": "#/components/schemas/Plan" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationPrivateModelsPolicy": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "mode", "data_handling_attestation", "updated_at" ], "properties": { "allow_claude_agent": { "type": "boolean" }, "allow_cloud_agent_launch": { "type": "boolean" }, "allow_codex_agent": { "type": "boolean" }, "allow_seren_agent": { "type": "boolean" }, "allow_seren_private_agent": { "type": "boolean" }, "data_handling_attestation": { "$ref": "#/components/schemas/PrivateModelsDataHandlingAttestation", "description": "Machine-readable training and retention declaration for organization private-model inference. Clients requiring confidentiality must deny access unless the status and terms are affirmative." }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "deployment_name": { "type": [ "string", "null" ] }, "disable_external_model_providers": { "type": "boolean" }, "disable_local_agents": { "type": "boolean" }, "disable_seren_models": { "type": "boolean" }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "global_ordered_model_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hide_model_picker": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/OrganizationPrivateModelsMode" }, "model_id": { "type": [ "string", "null" ] }, "ordered_model_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "organization_id": { "type": "string", "format": "uuid" }, "private_output_policy": { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase" } ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_OrganizationVpcEndpoint": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "region", "endpoint_id", "state", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "endpoint_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "region": { "type": "string" }, "state": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PasswordReset": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PasswordResetSent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PasswordUpdated": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PaymentHistory": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Payment history response", "required": [ "payments" ], "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRecord" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PaymentIntentCreated": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for creating a payment intent", "required": [ "payment_intent_id", "client_secret", "amount_cents", "amount_usd", "currency" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "description": "Amount to be charged, in cents." }, "amount_usd": { "type": "string", "description": "Amount to be charged, in USD." }, "client_secret": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "payment_intent_id": { "$ref": "#/components/schemas/StripePaymentIntentId" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PaymentMethodAdded": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for adding a payment method", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Plan": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Plan represents a subscription tier (Free, Launch, Scale)", "required": [ "id", "name", "display_name", "price_monthly", "max_compute_units", "max_branches_per_project", "support_level", "ip_allowlist_enabled", "vpc_enabled", "sso_enabled", "audit_logs_enabled", "monitoring_enabled", "is_active", "sort_order", "created_at", "updated_at" ], "properties": { "audit_logs_enabled": { "type": "boolean" }, "branch_price_per_hour": { "type": [ "string", "null" ] }, "compute_hours_quota": { "type": [ "integer", "null" ], "format": "int32" }, "compute_price_per_cu_hour": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "data_transfer_gb_included": { "type": [ "integer", "null" ], "format": "int32" }, "data_transfer_price_per_gb": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "ip_allowlist_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "max_branches_per_project": { "type": "integer", "format": "int32" }, "max_compute_units": { "type": "integer", "format": "int32" }, "max_databases_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_endpoints_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_projects": { "type": [ "integer", "null" ], "format": "int32" }, "monitoring_enabled": { "type": "boolean" }, "monitoring_retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "pitr_price_per_gb_month": { "type": [ "string", "null" ] }, "pitr_retention_hours": { "type": [ "integer", "null" ], "format": "int32" }, "price_monthly": { "type": "string" }, "scale_to_zero_delay_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "sla_uptime_percent": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer", "format": "int32" }, "sso_enabled": { "type": "boolean" }, "storage_gb_quota": { "type": [ "string", "null" ] }, "storage_price_per_gb_month": { "type": [ "string", "null" ] }, "stripe_price_id": { "type": [ "string", "null" ], "description": "Stripe Price ID used for recurring subscriptions on this plan (for paid tiers)." }, "support_level": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vpc_enabled": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PricingConfigResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Pricing config response", "required": [ "asset_id", "pricing_model", "base_price_per_1000_rows", "markup_multiplier", "min_charge", "payment_expiry_minutes", "prepaid_enabled", "onchain_enabled", "minimum_balance", "low_balance_threshold" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "description": "Asset this pricing applies to" }, "asset_symbol": { "type": [ "string", "null" ], "description": "Asset symbol for display" }, "base_price_per_1000_rows": { "type": "string" }, "grace_period_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "hourly_rate": { "type": [ "string", "null" ] }, "low_balance_threshold": { "type": "string" }, "markup_multiplier": { "type": "string" }, "max_queries_per_minute": { "type": [ "integer", "null" ], "format": "int32" }, "min_charge": { "type": "string" }, "min_display_price": { "type": [ "string", "null" ], "description": "Minimum price to display in UI for passthrough publishers (informational only)" }, "minimum_balance": { "type": "string" }, "onchain_enabled": { "type": "boolean" }, "payment_expiry_minutes": { "type": "integer", "format": "int32" }, "prepaid_enabled": { "type": "boolean" }, "price_per_call": { "type": [ "string", "null" ] }, "price_per_delete": { "type": [ "string", "null" ] }, "price_per_execution": { "type": [ "string", "null" ], "description": "Price per execution for agent templates or usage-based billing" }, "price_per_get": { "type": [ "string", "null" ] }, "price_per_patch": { "type": [ "string", "null" ] }, "price_per_post": { "type": [ "string", "null" ] }, "price_per_put": { "type": [ "string", "null" ] }, "pricing_display_text": { "type": [ "string", "null" ], "description": "Text to display for variable pricing (e.g., \"Varies by model\")" }, "pricing_model": { "$ref": "#/components/schemas/PricingModel" }, "reserve_max_charge": { "type": [ "string", "null" ] }, "unresolved_fallback_charge": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherAgentBalance": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "serenbucks_atomic", "total_available_atomic" ], "properties": { "onchain_atomic": { "type": [ "integer", "null" ], "format": "int64" }, "serenbucks_atomic": { "type": "integer", "format": "int64" }, "total_available_atomic": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherAnalytics": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for publisher analytics", "required": [ "publisher_id", "templates", "totals" ], "properties": { "publisher_id": { "type": "string", "format": "uuid" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateAnalytics" } }, "totals": { "$ref": "#/components/schemas/PublisherAnalyticsTotals" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherChargeInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "amount_atomic", "agent_wallet" ], "properties": { "agent_wallet": { "type": "string" }, "amount_atomic": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherPayoutInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "amount_atomic", "destination_wallet" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "destination_wallet": { "type": "string" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherPayoutResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Publisher payout response.", "required": [ "id", "publisher_id", "asset", "amount", "amount_atomic", "destination_wallet", "status", "requested_at" ], "properties": { "amount": { "type": "number", "format": "double" }, "amount_atomic": { "type": "integer", "format": "int64" }, "asset": { "$ref": "#/components/schemas/AssetInfo" }, "destination_wallet": { "$ref": "#/components/schemas/WalletAddress" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "tx_hash": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublisherResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Publisher response (excludes sensitive fields)", "required": [ "id", "name", "slug", "categories", "capabilities", "use_cases", "publisher_type", "wallet_address", "wallet_network_id", "publisher_category", "billing_model", "gateway_fee_percent", "auth_type", "allowed_passthrough_headers", "passthrough_header_rewrite", "request_content_type", "upstream_headers", "ownership_tracking_enabled", "undocumented_endpoint_policy", "is_active", "is_verified", "total_queries", "unique_agents_served", "total_revenue_atomic", "created_at", "updated_at", "requires_user_oauth" ], "properties": { "a2a_agent_card": { "description": "Cached A2A agent card" }, "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (for compute_type = agent)" }, "a2a_health_status": { "type": [ "string", "null" ], "description": "A2A health status: unknown, healthy, unhealthy, unreachable" }, "accepted_assets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssetInfo" }, "description": "Accepted assets for payment" }, "allowed_passthrough_headers": { "type": "array", "items": { "type": "string" } }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\", \"apiKey\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": "string", "description": "Upstream authentication mode." }, "billing_model": { "type": "string" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (for database_type = serendb)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching" }, "categories": { "type": "array", "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "created_at": { "type": "string", "format": "date-time" }, "database_config": { "description": "Provider config (sensitive fields redacted)" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "is_active": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "mcp_capabilities": { "description": "Cached MCP capabilities (tools, resources, prompts)" }, "mcp_discovery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpDiscoveryStatus", "description": "Last MCP discovery attempt, success, and error state." } ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "name": { "type": "string" }, "oauth_provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication" }, "ownership_tracking_enabled": { "type": "boolean" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "pricing": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PricingConfigResponse" }, "description": "Pricing config per asset (if included)" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (for database_type = serendb)" }, "protected_operations": {}, "publisher_category": { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute" }, "publisher_type": { "$ref": "#/components/schemas/PublisherType" }, "request_content_type": { "type": "string", "description": "Content-Type for upstream API requests" }, "requires_user_oauth": { "type": "boolean", "description": "If true, users must connect via OAuth before using this publisher" }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ] }, "resource_id_url_pattern": { "type": [ "string", "null" ] }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration (if publisher has geo-restricted upstream API)" } ] }, "slug": { "type": "string" }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token" }, "total_queries": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Lifetime total revenue across all assets, in atomic units" }, "undocumented_endpoint_policy": { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog" }, "unique_agents_served": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Human-readable use case descriptions" }, "verification_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When verification expires (NULL = no expiry)" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" }, "wallet_network_id": { "type": "string", "description": "Network for the wallet address" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_QuotaUsage": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Quota usage summary for an organization", "required": [ "organization_id", "plan", "current_storage_gb", "current_compute_hours", "current_serendb_compute_hours", "current_cloud_compute_hours", "current_projects", "current_branches", "is_over_storage_quota", "is_over_compute_quota", "is_over_projects_quota" ], "properties": { "compute_hours_usage_percent": { "type": [ "number", "null" ], "format": "double" }, "current_branches": { "type": "integer", "format": "int32" }, "current_cloud_compute_hours": { "type": "number", "format": "double" }, "current_compute_hours": { "type": "number", "format": "double" }, "current_projects": { "type": "integer", "format": "int32" }, "current_serendb_compute_hours": { "type": "number", "format": "double" }, "current_storage_gb": { "type": "number", "format": "double" }, "is_over_compute_quota": { "type": "boolean" }, "is_over_projects_quota": { "type": "boolean" }, "is_over_storage_quota": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "plan": { "$ref": "#/components/schemas/Plan" }, "projects_usage_percent": { "type": [ "number", "null" ], "format": "double" }, "storage_usage_percent": { "type": [ "number", "null" ], "format": "double" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_RbacRole": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating or updating a role", "required": [ "id", "name", "is_built_in", "permissions", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_built_in": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_RecoveryResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for recovery setup", "required": [ "has_recovery", "has_recovery_email", "message" ], "properties": { "has_recovery": { "type": "boolean", "description": "Whether recovery is now set up" }, "has_recovery_email": { "type": "boolean", "description": "Whether a recovery email is set" }, "message": { "type": "string", "description": "Message about recovery status" }, "recovery_code": { "type": [ "string", "null" ], "description": "Recovery code (only shown once, save it securely!)\nThis is a 24-character code that can be used to recover your account." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ReferralInfoResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for referral info", "required": [ "referral_code", "referral_url", "total_referrals", "total_earnings_atomic", "total_earnings_usd", "pending_earnings_atomic", "pending_earnings_usd" ], "properties": { "pending_earnings_atomic": { "type": "integer", "format": "int64" }, "pending_earnings_usd": { "type": "string" }, "referral_code": { "type": "string" }, "referral_url": { "type": "string" }, "total_earnings_atomic": { "type": "integer", "format": "int64" }, "total_earnings_usd": { "type": "string" }, "total_referrals": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_RevenueMetrics": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Revenue metrics with period-over-period comparison.", "required": [ "total_revenue_atomic", "total_revenue", "active_agents", "total_queries", "avg_query_cost_atomic", "revenue_change_pct", "agents_change_pct", "queries_change_pct", "period_start", "period_end" ], "properties": { "active_agents": { "type": "integer", "format": "int64", "description": "Number of active agents in the period" }, "agents_change_pct": { "type": "integer", "format": "int32", "description": "Agent count change from previous period (percentage)" }, "avg_query_cost_atomic": { "type": "integer", "format": "int64", "description": "Average query cost (atomic units)" }, "period_end": { "type": "string", "description": "Period end date (ISO 8601)" }, "period_start": { "type": "string", "description": "Period start date (ISO 8601)" }, "queries_change_pct": { "type": "integer", "format": "int32", "description": "Query count change from previous period (percentage)" }, "revenue_change_pct": { "type": "integer", "format": "int32", "description": "Revenue change from previous period (percentage, e.g., 15 = +15%)" }, "total_queries": { "type": "integer", "format": "int64", "description": "Total queries executed in the period" }, "total_revenue": { "type": "string", "description": "Total revenue as decimal string" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Total revenue in the period (atomic units)" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_SessionsRevoked": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message", "revoked_count" ], "properties": { "message": { "type": "string" }, "revoked_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_SettlementReceiptResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Settlement state for one priced publisher operation.", "required": [ "receipt_id", "status", "asset", "updated_at" ], "properties": { "asset": { "type": "string" }, "charged_micros": { "type": [ "integer", "null" ], "format": "int64", "description": "Gross settled cost in micro-units of the named asset.\n\nPending receipts report no settled amount. Cancelled and expired receipts\nreport zero. Refunded receipts retain the original gross cost.", "minimum": 0 }, "receipt_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_SignupResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "user", "message" ], "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfo" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_SuggestResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for suggest endpoint\nReturns publisher and agent recommendations based on task/query matching", "required": [ "publishers", "agents" ], "properties": { "agents": { "type": "array", "items": {}, "description": "Matched agents sorted by relevance (agent templates coming soon)" }, "publishers": { "type": "array", "items": { "$ref": "#/components/schemas/PublisherSuggestion" }, "description": "Matched publishers sorted by relevance" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_TokenRefresh": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "access_token", "refresh_token", "expires_in" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" }, "refresh_token": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_TransactionSummaryResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Summary statistics for transactions in a date range", "required": [ "starting_balance_atomic", "starting_balance_usd", "total_credits_atomic", "total_credits_usd", "total_debits_atomic", "total_debits_usd", "net_change_atomic", "net_change_usd", "ending_balance_atomic", "ending_balance_usd", "transaction_count" ], "properties": { "ending_balance_atomic": { "type": "integer", "format": "int64", "description": "Wallet balance at the end of the selected period" }, "ending_balance_usd": { "type": "string" }, "net_change_atomic": { "type": "integer", "format": "int64", "description": "Net change (credits - debits, can be negative)" }, "net_change_usd": { "type": "string" }, "period_end": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "starting_balance_atomic": { "type": "integer", "format": "int64", "description": "Wallet balance immediately before the period start" }, "starting_balance_usd": { "type": "string" }, "total_credits_atomic": { "type": "integer", "format": "int64", "description": "Total credits received in the period (positive)" }, "total_credits_usd": { "type": "string" }, "total_debits_atomic": { "type": "integer", "format": "int64", "description": "Total debits spent in the period (positive number representing absolute spend)" }, "total_debits_usd": { "type": "string" }, "transaction_count": { "type": "integer", "format": "int64", "description": "Total number of transactions in the period" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_UserMe": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/UserInfo" }, { "type": "object", "required": [ "default_organization_id" ], "properties": { "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present when the API key is bound to an agent identity." }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present when /auth/me is authenticated by an API key." }, "api_key_scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Normalized least-privilege scopes for a restricted API key. Omitted for\nsigned user sessions and unrestricted user API keys." }, "api_key_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiKeyType", "description": "Present when /auth/me is authenticated by an API key." } ] }, "default_organization_id": { "type": "string", "format": "uuid", "description": "The user's default organization ID for API calls requiring an organization context.\nThis is typically the first organization the user joined (their personal org)." } } } ], "description": "Response for GET /auth/me - current user info with default organization" }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_AgentCredentialSecret": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "name", "scope", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "scope": { "$ref": "#/components/schemas/AgentCredentialSecretScope" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_AgentTask": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An agent task — tracks a single agent invocation lifecycle.", "required": [ "id", "organization_id", "publisher_id", "user_id", "status", "trigger_type", "input_message", "cost_compute_atomic", "cost_tool_atomic", "cost_llm_atomic", "cost_total_atomic", "created_at", "updated_at" ], "properties": { "a2a_context_id": { "type": [ "string", "null" ] }, "a2a_task_id": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_cap_atomic": { "type": [ "integer", "null" ], "format": "int64" }, "cost_compute_atomic": { "type": "integer", "format": "int64" }, "cost_llm_atomic": { "type": "integer", "format": "int64" }, "cost_tool_atomic": { "type": "integer", "format": "int64" }, "cost_total_atomic": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "input_message": {}, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": {}, "payment_request_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/AgentTaskStatus" }, "trigger_type": { "$ref": "#/components/schemas/AgentTriggerType" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_AgentTaskEvent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An event in the agent task lifecycle (for SSE streaming).", "required": [ "id", "task_id", "event_type", "payload", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "payload": {}, "task_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_AgentTemplateSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Summary view of agent template for catalog listing", "required": [ "id", "slug", "name", "language", "price_atomic", "is_verified", "total_invocations" ], "properties": { "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_verified": { "type": "boolean" }, "language": { "$ref": "#/components/schemas/TemplateLanguage" }, "name": { "type": "string" }, "price_atomic": { "type": "integer", "format": "int64" }, "publisher_name": { "type": [ "string", "null" ] }, "publisher_slug": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "total_invocations": { "type": "integer", "format": "int64" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_ApiKeyInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response struct for listing API keys (never includes the secret)", "required": [ "id", "key_id", "name", "key_prefix", "organization_id", "key_type", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "key_type": { "$ref": "#/components/schemas/ApiKeyType" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_DatabaseWithContext": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Database with full project and branch context for cross-project listing", "required": [ "id", "name", "project_id", "project_name", "branch_id", "branch_name", "is_default_branch", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "branch_name": { "type": "string", "description": "Human-readable branch name" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid", "description": "Database ID" }, "is_default_branch": { "type": "boolean", "description": "Whether this is the project's default branch" }, "name": { "type": "string", "description": "Database name" }, "owner_name": { "type": [ "string", "null" ], "description": "Database owner role name" }, "project_id": { "type": "string", "format": "uuid", "description": "Project ID" }, "project_name": { "type": "string", "description": "Human-readable project name" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_FederatedResourceHistoryResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response for a federation history event with optional publisher metadata.", "required": [ "id", "publisher_id", "resource_type", "external_id", "metadata", "status", "operation", "changed_at" ], "properties": { "changed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "federation_id": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "operation": { "type": "string" }, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": [ "string", "null" ] }, "publisher_slug": { "type": [ "string", "null" ] }, "resource_type": { "type": "string" }, "status": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_FederatedResourceWithPublisherResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response for a federated resource with publisher info", "required": [ "id", "publisher_id", "publisher_slug", "publisher_name", "resource_type", "external_id", "metadata", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": "string" }, "publisher_slug": { "type": "string" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OAuthProviderResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response type for OAuth provider (excludes sensitive fields like client_secret)", "required": [ "id", "slug", "name", "authorization_url", "token_url", "client_id", "scopes", "pkce_required", "token_endpoint_auth_method", "is_active", "created_at", "updated_at" ], "properties": { "authorization_url": { "type": "string" }, "client_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "pkce_required": { "type": "boolean" }, "revocation_url": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" }, "token_url": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "userinfo_url": { "type": [ "string", "null" ] } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_Organization": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "slug", "created_by", "is_personal", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_personal": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "stripe_customer_id": { "type": [ "string", "null" ], "description": "Stripe Customer ID for this organization (if billing is enabled)." }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationCustomSkill": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "slug", "display_name", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "latest_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "latest_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "published_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationCustomSkillRevisionSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_custom_skill_id", "organization_id", "revision_number", "status", "bundle_sha256", "bundle_size_bytes", "file_count", "created_at" ], "properties": { "bundle_artifact_key": { "type": [ "string", "null" ] }, "bundle_sha256": { "type": "string" }, "bundle_size_bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "file_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "organization_custom_skill_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision_number": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionStatus" }, "title": { "type": [ "string", "null" ] } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationEmployeeCollaborationAssignment": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "organization_id", "deployment_id", "agent_identity_id", "assignment_generation", "organization_knowledge_read", "organization_credential_use", "organization_skill_use", "organization_artifact_write", "allowed_task_labels", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "assignment_generation": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "granted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationInvite": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response type for organization invites (token is not exposed over the API).", "required": [ "id", "organization_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "email": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ] }, "role": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationMemberWithUser": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Organization member with denormalized user fields for API responses.", "required": [ "id", "organization_id", "user_id", "email", "role", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "$ref": "#/components/schemas/Email" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_OrganizationVpcEndpoint": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "region", "endpoint_id", "state", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "endpoint_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "region": { "type": "string" }, "state": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_PaymentMethod": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Payment method details", "required": [ "id", "type_", "is_default" ], "properties": { "bank_last4": { "type": [ "string", "null" ] }, "card_brand": { "type": [ "string", "null" ] }, "card_exp_month": { "type": [ "integer", "null" ], "format": "int32" }, "card_exp_year": { "type": [ "integer", "null" ], "format": "int32" }, "card_last4": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "type_": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_Permission": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Permission definition", "required": [ "id", "name", "resource_type", "action", "created_at" ], "properties": { "action": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resource_type": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_Plan": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Plan represents a subscription tier (Free, Launch, Scale)", "required": [ "id", "name", "display_name", "price_monthly", "max_compute_units", "max_branches_per_project", "support_level", "ip_allowlist_enabled", "vpc_enabled", "sso_enabled", "audit_logs_enabled", "monitoring_enabled", "is_active", "sort_order", "created_at", "updated_at" ], "properties": { "audit_logs_enabled": { "type": "boolean" }, "branch_price_per_hour": { "type": [ "string", "null" ] }, "compute_hours_quota": { "type": [ "integer", "null" ], "format": "int32" }, "compute_price_per_cu_hour": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "data_transfer_gb_included": { "type": [ "integer", "null" ], "format": "int32" }, "data_transfer_price_per_gb": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "ip_allowlist_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "max_branches_per_project": { "type": "integer", "format": "int32" }, "max_compute_units": { "type": "integer", "format": "int32" }, "max_databases_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_endpoints_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_projects": { "type": [ "integer", "null" ], "format": "int32" }, "monitoring_enabled": { "type": "boolean" }, "monitoring_retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "pitr_price_per_gb_month": { "type": [ "string", "null" ] }, "pitr_retention_hours": { "type": [ "integer", "null" ], "format": "int32" }, "price_monthly": { "type": "string" }, "scale_to_zero_delay_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "sla_uptime_percent": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer", "format": "int32" }, "sso_enabled": { "type": "boolean" }, "storage_gb_quota": { "type": [ "string", "null" ] }, "storage_price_per_gb_month": { "type": [ "string", "null" ] }, "stripe_price_id": { "type": [ "string", "null" ], "description": "Stripe Price ID used for recurring subscriptions on this plan (for paid tiers)." }, "support_level": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vpc_enabled": { "type": "boolean" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_PublisherEarningsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Publisher earnings summary response (per asset).", "required": [ "publisher_id", "publisher_name", "publisher_slug", "wallet_address", "asset", "total_revenue", "total_withdrawn", "pending_payout", "available", "total_revenue_atomic", "total_withdrawn_atomic", "pending_payout_atomic", "available_atomic", "request_count" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetInfo" }, "available": { "type": "number", "format": "double" }, "available_atomic": { "type": "integer", "format": "int64" }, "pending_payout": { "type": "number", "format": "double" }, "pending_payout_atomic": { "type": "integer", "format": "int64" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": "string" }, "publisher_slug": { "type": "string" }, "request_count": { "type": "integer", "format": "int64", "description": "Count of billable transactions for this asset (query_charge, api_call, service_fee)." }, "total_revenue": { "type": "number", "format": "double" }, "total_revenue_atomic": { "type": "integer", "format": "int64" }, "total_withdrawn": { "type": "number", "format": "double" }, "total_withdrawn_atomic": { "type": "integer", "format": "int64" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_PublisherPayoutResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Publisher payout response.", "required": [ "id", "publisher_id", "asset", "amount", "amount_atomic", "destination_wallet", "status", "requested_at" ], "properties": { "amount": { "type": "number", "format": "double" }, "amount_atomic": { "type": "integer", "format": "int64" }, "asset": { "$ref": "#/components/schemas/AssetInfo" }, "destination_wallet": { "$ref": "#/components/schemas/WalletAddress" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "tx_hash": { "type": [ "string", "null" ] } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_PublisherResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Publisher response (excludes sensitive fields)", "required": [ "id", "name", "slug", "categories", "capabilities", "use_cases", "publisher_type", "wallet_address", "wallet_network_id", "publisher_category", "billing_model", "gateway_fee_percent", "auth_type", "allowed_passthrough_headers", "passthrough_header_rewrite", "request_content_type", "upstream_headers", "ownership_tracking_enabled", "undocumented_endpoint_policy", "is_active", "is_verified", "total_queries", "unique_agents_served", "total_revenue_atomic", "created_at", "updated_at", "requires_user_oauth" ], "properties": { "a2a_agent_card": { "description": "Cached A2A agent card" }, "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (for compute_type = agent)" }, "a2a_health_status": { "type": [ "string", "null" ], "description": "A2A health status: unknown, healthy, unhealthy, unreachable" }, "accepted_assets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssetInfo" }, "description": "Accepted assets for payment" }, "allowed_passthrough_headers": { "type": "array", "items": { "type": "string" } }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\", \"apiKey\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": "string", "description": "Upstream authentication mode." }, "billing_model": { "type": "string" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (for database_type = serendb)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching" }, "categories": { "type": "array", "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "created_at": { "type": "string", "format": "date-time" }, "database_config": { "description": "Provider config (sensitive fields redacted)" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "is_active": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "mcp_capabilities": { "description": "Cached MCP capabilities (tools, resources, prompts)" }, "mcp_discovery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpDiscoveryStatus", "description": "Last MCP discovery attempt, success, and error state." } ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "name": { "type": "string" }, "oauth_provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication" }, "ownership_tracking_enabled": { "type": "boolean" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "pricing": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PricingConfigResponse" }, "description": "Pricing config per asset (if included)" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (for database_type = serendb)" }, "protected_operations": {}, "publisher_category": { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute" }, "publisher_type": { "$ref": "#/components/schemas/PublisherType" }, "request_content_type": { "type": "string", "description": "Content-Type for upstream API requests" }, "requires_user_oauth": { "type": "boolean", "description": "If true, users must connect via OAuth before using this publisher" }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ] }, "resource_id_url_pattern": { "type": [ "string", "null" ] }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration (if publisher has geo-restricted upstream API)" } ] }, "slug": { "type": "string" }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token" }, "total_queries": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Lifetime total revenue across all assets, in atomic units" }, "undocumented_endpoint_policy": { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog" }, "unique_agents_served": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Human-readable use case descriptions" }, "verification_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When verification expires (NULL = no expiry)" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" }, "wallet_network_id": { "type": "string", "description": "Network for the wallet address" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_RbacRole": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response after creating or updating a role", "required": [ "id", "name", "is_built_in", "permissions", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_built_in": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_RevenueByDay": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Revenue breakdown by day.", "required": [ "date", "revenue_atomic", "revenue", "query_count", "unique_agents" ], "properties": { "date": { "type": "string", "description": "Date (YYYY-MM-DD)" }, "query_count": { "type": "integer", "format": "int64", "description": "Number of queries on this day" }, "revenue": { "type": "string", "description": "Revenue as decimal string" }, "revenue_atomic": { "type": "integer", "format": "int64", "description": "Revenue on this day (atomic units)" }, "unique_agents": { "type": "integer", "format": "int64", "description": "Number of unique agents on this day" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_Session": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response for listing user sessions (hides sensitive token hash)", "required": [ "id", "last_active_at", "created_at", "expires_at", "is_current" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": [ "string", "null" ] }, "is_current": { "type": "boolean" }, "last_active_at": { "type": "string", "format": "date-time" }, "user_agent": { "type": [ "string", "null" ] } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_String": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_TopAgent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Top agent by spending.", "required": [ "rank", "agent_wallet", "total_spent_atomic", "total_spent", "balance_atomic", "query_count" ], "properties": { "agent_wallet": { "type": "string", "description": "Agent wallet address" }, "balance_atomic": { "type": "integer", "format": "int64", "description": "Current balance (atomic units)" }, "last_active": { "type": [ "string", "null" ], "description": "Last activity timestamp (ISO 8601)" }, "query_count": { "type": "integer", "format": "int64", "description": "Number of queries executed" }, "rank": { "type": "integer", "format": "int32", "description": "Rank (1 = highest spender)" }, "total_spent": { "type": "string", "description": "Total amount spent as decimal string" }, "total_spent_atomic": { "type": "integer", "format": "int64", "description": "Total amount spent (atomic units)" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_UsageSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Usage summary for billing period", "required": [ "organization_id", "project_id", "project_name", "project_region", "period_start", "period_end", "compute_hours_small", "compute_hours_medium", "compute_hours_large", "compute_hours_xlarge", "storage_gb_avg", "pitr_gb_avg", "compute_cost_usd", "storage_cost_usd", "total_cost_usd" ], "properties": { "compute_cost_usd": { "type": "string" }, "compute_hours_large": { "type": "number", "format": "double" }, "compute_hours_medium": { "type": "number", "format": "double" }, "compute_hours_small": { "type": "number", "format": "double" }, "compute_hours_xlarge": { "type": "number", "format": "double" }, "organization_id": { "type": "string", "format": "uuid" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "pitr_gb_avg": { "type": "number", "format": "double" }, "project_id": { "type": "string", "format": "uuid" }, "project_name": { "type": "string", "description": "Human-readable project name (denormalized for convenience)." }, "project_region": { "type": "string", "description": "Cloud region for the project (e.g., aws-us-east-1)." }, "storage_cost_usd": { "type": "string" }, "storage_gb_avg": { "type": "number", "format": "double" }, "total_cost_usd": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_WebhookDelivery": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Webhook delivery record", "required": [ "id", "webhook_id", "event_type", "event_id", "payload", "attempt_number", "created_at" ], "properties": { "attempt_number": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "payload": { "type": "object" }, "response_body": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ], "format": "int32" }, "webhook_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_WebhookInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Webhook response (hides secret)", "required": [ "id", "organization_id", "name", "url", "events", "enabled", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "url": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_VerificationSent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletBalanceResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Wallet balance response (funded + promotional)", "required": [ "wallet_address", "balance_atomic", "balance_usd", "funded_balance_atomic", "funded_balance_usd", "promotional_balance_atomic", "promotional_balance_usd", "by_source", "total_purchases_cents", "total_purchases_usd", "has_recovery" ], "properties": { "balance_atomic": { "type": "integer", "format": "int64", "description": "Total wallet balance in atomic units" }, "balance_usd": { "type": "string" }, "by_source": { "type": "array", "items": { "$ref": "#/components/schemas/WalletSourceBalance" }, "description": "Breakdown by source" }, "funded_balance_atomic": { "type": "integer", "format": "int64", "description": "Total funded balance (fiat purchases + tier bonuses)" }, "funded_balance_usd": { "type": "string" }, "has_recovery": { "type": "boolean", "description": "Whether recovery is set up for this account" }, "promotional_balance_atomic": { "type": "integer", "format": "int64", "description": "Total promotional balance (bonuses, daily claims, referrals, admin grants)" }, "promotional_balance_usd": { "type": "string" }, "recovery_warning": { "type": [ "string", "null" ], "description": "Warning if funds exist but no recovery is set up" }, "total_purchases_cents": { "type": "integer", "format": "int64", "description": "Total lifetime SerenBucks purchases in cents (for plan upgrade tracking)" }, "total_purchases_usd": { "type": "string" }, "unread_received_transfers": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedTransferNotificationSummary" }, "description": "Recent unread wallet transfer notifications for this account." }, "wallet_address": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletRecoverResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response from wallet recovery endpoint.", "required": [ "success", "message", "agent", "setup", "skill_files", "new_recovery_code" ], "properties": { "agent": { "$ref": "#/components/schemas/AgentInfo", "description": "The recovered agent account (with a new API key)" }, "message": { "type": "string", "description": "Message about recovery result" }, "new_recovery_code": { "type": "string", "description": "New recovery code (the old one has been rotated). Save this securely!" }, "setup": { "$ref": "#/components/schemas/SetupInstructions", "description": "Setup instructions for getting started" }, "skill_files": { "$ref": "#/components/schemas/SkillFiles", "description": "Links to skill files and documentation" }, "success": { "type": "boolean", "description": "Whether recovery was successful" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransactionHistoryResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for transaction history", "required": [ "transactions", "total", "total_is_exact", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page when another page may exist." }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "total_is_exact": { "type": "boolean", "description": "Whether `total` is an exact count. When false, `total` is a pagination\nlower bound kept for older offset-based clients." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransactionResponse" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransferClaimResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "pending_transfer_id", "amount_received_cents", "balance_after_cents" ], "properties": { "amount_received_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "pending_transfer_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransferExecuteResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "transfer_id", "status", "settled_at", "balance_after_cents", "kind" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "kind": { "type": "string", "enum": [ "instant" ] }, "settled_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "transfer_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "pending_transfer_id", "status", "expires_at", "balance_after_cents", "kind" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "expires_at": { "type": "string", "format": "date-time" }, "invite_token": { "type": [ "string", "null" ] }, "invite_url": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "pending_invite" ] }, "pending_transfer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } } ] }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransferListResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransferListItem" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransferPreviewResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "recipient", "amount_cents", "balance_after_cents", "daily_remaining_cents", "kind" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "daily_remaining_cents": { "type": "integer", "format": "int64" }, "kind": { "type": "string", "enum": [ "instant" ] }, "memo": { "type": [ "string", "null" ] }, "recipient": { "$ref": "#/components/schemas/WalletTransferRecipient" } } }, { "type": "object", "required": [ "recipient_email", "amount_cents", "balance_after_cents", "daily_remaining_cents", "expires_at_estimate", "kind" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "daily_remaining_cents": { "type": "integer", "format": "int64" }, "expires_at_estimate": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "pending_invite" ] }, "memo": { "type": [ "string", "null" ] }, "recipient_email": { "type": "string" } } } ] }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WalletTransferRecallResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "pending_transfer_id", "status", "refunded_amount_cents", "balance_after_cents" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "pending_transfer_id": { "type": "string", "format": "uuid" }, "refunded_amount_cents": { "type": "integer", "format": "int64" }, "status": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WebhookCreated": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Webhook created response (includes secret on creation only)", "required": [ "webhook", "secret" ], "properties": { "secret": { "type": "string", "description": "The webhook secret - only shown once at creation time" }, "webhook": { "$ref": "#/components/schemas/WebhookInfo" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_WebhookInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Webhook response (hides secret)", "required": [ "id", "organization_id", "name", "url", "events", "enabled", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "url": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_bool": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "boolean" }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DatabaseQueryRequest": { "type": "object", "description": "Request body for database queries", "required": [ "query" ], "properties": { "database": { "type": [ "string", "null" ], "description": "Optional database name (primarily for SerenDB publishers)" }, "params": { "type": "array", "items": {}, "description": "Query parameters" }, "query": { "type": "string", "description": "Query payload to execute.\n\n- SQL publishers (serendb/neon/supabase): SQL string\n- MongoDB publishers: JSON string matching `MongoDbQuery`" } } }, "DatabaseType": { "type": "string", "description": "Database type - specific database provider when publisher_category = Database", "enum": [ "serendb", "neon", "supabase", "mongodb" ] }, "DatabaseWithContext": { "type": "object", "description": "Database with full project and branch context for cross-project listing", "required": [ "id", "name", "project_id", "project_name", "branch_id", "branch_name", "is_default_branch", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid", "description": "Branch ID" }, "branch_name": { "type": "string", "description": "Human-readable branch name" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid", "description": "Database ID" }, "is_default_branch": { "type": "boolean", "description": "Whether this is the project's default branch" }, "name": { "type": "string", "description": "Database name" }, "owner_name": { "type": [ "string", "null" ], "description": "Database owner role name" }, "project_id": { "type": "string", "format": "uuid", "description": "Project ID" }, "project_name": { "type": "string", "description": "Human-readable project name" } } }, "DelegationType": { "type": "string", "enum": [ "in_loop", "full_handoff" ] }, "DepositRequest": { "type": "object", "description": "Request to deposit funds via Stripe", "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "description": "Amount in USD cents (minimum 500 = $5.00, maximum 30000 = $300.00 by default)", "maximum": 30000, "minimum": 500 }, "referral_code": { "type": [ "string", "null" ], "description": "Optional affiliate referral code for tracking" } } }, "DepositResponse": { "type": "object", "description": "Response for wallet deposit initiation", "required": [ "deposit_id", "checkout_url", "amount_atomic", "bonus_atomic", "total_atomic", "amount_usd", "bonus_usd", "total_usd" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64", "description": "Base deposit amount in atomic units" }, "amount_usd": { "type": "string" }, "bonus_atomic": { "type": "integer", "format": "int64", "description": "Tier bonus in atomic units (if applicable)" }, "bonus_usd": { "type": "string" }, "checkout_url": { "type": "string", "description": "URL to the Stripe hosted checkout page - open this in a browser to complete payment" }, "deposit_id": { "type": "string", "format": "uuid" }, "total_atomic": { "type": "integer", "format": "int64", "description": "Total to be credited in atomic units" }, "total_usd": { "type": "string" } } }, "Eip712Domain": { "type": "object", "description": "EIP-712 domain (matches ethereum.rs Eip712Domain)", "required": [ "name", "version", "chainId", "verifyingContract" ], "properties": { "chainId": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "verifyingContract": { "type": "string" }, "version": { "type": "string" } } }, "Eip712Message": { "type": "object", "description": "EIP-712 message for TransferWithAuthorization", "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ], "properties": { "from": { "type": "string" }, "nonce": { "type": "string" }, "to": { "type": "string" }, "validAfter": { "type": "string" }, "validBefore": { "type": "string" }, "value": { "type": "string" } } }, "Eip712TypedData": { "type": "object", "description": "EIP-712 typed data for signing payment authorization", "required": [ "types", "primaryType", "domain", "message" ], "properties": { "domain": { "$ref": "#/components/schemas/Eip712Domain" }, "message": { "$ref": "#/components/schemas/Eip712Message" }, "primaryType": { "type": "string" }, "types": { "$ref": "#/components/schemas/Eip712Types" } } }, "Eip712Types": { "type": "object", "description": "EIP-712 type definitions", "required": [ "EIP712Domain", "TransferWithAuthorization" ], "properties": { "EIP712Domain": { "type": "array", "items": { "$ref": "#/components/schemas/TypedParam" } }, "TransferWithAuthorization": { "type": "array", "items": { "$ref": "#/components/schemas/TypedParam" } } } }, "Email": { "type": "string", "description": "A validated email address.\n\nThis type ensures email addresses are validated at construction time.\nStored as TEXT in the database via SQLx's transparent encoding.\n\n# Examples\n\n```\nuse seren_core::models::Email;\n\nlet email = Email::new(\"user@example.com\").unwrap();\nassert!(Email::new(\"invalid\").is_err());\n```", "example": "user@example.com" }, "EndpointAccess": { "type": "string", "description": "Access policy for a documented endpoint.", "enum": [ "authenticated", "public_anonymous" ] }, "EndpointBillingEvents": { "type": "object", "description": "Combined debug response for an endpoint's billing events", "required": [ "organization_id", "endpoint_id", "usage_events", "compute_usage_events" ], "properties": { "compute_usage_events": { "type": "array", "items": { "$ref": "#/components/schemas/ComputeUsageEventDebugRecord" } }, "endpoint_id": { "type": "string" }, "organization_id": { "type": "string" }, "usage_events": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEventDebugRecord" } } } }, "EndpointDefinition": { "type": "object", "description": "A structured endpoint definition for LLM discoverability and access control", "required": [ "method", "path" ], "properties": { "access": { "$ref": "#/components/schemas/EndpointAccess", "description": "Endpoint proxy access policy." }, "body_template": { "description": "Template for request body with {{query}} placeholder for user input\nUsed by browser extensions and LLMs to construct valid requests" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what this endpoint does" }, "example_request": { "description": "Example request body" }, "example_response": { "description": "Example response body" }, "is_default": { "type": "boolean", "description": "Whether this is the default endpoint for simple queries\nWhen multiple endpoints exist, the default is used for basic operations" }, "is_protected": { "type": "boolean", "description": "Whether this endpoint is blocked from agent access\nProtected endpoints are documented but return 403 if called" }, "method": { "$ref": "#/components/schemas/HttpMethod", "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)" }, "operation_id": { "type": [ "string", "null" ], "description": "Stable operation identifier used for scoped agent/publisher grants." }, "path": { "type": "string", "description": "Path relative to api_url (e.g., \"/chat/completions\")" }, "price": { "type": [ "string", "null" ], "description": "Endpoint-specific price override (in asset decimals, e.g., \"0.49\" for $0.49)\nIf set, takes precedence over method-level pricing (price_per_post, etc.)" }, "protection_reason": { "type": [ "string", "null" ], "description": "Reason for protection (shown in 403 response, e.g., \"Data redistribution policy\")" }, "query_params": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/QueryParamDefinition" }, "description": "Query parameter definitions" }, "request_body": { "description": "Request body schema (JSON Schema or simplified description)" }, "request_content_type": { "type": [ "string", "null" ], "description": "Endpoint-specific upstream request Content-Type override.\n\nWhen set, this takes precedence over the publisher-level request_content_type." }, "required_headers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Headers required for this endpoint (beyond publisher defaults)" }, "response": { "description": "Response schema (JSON Schema or simplified description)" } } }, "EntryRequires": { "type": "object", "description": "Typed dependency declarations for a catalog entry. All sub-collections\ndefault to empty so legacy rows storing `{}` deserialize cleanly. Stored\nin the `requires` JSONB column. Unknown top-level fields are tolerated\nat read time so a future schema bump does not invalidate existing rows;\nrequest DTOs deny unknown fields to surface client typos.", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredConnectorRef" } }, "features": { "type": "array", "items": { "type": "string" } }, "mcp_servers": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredMcpServerRef" } } } }, "EstimateRequestBody": { "type": "object", "description": "Query estimate request body", "required": [ "publisher_id", "query" ], "properties": { "asset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional asset id to estimate pricing for (defaults to publisher primary asset)" }, "publisher_id": { "type": "string", "format": "uuid", "description": "Publisher UUID" }, "query": { "type": "string", "description": "Query payload to estimate.\n\n- SQL publishers (serendb/neon/supabase): SQL string\n- MongoDB publishers: JSON string matching `MongoDbQuery`" } } }, "EstimateResponse": { "type": "object", "description": "Query estimate response", "required": [ "estimated_rows", "estimated_cost", "asset_symbol", "estimated_cost_atomic", "publisher_name", "publisher_slug" ], "properties": { "asset_symbol": { "type": "string", "description": "Asset symbol (e.g., USDC, USDT)" }, "estimated_cost": { "type": "string", "description": "Estimated cost in configured asset" }, "estimated_cost_atomic": { "type": "integer", "format": "int64", "description": "Estimated cost in atomic units" }, "estimated_rows": { "type": "integer", "format": "int64", "description": "Estimated rows to be returned" }, "publisher_name": { "type": "string", "description": "Publisher name" }, "publisher_slug": { "type": "string", "description": "Publisher slug" } } }, "EvalMatrixEntry": { "type": "object", "required": [ "score", "signal_count" ], "properties": { "score": { "type": "number", "format": "double" }, "signal_count": { "type": "integer", "format": "int64" } } }, "EvalMatrixResponse": { "type": "object", "required": [ "matrix", "generated_at", "total_signals" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "matrix": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EvalMatrixEntry" }, "propertyNames": { "type": "string" } }, "propertyNames": { "type": "string" } }, "total_signals": { "type": "integer", "format": "int64" } } }, "EvalSignalItem": { "type": "object", "required": [ "task_type", "model_id", "satisfaction" ], "properties": { "delegation_type": { "$ref": "#/components/schemas/DelegationType" }, "had_tool_errors": { "type": "boolean" }, "latency_ms": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LatencyMs" } ] }, "model_id": { "type": "string" }, "satisfaction": { "type": "integer", "format": "int32" }, "task_type": { "$ref": "#/components/schemas/TaskType" }, "token_count": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenCount" } ] }, "tool_ids_used": { "type": "array", "items": { "type": "string" } } } }, "EvalSignalRequest": { "type": "object", "required": [ "signals" ], "properties": { "signals": { "type": "array", "items": { "$ref": "#/components/schemas/EvalSignalItem" } } } }, "EvalSignalResponse": { "type": "object", "required": [ "accepted", "rejected" ], "properties": { "accepted": { "type": "integer", "format": "int64" }, "rejected": { "type": "integer", "format": "int64" } } }, "FederatedResourceHistoryResponse": { "type": "object", "description": "Response for a federation history event with optional publisher metadata.", "required": [ "id", "publisher_id", "resource_type", "external_id", "metadata", "status", "operation", "changed_at" ], "properties": { "changed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "federation_id": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "operation": { "type": "string" }, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": [ "string", "null" ] }, "publisher_slug": { "type": [ "string", "null" ] }, "resource_type": { "type": "string" }, "status": { "type": "string" } } }, "FederatedResourceResponse": { "type": "object", "description": "Response for a single federated resource", "required": [ "id", "publisher_id", "resource_type", "external_id", "metadata", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FederatedResourceWithPublisherResponse": { "type": "object", "description": "Response for a federated resource with publisher info", "required": [ "id", "publisher_id", "publisher_slug", "publisher_name", "resource_type", "external_id", "metadata", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "org_database_id": { "type": [ "string", "null" ], "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": "string" }, "publisher_slug": { "type": "string" }, "resource_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FederationHistoryStatsResponse": { "type": "object", "description": "Response for federation history aggregate statistics.", "required": [ "total_events", "unique_resources", "unique_publishers", "by_operation", "by_type", "by_status" ], "properties": { "by_operation": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_type": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "total_events": { "type": "integer", "format": "int64" }, "unique_publishers": { "type": "integer", "format": "int64" }, "unique_resources": { "type": "integer", "format": "int64" } } }, "FederationStatsResponse": { "type": "object", "description": "Response for federation statistics", "required": [ "total_active", "by_type", "by_status" ], "properties": { "by_status": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "by_type": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "total_active": { "type": "integer", "format": "int64" } } }, "ForgotPasswordRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "$ref": "#/components/schemas/Email" } } }, "GenerateInvoicesRequest": { "type": "object", "required": [ "year", "month" ], "properties": { "month": { "type": "integer", "format": "int32", "minimum": 0 }, "year": { "type": "integer", "format": "int32" } } }, "GeoRestrictedError": { "type": "object", "description": "Error response when a publisher uses opt_in routing and the user has not opted in", "required": [ "error", "message", "publisher", "proxy_region", "opt_in_endpoint" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "opt_in_endpoint": { "type": "string" }, "proxy_region": { "type": "string" }, "publisher": { "type": "string" } } }, "GeoRoutingConfig": { "type": "object", "required": [ "proxy_region" ], "properties": { "mode": { "$ref": "#/components/schemas/GeoRoutingMode", "description": "Routing mode (defaults to `always`)." }, "proxy_region": { "type": "string", "description": "Proxy region to route through (e.g., \"EU\")" } } }, "GeoRoutingMode": { "type": "string", "description": "Geographic routing configuration for publishers whose upstream API\nshould be accessed through a regional proxy.\n\nTwo modes:\n- `\"always\"`: all requests are routed through the proxy (e.g., upstream blocks US IPs)\n- `\"opt_in\"`: users can choose to route through the proxy via `/user/routing`", "enum": [ "always", "opt_in" ] }, "HttpMethod": { "type": "string", "description": "HTTP method for endpoint definitions", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] }, "IntegrationType": { "type": "string", "description": "Primary interface for an integration publisher.\n\nREST and native MCP interfaces are enabled independently by `api_url` and `mcp_endpoint`, so an integration publisher may expose both.", "enum": [ "api", "mcp" ] }, "InvocationCostBreakdown": { "type": "object", "description": "Cost breakdown for template invocation response", "required": [ "publisherFee", "llmCost", "computeCost", "total", "llmKeyUsed" ], "properties": { "computeCost": { "type": "string" }, "llmCost": { "type": "string" }, "llmKeyUsed": { "type": "string" }, "publisherFee": { "type": "string" }, "total": { "type": "string" } } }, "Invoice": { "type": "object", "description": "Invoice response with line items", "required": [ "id", "organization_id", "invoice_number", "period_start", "period_end", "subtotal_usd", "tax_usd", "total_usd", "status", "line_items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "organization_id": { "type": "string", "format": "uuid" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "status": { "type": "string" }, "subtotal_usd": { "type": "string" }, "tax_usd": { "type": "string" }, "total_usd": { "type": "string" } } }, "InvoiceLineItem": { "type": "object", "description": "Invoice line item response", "required": [ "description", "line_type", "quantity", "unit_price", "amount_usd" ], "properties": { "amount_usd": { "type": "string" }, "description": { "type": "string" }, "line_type": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "string" } } }, "InvoicesGenerated": { "type": "object", "description": "Response for invoice generation", "required": [ "invoice_ids", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "InvokeTemplateRequest": { "type": "object", "description": "Request to invoke an agent template", "required": [ "input" ], "properties": { "input": { "description": "Input data to pass to the template" } } }, "InvokeTemplateResponse": { "type": "object", "description": "Response from invoking a template", "required": [ "result", "cost", "executionTimeMs", "invocationId" ], "properties": { "cost": { "$ref": "#/components/schemas/InvocationCostBreakdown", "description": "Cost breakdown" }, "executionTimeMs": { "type": "integer", "format": "int32", "description": "Execution time in milliseconds" }, "invocationId": { "type": "string", "format": "uuid", "description": "Invocation ID for tracking" }, "result": { "description": "Output from template execution" } } }, "LatencyMs": { "type": "object", "properties": { "first": { "type": [ "integer", "null" ], "format": "int32" }, "total": { "type": [ "integer", "null" ], "format": "int32" } } }, "LlmConfig": { "type": "object", "description": "LLM configuration for templates", "required": [ "provider", "model" ], "properties": { "apiKey": { "type": [ "string", "null" ], "description": "API key (optional, will be encrypted)" }, "model": { "type": "string", "description": "Model name (e.g., \"gpt-4o\", \"claude-3-opus\")" }, "provider": { "type": "string", "description": "LLM provider (e.g., \"openai\", \"anthropic\")" } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "$ref": "#/components/schemas/Email" }, "password": { "type": "string" } } }, "LoginResult": { "type": "object", "required": [ "access_token", "refresh_token", "expires_in", "user", "default_organization_id" ], "properties": { "access_token": { "type": "string" }, "default_organization_id": { "type": "string", "format": "uuid", "description": "The user's default organization ID for API calls requiring an organization context.\nThis is typically the first organization the user joined (their personal org)." }, "expires_in": { "type": "integer", "format": "int64" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfo" } } }, "LogoUploadRequest": { "type": "object", "description": "Logo upload request body", "required": [ "logo", "content_type" ], "properties": { "content_type": { "type": "string", "description": "Content type of the image (image/png, image/jpeg, image/webp, image/svg+xml)" }, "logo": { "type": "string", "description": "Base64 encoded image data" } } }, "LogoUploadResponse": { "type": "object", "description": "Logo upload response", "required": [ "message", "logo_url" ], "properties": { "logo_url": { "type": "string", "description": "URL to access the uploaded logo" }, "message": { "type": "string", "description": "Message indicating success" } } }, "LogoutResult": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ManagedAgentPrivateOutputPolicy": { "type": "string", "enum": [ "control_plane", "private_session_database" ] }, "ManagedAgentSessionDatabase": { "type": "object", "required": [ "engine" ], "properties": { "database_name": { "type": [ "string", "null" ], "description": "Optional Seren organization database name when `provider` is `seren_organization_database`." }, "engine": { "$ref": "#/components/schemas/ManagedAgentSessionDatabaseEngine", "description": "Session database engine family. The runtime still consumes a standard connection URL." }, "provider": { "$ref": "#/components/schemas/ManagedAgentSessionDatabaseProvider", "description": "Session database provider. Defaults to `direct_url`." }, "url_secret_key": { "type": [ "string", "null" ], "description": "Secret key whose value is the connection URL for the session database." } } }, "ManagedAgentSessionDatabaseEngine": { "type": "string", "enum": [ "postgres", "aurora_postgres" ] }, "ManagedAgentSessionDatabaseProvider": { "type": "string", "enum": [ "direct_url", "seren_organization_database" ] }, "McpDiscoveryStatus": { "type": "object", "description": "Discovery status for an MCP publisher.", "properties": { "error": { "type": [ "string", "null" ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "McpToolInfo": { "type": "object", "description": "Information about an MCP tool", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Tool description" }, "input_schema": { "description": "JSON Schema for tool input parameters" }, "name": { "type": "string", "description": "Tool name" } } }, "MultipleOAuthConnectionsAmbiguousResponse": { "type": "object", "required": [ "error", "message", "provider_id", "provider_slug", "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/UserOAuthConnectionResponse" } }, "error": { "type": "string" }, "message": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_slug": { "type": "string" } } }, "NotificationReadResponse": { "type": "object", "required": [ "notification_id", "read_at" ], "properties": { "notification_id": { "type": "string", "format": "uuid" }, "read_at": { "type": "string", "format": "date-time" } } }, "OAuthProviderResponse": { "type": "object", "description": "Response type for OAuth provider (excludes sensitive fields like client_secret)", "required": [ "id", "slug", "name", "authorization_url", "token_url", "client_id", "scopes", "pkce_required", "token_endpoint_auth_method", "is_active", "created_at", "updated_at" ], "properties": { "authorization_url": { "type": "string" }, "client_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "pkce_required": { "type": "boolean" }, "revocation_url": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" }, "token_url": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "userinfo_url": { "type": [ "string", "null" ] } } }, "OffsetPaginationMeta": { "type": "object", "description": "Offset-based pagination metadata\n\nUsed for APIs that use limit/offset pagination instead of page/per_page.\nStandard fields following REST API conventions.", "required": [ "total", "count", "limit", "offset", "has_more" ], "properties": { "count": { "type": "integer", "description": "Number of items in this response", "minimum": 0 }, "has_more": { "type": "boolean", "description": "Whether more items exist beyond this page" }, "limit": { "type": "integer", "format": "int64", "description": "Maximum items requested" }, "offset": { "type": "integer", "format": "int64", "description": "Starting offset" }, "total": { "type": "integer", "format": "int64", "description": "Total number of items across all pages", "minimum": 0 } } }, "OnchainDepositRequest": { "type": "object", "description": "Request body for on-chain deposit", "required": [ "publisher_id", "amount" ], "properties": { "amount": { "type": "string", "description": "Amount to deposit in the configured asset (decimal string, e.g., \"10.50\")" }, "asset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional asset id to deposit (defaults to publisher primary asset)" }, "publisher_id": { "type": "string", "format": "uuid", "description": "Publisher to deposit funds for" } } }, "OnchainDepositResponse": { "type": "object", "description": "Response after successful on-chain deposit", "required": [ "message", "deposited_amount", "balance_amount", "asset_symbol", "publisher_id", "agent_wallet" ], "properties": { "agent_wallet": { "$ref": "#/components/schemas/WalletAddress", "description": "Agent wallet address" }, "asset_symbol": { "type": "string", "description": "Asset symbol (e.g., USDC, USDT)" }, "balance_amount": { "type": "string", "description": "New balance (configured asset)" }, "deposited_amount": { "type": "string", "description": "Amount deposited (configured asset)" }, "message": { "type": "string", "description": "Deposit successful message" }, "publisher_id": { "type": "string", "format": "uuid", "description": "Publisher ID" }, "tx_hash": { "type": [ "string", "null" ], "description": "On-chain transaction hash" } } }, "Organization": { "type": "object", "required": [ "id", "name", "slug", "created_by", "is_personal", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_personal": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "stripe_customer_id": { "type": [ "string", "null" ], "description": "Stripe Customer ID for this organization (if billing is enabled)." }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationConsumption": { "type": "object", "description": "OrganizationConsumption wraps organization-wide consumption", "required": [ "organization_id", "from", "to", "periods", "current_month" ], "properties": { "current_month": { "$ref": "#/components/schemas/ConsumptionSummary" }, "from": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionPeriodData" } }, "to": { "type": "string", "format": "date-time" } } }, "OrganizationCustomSkill": { "type": "object", "required": [ "id", "organization_id", "slug", "display_name", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "latest_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "latest_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_revision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionSummary" } ] }, "published_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "OrganizationCustomSkillFileContent": { "type": "object", "required": [ "revision_id", "relative_path", "content_type", "size_bytes", "sha256", "content_base64", "is_text" ], "properties": { "content_base64": { "type": "string" }, "content_type": { "type": "string" }, "is_text": { "type": "boolean" }, "relative_path": { "type": "string" }, "revision_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "OrganizationCustomSkillFileInput": { "type": "object", "required": [ "relative_path", "content_base64" ], "properties": { "content_base64": { "type": "string" }, "content_type": { "type": [ "string", "null" ] }, "relative_path": { "type": "string" } } }, "OrganizationCustomSkillFileMetadata": { "type": "object", "required": [ "id", "revision_id", "relative_path", "content_type", "size_bytes", "sha256", "is_text", "created_at" ], "properties": { "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_text": { "type": "boolean" }, "relative_path": { "type": "string" }, "revision_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "OrganizationCustomSkillRevision": { "type": "object", "required": [ "id", "organization_custom_skill_id", "organization_id", "revision_number", "status", "skill_md", "skill_md_sha256", "frontmatter", "manifest", "bundle_sha256", "bundle_size_bytes", "created_at", "files" ], "properties": { "bundle_artifact_key": { "type": [ "string", "null" ] }, "bundle_sha256": { "type": "string" }, "bundle_size_bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationCustomSkillFileMetadata" } }, "frontmatter": {}, "id": { "type": "string", "format": "uuid" }, "manifest": {}, "organization_custom_skill_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision_number": { "type": "integer", "format": "int64" }, "skill_md": { "type": "string" }, "skill_md_sha256": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionStatus" }, "title": { "type": [ "string", "null" ] } } }, "OrganizationCustomSkillRevisionStatus": { "type": "string", "enum": [ "draft", "published", "superseded", "archived" ] }, "OrganizationCustomSkillRevisionSummary": { "type": "object", "required": [ "id", "organization_custom_skill_id", "organization_id", "revision_number", "status", "bundle_sha256", "bundle_size_bytes", "file_count", "created_at" ], "properties": { "bundle_artifact_key": { "type": [ "string", "null" ] }, "bundle_sha256": { "type": "string" }, "bundle_size_bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "file_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "organization_custom_skill_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision_number": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/OrganizationCustomSkillRevisionStatus" }, "title": { "type": [ "string", "null" ] } } }, "OrganizationCustomSkillStatus": { "type": "string", "enum": [ "active", "archived" ] }, "OrganizationEmployeeCollaborationAssignment": { "type": "object", "required": [ "organization_id", "deployment_id", "agent_identity_id", "assignment_generation", "organization_knowledge_read", "organization_credential_use", "organization_skill_use", "organization_artifact_write", "allowed_task_labels", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "assignment_generation": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "granted_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationEmployeeCollaborationPolicy": { "type": "object", "required": [ "organization_id", "policy_revision", "enabled", "organization_knowledge_read", "organization_credential_use", "organization_skill_use", "organization_artifact_write", "updated_at" ], "properties": { "enabled": { "type": "boolean", "description": "Organization collaboration is unavailable unless explicitly enabled." }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" }, "policy_revision": { "type": "string", "description": "Opaque revision rotated only when the effective policy changes." }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationInvite": { "type": "object", "description": "Response type for organization invites (token is not exposed over the API).", "required": [ "id", "organization_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "email": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ] }, "role": { "type": "string" } } }, "OrganizationMemberWithUser": { "type": "object", "description": "Organization member with denormalized user fields for API responses.", "required": [ "id", "organization_id", "user_id", "email", "role", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "$ref": "#/components/schemas/Email" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "OrganizationMemoryCapturePolicy": { "type": "object", "required": [ "organization_id", "policy_version", "capture_enabled", "retain_source_allowed", "capture_user_prompts", "capture_assistant_responses", "max_transcript_bytes", "cache_ttl_seconds", "offline_grace_seconds", "allowed_agent_platforms", "updated_at" ], "properties": { "allowed_agent_platforms": { "type": "array", "items": { "type": "string" }, "description": "Empty permits every supported platform; otherwise names are lowercase." }, "cache_ttl_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "capture_assistant_responses": { "type": "boolean" }, "capture_enabled": { "type": "boolean" }, "capture_user_prompts": { "type": "boolean" }, "max_transcript_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "offline_grace_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "organization_id": { "type": "string", "format": "uuid" }, "policy_version": { "type": "string", "description": "Opaque revision that automatic capture submissions must present. It\nchanges only when the effective policy changes." }, "retain_source_allowed": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationOtpCodeRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "OrganizationOtpEnrollmentChallenge": { "type": "object", "required": [ "organization_id", "user_id", "enrollment_status", "issuer", "account_name", "manual_entry_key", "otpauth_uri" ], "properties": { "account_name": { "type": "string" }, "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "issuer": { "type": "string" }, "manual_entry_key": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "otpauth_uri": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "OrganizationOtpEnrollmentStatus": { "type": "string", "enum": [ "unenrolled", "pending_confirmation", "enrolled" ] }, "OrganizationOtpPolicy": { "type": "object", "required": [ "organization_id", "enabled_scopes", "default_verification_ttl", "updated_at" ], "properties": { "default_verification_ttl": { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" }, "enabled_scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScope" } }, "organization_id": { "type": "string", "format": "uuid" }, "ttl_overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScopePolicy" } }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationOtpResetResponse": { "type": "object", "required": [ "organization_id", "user_id", "enrollment_status" ], "properties": { "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "organization_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "OrganizationOtpScope": { "type": "string", "enum": [ "org_sign_in", "organization_security_manage", "private_models.access" ] }, "OrganizationOtpScopePolicy": { "type": "object", "required": [ "scope" ], "properties": { "scope": { "$ref": "#/components/schemas/OrganizationOtpScope" }, "verification_ttl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" } ] } } }, "OrganizationOtpStatus": { "type": "object", "required": [ "organization_id", "user_id", "scope", "is_scope_protected", "enrollment_status", "verification_required", "verification_ttl" ], "properties": { "enrollment_status": { "$ref": "#/components/schemas/OrganizationOtpEnrollmentStatus" }, "is_scope_protected": { "type": "boolean" }, "locked_until": { "type": [ "string", "null" ], "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "scope": { "$ref": "#/components/schemas/OrganizationOtpScope" }, "user_id": { "type": "string", "format": "uuid" }, "verification_required": { "type": "boolean" }, "verification_ttl": { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" }, "verified_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrganizationOtpVerificationTtl": { "type": "string", "enum": [ "30m", "8h", "12h" ] }, "OrganizationOtpVerifyRequest": { "type": "object", "required": [ "scope", "code" ], "properties": { "code": { "type": "string" }, "scope": { "$ref": "#/components/schemas/OrganizationOtpScope" } } }, "OrganizationPlan": { "type": "object", "description": "OrganizationPlan tracks which plan an organization is currently on", "required": [ "id", "organization_id", "plan_id", "started_at", "is_trial", "created_at", "updated_at" ], "properties": { "cancellation_reason": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_trial": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "plan_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "stripe_subscription_id": { "type": [ "string", "null" ] }, "trial_ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationPlanWithDetails": { "type": "object", "description": "Response type that includes both the plan and organization_plan details", "required": [ "organization_plan", "plan" ], "properties": { "organization_plan": { "$ref": "#/components/schemas/OrganizationPlan" }, "plan": { "$ref": "#/components/schemas/Plan" } } }, "OrganizationPrivateModelsMode": { "type": "string", "enum": [ "standard", "private_org_agent" ] }, "OrganizationPrivateModelsPolicy": { "type": "object", "required": [ "organization_id", "mode", "data_handling_attestation", "updated_at" ], "properties": { "allow_claude_agent": { "type": "boolean" }, "allow_cloud_agent_launch": { "type": "boolean" }, "allow_codex_agent": { "type": "boolean" }, "allow_seren_agent": { "type": "boolean" }, "allow_seren_private_agent": { "type": "boolean" }, "data_handling_attestation": { "$ref": "#/components/schemas/PrivateModelsDataHandlingAttestation", "description": "Machine-readable training and retention declaration for organization private-model inference. Clients requiring confidentiality must deny access unless the status and terms are affirmative." }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "deployment_name": { "type": [ "string", "null" ] }, "disable_external_model_providers": { "type": "boolean" }, "disable_local_agents": { "type": "boolean" }, "disable_seren_models": { "type": "boolean" }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "global_ordered_model_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hide_model_picker": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/OrganizationPrivateModelsMode" }, "model_id": { "type": [ "string", "null" ] }, "ordered_model_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "organization_id": { "type": "string", "format": "uuid" }, "private_output_policy": { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase" } ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationVpcEndpoint": { "type": "object", "required": [ "id", "organization_id", "region", "endpoint_id", "state", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "endpoint_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "organization_id": { "type": "string", "format": "uuid" }, "region": { "type": "string" }, "state": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PaginatedResponse_Vec_PublisherResponse": { "type": "object", "description": "Response wrapper with offset-based pagination\n\nUse this for list endpoints that use limit/offset pagination.", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Publisher response (excludes sensitive fields)", "required": [ "id", "name", "slug", "categories", "capabilities", "use_cases", "publisher_type", "wallet_address", "wallet_network_id", "publisher_category", "billing_model", "gateway_fee_percent", "auth_type", "allowed_passthrough_headers", "passthrough_header_rewrite", "request_content_type", "upstream_headers", "ownership_tracking_enabled", "undocumented_endpoint_policy", "is_active", "is_verified", "total_queries", "unique_agents_served", "total_revenue_atomic", "created_at", "updated_at", "requires_user_oauth" ], "properties": { "a2a_agent_card": { "description": "Cached A2A agent card" }, "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (for compute_type = agent)" }, "a2a_health_status": { "type": [ "string", "null" ], "description": "A2A health status: unknown, healthy, unhealthy, unreachable" }, "accepted_assets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssetInfo" }, "description": "Accepted assets for payment" }, "allowed_passthrough_headers": { "type": "array", "items": { "type": "string" } }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\", \"apiKey\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": "string", "description": "Upstream authentication mode." }, "billing_model": { "type": "string" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (for database_type = serendb)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching" }, "categories": { "type": "array", "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "created_at": { "type": "string", "format": "date-time" }, "database_config": { "description": "Provider config (sensitive fields redacted)" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "is_active": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "mcp_capabilities": { "description": "Cached MCP capabilities (tools, resources, prompts)" }, "mcp_discovery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpDiscoveryStatus", "description": "Last MCP discovery attempt, success, and error state." } ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "name": { "type": "string" }, "oauth_provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication" }, "ownership_tracking_enabled": { "type": "boolean" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "pricing": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PricingConfigResponse" }, "description": "Pricing config per asset (if included)" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (for database_type = serendb)" }, "protected_operations": {}, "publisher_category": { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute" }, "publisher_type": { "$ref": "#/components/schemas/PublisherType" }, "request_content_type": { "type": "string", "description": "Content-Type for upstream API requests" }, "requires_user_oauth": { "type": "boolean", "description": "If true, users must connect via OAuth before using this publisher" }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ] }, "resource_id_url_pattern": { "type": [ "string", "null" ] }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration (if publisher has geo-restricted upstream API)" } ] }, "slug": { "type": "string" }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token" }, "total_queries": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Lifetime total revenue across all assets, in atomic units" }, "undocumented_endpoint_policy": { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog" }, "unique_agents_served": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Human-readable use case descriptions" }, "verification_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When verification expires (NULL = no expiry)" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" }, "wallet_network_id": { "type": "string", "description": "Network for the wallet address" } } } }, "pagination": { "$ref": "#/components/schemas/OffsetPaginationMeta", "description": "Pagination metadata" } } }, "PaginationMeta": { "type": "object", "description": "Pagination metadata included in responses.", "required": [ "total", "count", "limit", "offset", "has_more" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "Number of items in this response" }, "has_more": { "type": "boolean", "description": "Whether there are more items after this page" }, "limit": { "type": "integer", "format": "int64", "description": "Maximum items per page" }, "offset": { "type": "integer", "format": "int64", "description": "Offset from start" }, "total": { "type": "integer", "format": "int64", "description": "Total number of items across all pages" } } }, "ParamType": { "type": "string", "description": "Parameter type for query/path parameters", "enum": [ "string", "integer", "boolean", "number", "array" ] }, "PasswordReset": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "PasswordResetSent": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "PasswordUpdated": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "PaymentHistory": { "type": "object", "description": "Payment history response", "required": [ "payments" ], "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRecord" } } } }, "PaymentIntentCreated": { "type": "object", "description": "Response for creating a payment intent", "required": [ "payment_intent_id", "client_secret", "amount_cents", "amount_usd", "currency" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "description": "Amount to be charged, in cents." }, "amount_usd": { "type": "string", "description": "Amount to be charged, in USD." }, "client_secret": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "payment_intent_id": { "$ref": "#/components/schemas/StripePaymentIntentId" } } }, "PaymentMethod": { "type": "object", "description": "Payment method details", "required": [ "id", "type_", "is_default" ], "properties": { "bank_last4": { "type": [ "string", "null" ] }, "card_brand": { "type": [ "string", "null" ] }, "card_exp_month": { "type": [ "integer", "null" ], "format": "int32" }, "card_exp_year": { "type": [ "integer", "null" ], "format": "int32" }, "card_last4": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "type_": { "type": "string" } } }, "PaymentMethodAdded": { "type": "object", "description": "Response for adding a payment method", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } }, "PaymentRecord": { "type": "object", "description": "Individual payment record", "required": [ "id", "stripe_payment_intent_id", "amount_usd", "currency", "status", "attempted_at" ], "properties": { "amount_usd": { "type": "string" }, "attempted_at": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "failed_at": { "type": [ "string", "null" ] }, "failure_code": { "type": [ "string", "null" ] }, "failure_message": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "status": { "type": "string" }, "stripe_charge_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StripeChargeId" } ] }, "stripe_payment_intent_id": { "$ref": "#/components/schemas/StripePaymentIntentId" }, "succeeded_at": { "type": [ "string", "null" ] } } }, "PaymentRequestInfo": { "type": "object", "description": "Internal payment request tracking (extends with Seren-specific fields)", "required": [ "payment_request_id", "publisher_id", "expires" ], "properties": { "eip712TypedData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Eip712TypedData", "description": "EIP-712 typed data for signing (EIP-3009 only)" } ] }, "estimate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CostEstimate", "description": "Optional: Estimated cost breakdown" } ] }, "expires": { "type": "integer", "format": "int64", "description": "Expiration timestamp (Unix seconds)" }, "payment_request_id": { "type": "string", "description": "Payment request ID for correlation" }, "publisher_id": { "type": "string", "format": "uuid", "description": "Publisher ID" } } }, "PaymentRequiredResponse": { "type": "object", "description": "x402 V2 402 Payment Required Response\n\nThe official V2 format with top-level resource info and extensions support.", "required": [ "x402Version", "resource", "accepts" ], "properties": { "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequirements" }, "description": "List of acceptable payment methods" }, "error": { "type": [ "string", "null" ], "description": "Error message explaining why payment is required" }, "extensions": { "description": "Optional extensions (V2 feature for protocol extensibility)" }, "resource": { "$ref": "#/components/schemas/ResourceInfo", "description": "Resource information (V2 - moved to top level)" }, "x402Version": { "type": "integer", "format": "int32", "description": "x402 protocol version (2 for V2)", "minimum": 0 } } }, "PaymentRequiredResponseWithInfo": { "allOf": [ { "$ref": "#/components/schemas/PaymentRequiredResponse", "description": "Protocol response (x402 v2)" }, { "type": "object", "properties": { "seren": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentRequestInfo", "description": "Seren-specific payment request info" } ] } } } ], "description": "402 Payment Required response body (x402 v2) with Seren-specific extensions." }, "PaymentRequirements": { "type": "object", "description": "x402 V2 Payment Requirements\n\nFollows the official x402 V2 specification.\nSee: https://github.com/coinbase/x402/blob/main/typescript/packages/core/src/types/payments.ts", "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "amount": { "type": "string", "description": "Amount in atomic units (token decimals)" }, "asset": { "type": "string", "description": "Payment asset address (token contract)" }, "extra": { "description": "Extra information about the payment (scheme-specific)\n\nFor EVM/exact scheme, this typically contains:\n- `name`: Asset name (e.g., \"USD Coin\")\n- `version`: Asset version\n- `eip712TypedData`: EIP-712 typed data for signing (EIP-3009)\n- `paymentRequestId`: Correlation ID\n- `expires`: Expiration timestamp\n- `estimate`: Cost breakdown (optional)\n- `settlementMethod`: \"eip3009\" or \"transfer\"" }, "maxTimeoutSeconds": { "type": "integer", "format": "int32", "description": "Maximum time in seconds for the resource server to respond" }, "network": { "type": "string", "description": "Network for payment in CAIP-2 format (e.g., \"eip155:8453\" for Base mainnet)" }, "payTo": { "type": "string", "description": "Address to pay value to (publisher or gateway wallet)" }, "scheme": { "type": "string", "description": "Payment scheme (e.g., \"exact\")" } } }, "PaymentStatus": { "type": "string", "description": "Status of payment request (402 response)", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "PayoutStatus": { "type": "string", "description": "Status of a publisher payout request.", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "Permission": { "type": "object", "description": "Permission definition", "required": [ "id", "name", "resource_type", "action", "created_at" ], "properties": { "action": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resource_type": { "type": "string" } } }, "Plan": { "type": "object", "description": "Plan represents a subscription tier (Free, Launch, Scale)", "required": [ "id", "name", "display_name", "price_monthly", "max_compute_units", "max_branches_per_project", "support_level", "ip_allowlist_enabled", "vpc_enabled", "sso_enabled", "audit_logs_enabled", "monitoring_enabled", "is_active", "sort_order", "created_at", "updated_at" ], "properties": { "audit_logs_enabled": { "type": "boolean" }, "branch_price_per_hour": { "type": [ "string", "null" ] }, "compute_hours_quota": { "type": [ "integer", "null" ], "format": "int32" }, "compute_price_per_cu_hour": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "data_transfer_gb_included": { "type": [ "integer", "null" ], "format": "int32" }, "data_transfer_price_per_gb": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "ip_allowlist_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "max_branches_per_project": { "type": "integer", "format": "int32" }, "max_compute_units": { "type": "integer", "format": "int32" }, "max_databases_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_endpoints_per_branch": { "type": [ "integer", "null" ], "format": "int32" }, "max_projects": { "type": [ "integer", "null" ], "format": "int32" }, "monitoring_enabled": { "type": "boolean" }, "monitoring_retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "pitr_price_per_gb_month": { "type": [ "string", "null" ] }, "pitr_retention_hours": { "type": [ "integer", "null" ], "format": "int32" }, "price_monthly": { "type": "string" }, "scale_to_zero_delay_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "sla_uptime_percent": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer", "format": "int32" }, "sso_enabled": { "type": "boolean" }, "storage_gb_quota": { "type": [ "string", "null" ] }, "storage_price_per_gb_month": { "type": [ "string", "null" ] }, "stripe_price_id": { "type": [ "string", "null" ], "description": "Stripe Price ID used for recurring subscriptions on this plan (for paid tiers)." }, "support_level": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vpc_enabled": { "type": "boolean" } } }, "PricingConfigResponse": { "type": "object", "description": "Pricing config response", "required": [ "asset_id", "pricing_model", "base_price_per_1000_rows", "markup_multiplier", "min_charge", "payment_expiry_minutes", "prepaid_enabled", "onchain_enabled", "minimum_balance", "low_balance_threshold" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "description": "Asset this pricing applies to" }, "asset_symbol": { "type": [ "string", "null" ], "description": "Asset symbol for display" }, "base_price_per_1000_rows": { "type": "string" }, "grace_period_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "hourly_rate": { "type": [ "string", "null" ] }, "low_balance_threshold": { "type": "string" }, "markup_multiplier": { "type": "string" }, "max_queries_per_minute": { "type": [ "integer", "null" ], "format": "int32" }, "min_charge": { "type": "string" }, "min_display_price": { "type": [ "string", "null" ], "description": "Minimum price to display in UI for passthrough publishers (informational only)" }, "minimum_balance": { "type": "string" }, "onchain_enabled": { "type": "boolean" }, "payment_expiry_minutes": { "type": "integer", "format": "int32" }, "prepaid_enabled": { "type": "boolean" }, "price_per_call": { "type": [ "string", "null" ] }, "price_per_delete": { "type": [ "string", "null" ] }, "price_per_execution": { "type": [ "string", "null" ], "description": "Price per execution for agent templates or usage-based billing" }, "price_per_get": { "type": [ "string", "null" ] }, "price_per_patch": { "type": [ "string", "null" ] }, "price_per_post": { "type": [ "string", "null" ] }, "price_per_put": { "type": [ "string", "null" ] }, "pricing_display_text": { "type": [ "string", "null" ], "description": "Text to display for variable pricing (e.g., \"Varies by model\")" }, "pricing_model": { "$ref": "#/components/schemas/PricingModel" }, "reserve_max_charge": { "type": [ "string", "null" ] }, "unresolved_fallback_charge": { "type": [ "string", "null" ] } } }, "PricingModel": { "type": "string", "description": "Pricing model used to interpret pricing units.", "enum": [ "per_row", "per_request", "per_byte", "tiered", "passthrough" ] }, "PricingSummary": { "type": "object", "description": "Simplified pricing summary for suggestions", "properties": { "base_price_per_1000_rows": { "type": [ "string", "null" ] } } }, "PrivateModelsDataHandlingAttestation": { "type": "object", "description": "Machine-readable private-model data-handling declaration.", "required": [ "status", "scope", "training_use", "prompt_retention", "output_retention", "derived_data_retention" ], "properties": { "attested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the affirmative declaration was recorded. Absent when status is `unknown`." }, "attested_by_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "User who recorded the declaration, when that user still exists." }, "basis": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrivateModelsDataHandlingAttestationBasis", "description": "Authority that recorded the declaration. Absent when status is `unknown`." } ] }, "derived_data_retention": { "$ref": "#/components/schemas/PrivateModelsDataRetention", "description": "Retention treatment for content-derived logs, caches, embeddings, fine-tuning artifacts, and similar records." }, "output_retention": { "$ref": "#/components/schemas/PrivateModelsDataRetention", "description": "Retention treatment for generated inference outputs." }, "prompt_retention": { "$ref": "#/components/schemas/PrivateModelsDataRetention", "description": "Retention treatment for prompts submitted to inference." }, "scope": { "$ref": "#/components/schemas/PrivateModelsDataHandlingScope", "description": "Operations to which this declaration applies." }, "status": { "$ref": "#/components/schemas/PrivateModelsDataHandlingAttestationStatus", "description": "`unknown` provides no confidentiality guarantee. `no_training_no_retention` is the affirmative declaration defined by the remaining fields." }, "terms": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrivateModelsDataHandlingTerms", "description": "Definition of the affirmative declaration. Absent when status is `unknown`." } ] }, "training_use": { "$ref": "#/components/schemas/PrivateModelsTrainingUse", "description": "Whether covered data may be used for training or model improvement." } } }, "PrivateModelsDataHandlingAttestationBasis": { "type": "string", "description": "Authority that recorded the data-handling declaration.", "enum": [ "policy_administrator", "provider_configuration" ] }, "PrivateModelsDataHandlingAttestationStatus": { "type": "string", "description": "Organization declaration for private-model inference data handling.", "enum": [ "unknown", "no_training_no_retention" ] }, "PrivateModelsDataHandlingScope": { "type": "string", "description": "Operations covered by the data-handling declaration.", "enum": [ "organization_private_model_inference" ] }, "PrivateModelsDataHandlingTerms": { "type": "string", "description": "Terms represented by an affirmative declaration.", "enum": [ "no_training_no_retention" ] }, "PrivateModelsDataRetention": { "type": "string", "description": "Retention treatment for a covered data category.", "enum": [ "unknown", "none_after_response" ] }, "PrivateModelsTrainingUse": { "type": "string", "description": "Permitted training use for covered data.", "enum": [ "unknown", "prohibited" ] }, "ProvidersResponse": { "type": "object", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/PublisherOAuthProviderResponse" } } } }, "PublisherAgentBalance": { "type": "object", "required": [ "serenbucks_atomic", "total_available_atomic" ], "properties": { "onchain_atomic": { "type": [ "integer", "null" ], "format": "int64" }, "serenbucks_atomic": { "type": "integer", "format": "int64" }, "total_available_atomic": { "type": "integer", "format": "int64" } } }, "PublisherAnalytics": { "type": "object", "description": "Response for publisher analytics", "required": [ "publisher_id", "templates", "totals" ], "properties": { "publisher_id": { "type": "string", "format": "uuid" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateAnalytics" } }, "totals": { "$ref": "#/components/schemas/PublisherAnalyticsTotals" } } }, "PublisherAnalyticsTotals": { "type": "object", "description": "Aggregated totals for publisher analytics", "required": [ "total_templates", "total_invocations", "successful_invocations", "failed_invocations", "overall_success_rate", "unique_agents_served", "total_revenue_atomic", "total_revenue_usd" ], "properties": { "failed_invocations": { "type": "integer", "format": "int64" }, "overall_success_rate": { "type": "number", "format": "double" }, "successful_invocations": { "type": "integer", "format": "int64" }, "total_invocations": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64" }, "total_revenue_usd": { "type": "string" }, "total_templates": { "type": "integer", "format": "int64" }, "unique_agents_served": { "type": "integer", "format": "int64" } } }, "PublisherCategory": { "type": "string", "description": "Publisher category - the primary classification of what a publisher offers", "enum": [ "database", "integration", "compute" ] }, "PublisherChargeInfo": { "type": "object", "required": [ "id", "status", "amount_atomic", "agent_wallet" ], "properties": { "agent_wallet": { "type": "string" }, "amount_atomic": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "PublisherEarningsResponse": { "type": "object", "description": "Publisher earnings summary response (per asset).", "required": [ "publisher_id", "publisher_name", "publisher_slug", "wallet_address", "asset", "total_revenue", "total_withdrawn", "pending_payout", "available", "total_revenue_atomic", "total_withdrawn_atomic", "pending_payout_atomic", "available_atomic", "request_count" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetInfo" }, "available": { "type": "number", "format": "double" }, "available_atomic": { "type": "integer", "format": "int64" }, "pending_payout": { "type": "number", "format": "double" }, "pending_payout_atomic": { "type": "integer", "format": "int64" }, "publisher_id": { "type": "string", "format": "uuid" }, "publisher_name": { "type": "string" }, "publisher_slug": { "type": "string" }, "request_count": { "type": "integer", "format": "int64", "description": "Count of billable transactions for this asset (query_charge, api_call, service_fee)." }, "total_revenue": { "type": "number", "format": "double" }, "total_revenue_atomic": { "type": "integer", "format": "int64" }, "total_withdrawn": { "type": "number", "format": "double" }, "total_withdrawn_atomic": { "type": "integer", "format": "int64" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" } } }, "PublisherOAuthProviderResponse": { "type": "object", "description": "Response type for OAuth provider (excludes sensitive fields)", "required": [ "id", "slug", "name", "scopes", "is_active", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "custom_auth_params": { "description": "Custom provider-specific authorization URL parameters" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" } } }, "PublisherPayoutInfo": { "type": "object", "required": [ "id", "status", "amount_atomic", "destination_wallet" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "destination_wallet": { "type": "string" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] } } }, "PublisherPayoutResponse": { "type": "object", "description": "Publisher payout response.", "required": [ "id", "publisher_id", "asset", "amount", "amount_atomic", "destination_wallet", "status", "requested_at" ], "properties": { "amount": { "type": "number", "format": "double" }, "amount_atomic": { "type": "integer", "format": "int64" }, "asset": { "$ref": "#/components/schemas/AssetInfo" }, "destination_wallet": { "$ref": "#/components/schemas/WalletAddress" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "publisher_id": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "tx_hash": { "type": [ "string", "null" ] } } }, "PublisherResponse": { "type": "object", "description": "Publisher response (excludes sensitive fields)", "required": [ "id", "name", "slug", "categories", "capabilities", "use_cases", "publisher_type", "wallet_address", "wallet_network_id", "publisher_category", "billing_model", "gateway_fee_percent", "auth_type", "allowed_passthrough_headers", "passthrough_header_rewrite", "request_content_type", "upstream_headers", "ownership_tracking_enabled", "undocumented_endpoint_policy", "is_active", "is_verified", "total_queries", "unique_agents_served", "total_revenue_atomic", "created_at", "updated_at", "requires_user_oauth" ], "properties": { "a2a_agent_card": { "description": "Cached A2A agent card" }, "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (for compute_type = agent)" }, "a2a_health_status": { "type": [ "string", "null" ], "description": "A2A health status: unknown, healthy, unhealthy, unreachable" }, "accepted_assets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssetInfo" }, "description": "Accepted assets for payment" }, "allowed_passthrough_headers": { "type": "array", "items": { "type": "string" } }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\", \"apiKey\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": "string", "description": "Upstream authentication mode." }, "billing_model": { "type": "string" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (for database_type = serendb)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching" }, "categories": { "type": "array", "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "created_at": { "type": "string", "format": "date-time" }, "database_config": { "description": "Provider config (sensitive fields redacted)" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "is_active": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "mcp_capabilities": { "description": "Cached MCP capabilities (tools, resources, prompts)" }, "mcp_discovery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpDiscoveryStatus", "description": "Last MCP discovery attempt, success, and error state." } ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "name": { "type": "string" }, "oauth_provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication" }, "ownership_tracking_enabled": { "type": "boolean" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "pricing": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PricingConfigResponse" }, "description": "Pricing config per asset (if included)" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (for database_type = serendb)" }, "protected_operations": {}, "publisher_category": { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute" }, "publisher_type": { "$ref": "#/components/schemas/PublisherType" }, "request_content_type": { "type": "string", "description": "Content-Type for upstream API requests" }, "requires_user_oauth": { "type": "boolean", "description": "If true, users must connect via OAuth before using this publisher" }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ] }, "resource_id_url_pattern": { "type": [ "string", "null" ] }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration (if publisher has geo-restricted upstream API)" } ] }, "slug": { "type": "string" }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token" }, "total_queries": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Lifetime total revenue across all assets, in atomic units" }, "undocumented_endpoint_policy": { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog" }, "unique_agents_served": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Human-readable use case descriptions" }, "verification_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When verification expires (NULL = no expiry)" }, "wallet_address": { "$ref": "#/components/schemas/WalletAddress" }, "wallet_network_id": { "type": "string", "description": "Network for the wallet address" } } }, "PublisherRootRequest": { "oneOf": [ { "$ref": "#/components/schemas/DatabaseQueryRequest" }, {} ], "description": "Request body for publisher root `POST /publishers/{slug}`.\n\n- For database publishers: use `DatabaseQueryRequest`\n- For API publishers: any JSON body will be proxied to the upstream API root (`/`)" }, "PublisherSuggestion": { "type": "object", "description": "A publisher suggestion with match score and reason", "required": [ "slug", "name", "match_reason", "score", "capabilities" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Publisher-declared capabilities" }, "description": { "type": [ "string", "null" ] }, "match_reason": { "type": "string", "description": "Why this publisher was suggested" }, "mcp_tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/McpToolInfo" }, "description": "Cached MCP tool schemas for MCP publishers" }, "name": { "type": "string" }, "pricing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PricingSummary", "description": "Pricing info" } ] }, "score": { "type": "number", "format": "double", "description": "Match score (0.0 to 1.0)" }, "slug": { "type": "string" } } }, "PublisherType": { "type": "string", "description": "Type of publisher in the store", "enum": [ "individual", "organization", "verified_partner" ] }, "PublisherTypeInstructions": { "type": "object", "description": "Instructions for using different publisher types", "required": [ "api", "mcp", "database" ], "properties": { "api": { "type": "string", "description": "For API publishers" }, "database": { "type": "string", "description": "For database publishers" }, "mcp": { "type": "string", "description": "For MCP publishers" } } }, "QueryParamDefinition": { "type": "object", "description": "Query parameter definition for an endpoint", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description" }, "example": { "type": [ "string", "null" ], "description": "Example value for documentation" }, "name": { "type": "string", "description": "Parameter name (e.g., \"id\", \"limit\")" }, "param_type": { "$ref": "#/components/schemas/ParamType", "description": "Parameter type" }, "required": { "type": "boolean", "description": "Whether this parameter is required" } } }, "QuotaUsage": { "type": "object", "description": "Quota usage summary for an organization", "required": [ "organization_id", "plan", "current_storage_gb", "current_compute_hours", "current_serendb_compute_hours", "current_cloud_compute_hours", "current_projects", "current_branches", "is_over_storage_quota", "is_over_compute_quota", "is_over_projects_quota" ], "properties": { "compute_hours_usage_percent": { "type": [ "number", "null" ], "format": "double" }, "current_branches": { "type": "integer", "format": "int32" }, "current_cloud_compute_hours": { "type": "number", "format": "double" }, "current_compute_hours": { "type": "number", "format": "double" }, "current_projects": { "type": "integer", "format": "int32" }, "current_serendb_compute_hours": { "type": "number", "format": "double" }, "current_storage_gb": { "type": "number", "format": "double" }, "is_over_compute_quota": { "type": "boolean" }, "is_over_projects_quota": { "type": "boolean" }, "is_over_storage_quota": { "type": "boolean" }, "organization_id": { "type": "string", "format": "uuid" }, "plan": { "$ref": "#/components/schemas/Plan" }, "projects_usage_percent": { "type": [ "number", "null" ], "format": "double" }, "storage_usage_percent": { "type": [ "number", "null" ], "format": "double" } } }, "RbacRole": { "type": "object", "description": "Response after creating or updating a role", "required": [ "id", "name", "is_built_in", "permissions", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_built_in": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "ReceivedTransferNotificationSummary": { "type": "object", "required": [ "notification_id", "transfer_id", "amount_atomic", "amount_usd", "sender_display_name", "sender_email", "received_at" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "notification_id": { "type": "string", "format": "uuid" }, "received_at": { "type": "string", "format": "date-time" }, "sender_display_name": { "type": "string" }, "sender_email": { "type": "string" }, "transfer_id": { "type": "string", "format": "uuid" } } }, "RecoveryResponse": { "type": "object", "description": "Response for recovery setup", "required": [ "has_recovery", "has_recovery_email", "message" ], "properties": { "has_recovery": { "type": "boolean", "description": "Whether recovery is now set up" }, "has_recovery_email": { "type": "boolean", "description": "Whether a recovery email is set" }, "message": { "type": "string", "description": "Message about recovery status" }, "recovery_code": { "type": [ "string", "null" ], "description": "Recovery code (only shown once, save it securely!)\nThis is a 24-character code that can be used to recover your account." } } }, "ReferralInfoResponse": { "type": "object", "description": "Response for referral info", "required": [ "referral_code", "referral_url", "total_referrals", "total_earnings_atomic", "total_earnings_usd", "pending_earnings_atomic", "pending_earnings_usd" ], "properties": { "pending_earnings_atomic": { "type": "integer", "format": "int64" }, "pending_earnings_usd": { "type": "string" }, "referral_code": { "type": "string" }, "referral_url": { "type": "string" }, "total_earnings_atomic": { "type": "integer", "format": "int64" }, "total_earnings_usd": { "type": "string" }, "total_referrals": { "type": "integer", "format": "int64" } } }, "RefreshTokenRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "RefundChargeRequest": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } }, "RequiredConnectorRef": { "type": "object", "description": "Reference to a connector the catalog item depends on. `kind` is optional\nmetadata for UI grouping or provider-specific platform hints\n(gmail|slack|browser|telegram|...). The connector itself is resolved by\n`name` against the org's connector inventory at apply time. Messaging\nchannel entries remain provider-defined: Seren's deployment contract uses\nconnector tool refs with capability/scopes metadata rather than a closed\nchannel enum.", "required": [ "name" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "RequiredMcpServerRef": { "type": "object", "description": "Reference to an MCP server entry the catalog item depends on. `semver`\ncarries a constraint expression resolved at apply time against the\ninstalled MCP catalog (validation is shape-only here; resolution lives\nin the deployment apply path).", "required": [ "name", "semver" ], "properties": { "name": { "type": "string" }, "semver": { "type": "string" } } }, "ResendVerificationRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "$ref": "#/components/schemas/Email" } } }, "ResetPasswordRequest": { "type": "object", "required": [ "token", "new_password" ], "properties": { "new_password": { "type": "string" }, "token": { "type": "string" } } }, "ResourceInfo": { "type": "object", "description": "Resource information for x402 V2\n\nIn V2, resource metadata is a top-level field rather than being\nembedded in each payment requirement.", "required": [ "url", "description", "mimeType" ], "properties": { "description": { "type": "string", "description": "Human-readable description of the resource" }, "mimeType": { "type": "string", "description": "MIME type of the resource response" }, "url": { "type": "string", "description": "URL of the resource being paid for" } } }, "RevenueByDay": { "type": "object", "description": "Revenue breakdown by day.", "required": [ "date", "revenue_atomic", "revenue", "query_count", "unique_agents" ], "properties": { "date": { "type": "string", "description": "Date (YYYY-MM-DD)" }, "query_count": { "type": "integer", "format": "int64", "description": "Number of queries on this day" }, "revenue": { "type": "string", "description": "Revenue as decimal string" }, "revenue_atomic": { "type": "integer", "format": "int64", "description": "Revenue on this day (atomic units)" }, "unique_agents": { "type": "integer", "format": "int64", "description": "Number of unique agents on this day" } } }, "RevenueMetrics": { "type": "object", "description": "Revenue metrics with period-over-period comparison.", "required": [ "total_revenue_atomic", "total_revenue", "active_agents", "total_queries", "avg_query_cost_atomic", "revenue_change_pct", "agents_change_pct", "queries_change_pct", "period_start", "period_end" ], "properties": { "active_agents": { "type": "integer", "format": "int64", "description": "Number of active agents in the period" }, "agents_change_pct": { "type": "integer", "format": "int32", "description": "Agent count change from previous period (percentage)" }, "avg_query_cost_atomic": { "type": "integer", "format": "int64", "description": "Average query cost (atomic units)" }, "period_end": { "type": "string", "description": "Period end date (ISO 8601)" }, "period_start": { "type": "string", "description": "Period start date (ISO 8601)" }, "queries_change_pct": { "type": "integer", "format": "int32", "description": "Query count change from previous period (percentage)" }, "revenue_change_pct": { "type": "integer", "format": "int32", "description": "Revenue change from previous period (percentage, e.g., 15 = +15%)" }, "total_queries": { "type": "integer", "format": "int64", "description": "Total queries executed in the period" }, "total_revenue": { "type": "string", "description": "Total revenue as decimal string" }, "total_revenue_atomic": { "type": "integer", "format": "int64", "description": "Total revenue in the period (atomic units)" } } }, "RevokeResponse": { "type": "object", "required": [ "success", "message" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "Session": { "type": "object", "description": "Response for listing user sessions (hides sensitive token hash)", "required": [ "id", "last_active_at", "created_at", "expires_at", "is_current" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": [ "string", "null" ] }, "is_current": { "type": "boolean" }, "last_active_at": { "type": "string", "format": "date-time" }, "user_agent": { "type": [ "string", "null" ] } } }, "SessionsRevoked": { "type": "object", "required": [ "message", "revoked_count" ], "properties": { "message": { "type": "string" }, "revoked_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SetDefaultConnectionResponse": { "type": "object", "required": [ "connection" ], "properties": { "connection": { "$ref": "#/components/schemas/UserOAuthConnectionResponse" } } }, "SetRecoveryRequest": { "type": "object", "description": "Request to set up account recovery", "properties": { "email": { "type": [ "string", "null" ], "description": "Email address for account recovery (optional, for human contact)" } } }, "SettlementReceiptResponse": { "type": "object", "description": "Settlement state for one priced publisher operation.", "required": [ "receipt_id", "status", "asset", "updated_at" ], "properties": { "asset": { "type": "string" }, "charged_micros": { "type": [ "integer", "null" ], "format": "int64", "description": "Gross settled cost in micro-units of the named asset.\n\nPending receipts report no settled amount. Cancelled and expired receipts\nreport zero. Refunded receipts retain the original gross cost.", "minimum": 0 }, "receipt_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SetupInstructions": { "type": "object", "description": "Setup instructions for new agents", "required": [ "step_1", "step_2", "step_3", "step_4" ], "properties": { "step_1": { "type": "string", "description": "Step 1: Save your API key" }, "step_2": { "type": "string", "description": "Step 2: Set up authentication header" }, "step_3": { "type": "string", "description": "Step 3: Browse publishers" }, "step_4": { "$ref": "#/components/schemas/PublisherTypeInstructions", "description": "Step 4: Use publishers by type" } } }, "SignupRequest": { "type": "object", "required": [ "email", "password", "name" ], "properties": { "email": { "$ref": "#/components/schemas/Email" }, "name": { "type": "string" }, "password": { "type": "string" }, "referral_code": { "type": [ "string", "null" ], "description": "Optional referral code for affiliate tracking" } } }, "SignupResult": { "type": "object", "required": [ "user", "message" ], "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfo" } } }, "SkillFiles": { "type": "object", "description": "Skill files and documentation links", "required": [ "skill_md", "docs" ], "properties": { "docs": { "type": "string", "description": "Link to the documentation" }, "skill_md": { "type": "string", "description": "Link to the main skill.md file" } } }, "SlashChargeRequest": { "type": "object", "required": [ "slash_amount_atomic", "reason" ], "properties": { "reason": { "type": "string" }, "slash_amount_atomic": { "type": "integer", "format": "int64" } } }, "Slug": { "type": "string", "description": "A validated URL-safe slug.\n\nSlugs must be:\n- 2-64 characters long\n- Lowercase alphanumeric with hyphens\n- Cannot start or end with a hyphen\n- Cannot have consecutive hyphens\n\n# Examples\n\n```\nuse seren_core::models::Slug;\n\nlet slug = Slug::new(\"my-project\").unwrap();\nassert!(Slug::new(\"My Project\").is_err()); // spaces not allowed\nassert!(Slug::new(\"-invalid\").is_err()); // can't start with hyphen\n```", "example": "my-project" }, "StripeChargeId": { "type": "string", "description": "A Stripe Charge ID (ch_xxx).", "example": "ch_1234567890abcdef" }, "StripePaymentIntentId": { "type": "string", "description": "A Stripe Payment Intent ID (pi_xxx).", "example": "pi_1234567890abcdef" }, "StripePaymentMethodId": { "type": "string", "description": "A Stripe Payment Method ID (pm_xxx).", "example": "pm_1234567890abcdef" }, "SubmitTaskInputRequest": { "type": "object", "required": [ "input" ], "properties": { "input": {} } }, "SuggestResponse": { "type": "object", "description": "Response for suggest endpoint\nReturns publisher and agent recommendations based on task/query matching", "required": [ "publishers", "agents" ], "properties": { "agents": { "type": "array", "items": {}, "description": "Matched agents sorted by relevance (agent templates coming soon)" }, "publishers": { "type": "array", "items": { "$ref": "#/components/schemas/PublisherSuggestion" }, "description": "Matched publishers sorted by relevance" } } }, "SupportedKind": { "type": "object", "description": "Supported payment kind (from facilitator /supported endpoint)", "required": [ "x402Version", "scheme", "network" ], "properties": { "extra": { "description": "Extra scheme-specific info" }, "network": { "type": "string", "description": "Network in CAIP-2 format" }, "scheme": { "type": "string", "description": "Payment scheme" }, "x402Version": { "type": "integer", "format": "int32", "description": "x402 protocol version", "minimum": 0 } } }, "SupportedResponse": { "type": "object", "description": "Response from facilitator /supported endpoint", "required": [ "kinds" ], "properties": { "extensions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of supported extensions" }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/SupportedKind" }, "description": "List of supported payment kinds" }, "signers": { "description": "Signer addresses by network family" } } }, "TaskType": { "type": "string", "enum": [ "code_generation", "file_operations", "research", "document_generation", "general_chat" ] }, "TemplateAnalytics": { "type": "object", "description": "Analytics data for a single template", "required": [ "template_id", "slug", "name", "total_invocations", "successful_invocations", "failed_invocations", "success_rate", "unique_agents_served", "total_revenue_atomic", "total_revenue_usd" ], "properties": { "avg_execution_time_ms": { "type": [ "integer", "null" ], "format": "int32" }, "failed_invocations": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "success_rate": { "type": "number", "format": "double" }, "successful_invocations": { "type": "integer", "format": "int64" }, "template_id": { "type": "string", "format": "uuid" }, "total_invocations": { "type": "integer", "format": "int64" }, "total_revenue_atomic": { "type": "integer", "format": "int64" }, "total_revenue_usd": { "type": "string" }, "unique_agents_served": { "type": "integer", "format": "int64" } } }, "TemplateLanguage": { "type": "string", "enum": [ "python", "typescript", "javascript" ] }, "TemplateSetting": { "type": "object", "description": "A publisher-defined user-configurable setting on a template.", "required": [ "key", "label", "settingType", "required" ], "properties": { "default": { "description": "Default value (must match setting_type)" }, "key": { "type": "string", "description": "Machine-readable key (e.g., \"output_format\")" }, "label": { "type": "string", "description": "Human-readable label (e.g., \"Output Format\")" }, "required": { "type": "boolean", "description": "Whether the setting must be provided at invocation time" }, "settingType": { "$ref": "#/components/schemas/TemplateSettingType", "description": "Type of the setting" } } }, "TemplateSettingType": { "oneOf": [ { "type": "string", "description": "Free-form text input", "enum": [ "text" ] }, { "type": "string", "description": "Boolean toggle", "enum": [ "toggle" ] }, { "type": "object", "description": "Selection from a fixed set of options", "required": [ "select" ], "properties": { "select": { "type": "object", "description": "Selection from a fixed set of options", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "type": "string" } } } } } } ], "description": "Types of user-configurable template settings." }, "TemplateSortBy": { "type": "string", "description": "Sorting options for template catalog", "enum": [ "popularity", "price_asc", "price_desc", "newest", "oldest" ] }, "TokenCount": { "type": "object", "properties": { "input": { "type": [ "integer", "null" ], "format": "int32" }, "output": { "type": [ "integer", "null" ], "format": "int32" } } }, "TokenEndpointAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "TokenRefresh": { "type": "object", "required": [ "access_token", "refresh_token", "expires_in" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" }, "refresh_token": { "type": "string" } } }, "TopAgent": { "type": "object", "description": "Top agent by spending.", "required": [ "rank", "agent_wallet", "total_spent_atomic", "total_spent", "balance_atomic", "query_count" ], "properties": { "agent_wallet": { "type": "string", "description": "Agent wallet address" }, "balance_atomic": { "type": "integer", "format": "int64", "description": "Current balance (atomic units)" }, "last_active": { "type": [ "string", "null" ], "description": "Last activity timestamp (ISO 8601)" }, "query_count": { "type": "integer", "format": "int64", "description": "Number of queries executed" }, "rank": { "type": "integer", "format": "int32", "description": "Rank (1 = highest spender)" }, "total_spent": { "type": "string", "description": "Total amount spent as decimal string" }, "total_spent_atomic": { "type": "integer", "format": "int64", "description": "Total amount spent (atomic units)" } } }, "TransactionSummaryResponse": { "type": "object", "description": "Summary statistics for transactions in a date range", "required": [ "starting_balance_atomic", "starting_balance_usd", "total_credits_atomic", "total_credits_usd", "total_debits_atomic", "total_debits_usd", "net_change_atomic", "net_change_usd", "ending_balance_atomic", "ending_balance_usd", "transaction_count" ], "properties": { "ending_balance_atomic": { "type": "integer", "format": "int64", "description": "Wallet balance at the end of the selected period" }, "ending_balance_usd": { "type": "string" }, "net_change_atomic": { "type": "integer", "format": "int64", "description": "Net change (credits - debits, can be negative)" }, "net_change_usd": { "type": "string" }, "period_end": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "starting_balance_atomic": { "type": "integer", "format": "int64", "description": "Wallet balance immediately before the period start" }, "starting_balance_usd": { "type": "string" }, "total_credits_atomic": { "type": "integer", "format": "int64", "description": "Total credits received in the period (positive)" }, "total_credits_usd": { "type": "string" }, "total_debits_atomic": { "type": "integer", "format": "int64", "description": "Total debits spent in the period (positive number representing absolute spend)" }, "total_debits_usd": { "type": "string" }, "transaction_count": { "type": "integer", "format": "int64", "description": "Total number of transactions in the period" } } }, "TypedParam": { "type": "object", "description": "Single typed parameter definition", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "UndocumentedEndpointPolicy": { "type": "string", "description": "Policy for handling requests to paths not in the endpoints catalog", "enum": [ "default_allow", "default_deny" ] }, "UpdateApiKeyScopesRequest": { "type": "object", "description": "Request to replace the least-privilege scopes on an existing user API key.", "required": [ "scopes" ], "properties": { "scopes": { "type": "array", "items": { "type": "string" }, "description": "Complete replacement scope set. At least one valid scope is required." } } }, "UpdateOAuthProviderRequest": { "type": "object", "description": "Request to update an OAuth provider (admin only).\n\nFields use `Option>` where `null` explicitly clears the value.", "properties": { "authorization_url": { "type": [ "string", "null" ] }, "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ], "description": "Optional new client secret (will be re-encrypted). If omitted, keep existing." }, "custom_auth_params": { "description": "Custom provider-specific authorization URL parameters. If omitted, leave unchanged." }, "description": { "type": [ "string", "null" ], "description": "If omitted, leave unchanged. If null, clear." }, "is_active": { "type": [ "boolean", "null" ] }, "logo_url": { "type": [ "string", "null" ], "description": "If omitted, leave unchanged. If null, clear." }, "name": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ], "format": "uuid", "description": "If omitted, leave unchanged. If null, make global. If set, scope to organization." }, "pkce_required": { "type": [ "boolean", "null" ] }, "revocation_url": { "type": [ "string", "null" ], "description": "If omitted, leave unchanged. If null, clear." }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "slug": { "type": [ "string", "null" ] }, "token_endpoint_auth_method": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenEndpointAuthMethod" } ] }, "token_url": { "type": [ "string", "null" ] }, "userinfo_url": { "type": [ "string", "null" ], "description": "If omitted, leave unchanged. If null, clear." } } }, "UpdateOrganizationCustomSkillRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "description": "If omitted, leave unchanged. If null, clear." }, "display_name": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationCustomSkillStatus" } ] } } }, "UpdateOrganizationEmployeeCollaborationPolicyRequest": { "type": "object", "required": [ "expected_policy_revision", "enabled" ], "properties": { "enabled": { "type": "boolean" }, "expected_policy_revision": { "type": "string", "description": "Revision returned by the last policy read. Use `baseline` when no\norganization-specific policy row exists yet." }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" } }, "additionalProperties": false }, "UpdateOrganizationMemoryCapturePolicyRequest": { "type": "object", "required": [ "capture_enabled", "retain_source_allowed", "capture_user_prompts", "capture_assistant_responses", "max_transcript_bytes", "cache_ttl_seconds", "offline_grace_seconds" ], "properties": { "allowed_agent_platforms": { "type": "array", "items": { "type": "string" } }, "cache_ttl_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "capture_assistant_responses": { "type": "boolean" }, "capture_enabled": { "type": "boolean" }, "capture_user_prompts": { "type": "boolean" }, "max_transcript_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "offline_grace_seconds": { "type": "integer", "format": "int32", "minimum": 0 }, "retain_source_allowed": { "type": "boolean" } }, "additionalProperties": false }, "UpdateOrganizationOtpPolicyRequest": { "type": "object", "required": [ "default_verification_ttl" ], "properties": { "default_verification_ttl": { "$ref": "#/components/schemas/OrganizationOtpVerificationTtl" }, "enabled_scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScope" } }, "ttl_overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationOtpScopePolicy" } } } }, "UpdateOrganizationPrivateModelsPolicyRequest": { "type": "object", "required": [ "mode" ], "properties": { "allow_claude_agent": { "type": "boolean" }, "allow_cloud_agent_launch": { "type": "boolean" }, "allow_codex_agent": { "type": "boolean" }, "allow_seren_agent": { "type": "boolean" }, "allow_seren_private_agent": { "type": "boolean" }, "clear_session_database": { "type": "boolean" }, "data_handling_attestation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrivateModelsDataHandlingAttestationStatus", "description": "Authorized policy administrator declaration for private-model inference data handling. Omit or set `null` to preserve the current declaration; set `unknown` to withdraw it." } ] }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "disable_external_model_providers": { "type": "boolean" }, "disable_local_agents": { "type": "boolean" }, "disable_seren_models": { "type": "boolean" }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hide_model_picker": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/OrganizationPrivateModelsMode" }, "model_id": { "type": [ "string", "null" ] }, "ordered_model_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "private_output_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" } ] }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase" } ] }, "session_database_secret_value": { "type": [ "string", "null" ], "description": "Optional new secret value for the private DB URL referenced by `session_database.url_secret_key`.\n\nThis is write-only and is not returned by the API." } } }, "UpdatePasswordRequest": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } }, "UpdatePricingRequest": { "type": "object", "description": "Request to update pricing config", "required": [ "asset_id" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "description": "Asset ID for this pricing config (required)" }, "base_price_per_1000_rows": { "type": [ "string", "null" ] }, "grace_period_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "hourly_rate": { "type": [ "string", "null" ] }, "low_balance_threshold": { "type": [ "string", "null" ] }, "markup_multiplier": { "type": [ "string", "null" ] }, "max_queries_per_minute": { "type": [ "integer", "null" ], "format": "int32" }, "min_charge": { "type": [ "string", "null" ] }, "min_display_price": { "type": [ "string", "null" ], "description": "Minimum price to display in UI for passthrough publishers (informational only)" }, "minimum_balance": { "type": [ "string", "null" ] }, "onchain_enabled": { "type": [ "boolean", "null" ] }, "payment_expiry_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "prepaid_enabled": { "type": [ "boolean", "null" ] }, "price_per_call": { "type": [ "string", "null" ] }, "price_per_delete": { "type": [ "string", "null" ] }, "price_per_execution": { "type": [ "string", "null" ], "description": "Price per execution for agent templates or usage-based billing" }, "price_per_get": { "type": [ "string", "null" ] }, "price_per_patch": { "type": [ "string", "null" ] }, "price_per_post": { "type": [ "string", "null" ] }, "price_per_put": { "type": [ "string", "null" ] }, "pricing_display_text": { "type": [ "string", "null" ], "description": "Text to display for variable pricing (e.g., \"Varies by model\")" }, "pricing_model": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PricingModel" } ] }, "reserve_max_charge": { "type": [ "string", "null" ] }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds (60-86400)" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token" }, "unresolved_fallback_charge": { "type": [ "string", "null" ] } } }, "UpdatePublisherRequest": { "type": "object", "description": "Request to update a publisher", "properties": { "a2a_endpoint_url": { "type": [ "string", "null" ], "description": "A2A endpoint base URL (for compute_type = agent)" }, "add_asset_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Asset IDs to add to accepted assets" }, "allowed_passthrough_headers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Whitelist of agent-provided headers allowed to pass through to upstream" }, "api_headers": { "description": "Headers for API requests (will be encrypted)" }, "api_key_header": { "type": [ "string", "null" ], "description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")" }, "api_key_query_param": { "type": [ "string", "null" ], "description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\")" }, "api_url": { "type": [ "string", "null" ], "description": "External API URL. When present, enables REST proxying." }, "auth_type": { "type": [ "string", "null" ], "description": "Upstream auth mode (\"static\", \"jwt\", \"oauth2_cc\", or \"passthrough\")" }, "base_price_per_1000_rows": { "type": [ "string", "null" ] }, "billing_model": { "type": [ "string", "null" ], "description": "Billing model (\"x402_per_request\", \"prepaid_credits\", \"x402_passthrough\", \"pay_per_use\")" }, "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB branch ID (for database_type = serendb)" }, "capabilities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Publisher-declared capabilities for task matching (e.g., \"web_scraping\", \"ai_search\")" }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "compute_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputeType", "description": "Compute type when publisher_category = compute" } ] }, "database_config": { "description": "Provider-specific configuration" }, "database_name": { "type": [ "string", "null" ], "description": "Database name within the SerenDB project" }, "database_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DatabaseType", "description": "Database type when publisher_category = database" } ] }, "description": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Publisher contact email for notifications and support" }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointDefinition" }, "description": "Structured endpoint definitions for LLM discoverability and access control" }, "gateway_fee_percent": { "type": [ "string", "null" ], "description": "Gateway fee percentage for upstream x402 payments (pass-through)." }, "grace_period_minutes": { "type": [ "integer", "null" ], "format": "int32" }, "hourly_rate": { "type": [ "string", "null" ] }, "integration_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntegrationType", "description": "Primary integration interface when publisher_category = integration" } ] }, "is_active": { "type": [ "boolean", "null" ] }, "jwt_access_key": { "type": [ "string", "null" ], "description": "JWT access key / issuer claim (plaintext)" }, "jwt_algorithm": { "type": [ "string", "null" ], "description": "JWT signing algorithm (\"HS256\", \"HS384\", \"HS512\")" }, "jwt_expiration_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "JWT expiration seconds" }, "jwt_secret_key": { "type": [ "string", "null" ], "description": "JWT secret key (will be encrypted)" }, "logo_url": { "type": [ "string", "null" ], "description": "Optional publisher branding URL" }, "low_balance_threshold": { "type": [ "string", "null" ] }, "markup_multiplier": { "type": [ "string", "null" ] }, "mcp_endpoint": { "type": [ "string", "null" ], "description": "MCP server endpoint URL. When present, enables native MCP proxying." }, "minimum_balance": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "oauth2_client_id": { "type": [ "string", "null" ], "description": "OAuth2 client ID for Client Credentials flow" }, "oauth2_client_secret": { "type": [ "string", "null" ], "description": "OAuth2 client secret for Client Credentials flow (will be encrypted)" }, "oauth2_scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "OAuth2 scopes to request during Client Credentials flow" }, "oauth2_token_url": { "type": [ "string", "null" ], "description": "OAuth2 token endpoint URL for Client Credentials flow" }, "oauth_provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication.\nSet to enable user-specific OAuth tokens for this publisher." }, "ownership_tracking_enabled": { "type": [ "boolean", "null" ], "description": "Enable resource ownership tracking (legacy gateway parity)" }, "passthrough_header_rewrite": { "description": "Map of allowed client-side header names to upstream names. Authorization is target-only." }, "price_per_call": { "type": [ "string", "null" ] }, "price_per_delete": { "type": [ "string", "null" ] }, "price_per_execution": { "type": [ "string", "null" ], "description": "Price per execution for agent templates or usage-based billing" }, "price_per_get": { "type": [ "string", "null" ] }, "price_per_patch": { "type": [ "string", "null" ] }, "price_per_post": { "type": [ "string", "null" ] }, "price_per_put": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SerenDB project ID (for database_type = serendb)" }, "protected_operations": { "description": "Protected operations configuration - legacy, use endpoints[].is_protected instead" }, "publisher_category": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublisherCategory", "description": "Publisher category: database, integration, or compute\nNote: Changing category is a significant change and requires corresponding type field" } ] }, "remove_asset_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Asset IDs to remove from accepted assets" }, "request_content_type": { "type": [ "string", "null" ], "description": "Content-Type for upstream API requests (default: application/json)" }, "requires_user_oauth": { "type": [ "boolean", "null" ], "description": "If true, users must connect via OAuth before using this publisher (BYOC mode).\nRequires oauth_provider_id to be set." }, "reserve_max_charge": { "type": [ "string", "null" ], "description": "Maximum amount to reserve up-front for pay_per_use pre-authorization." }, "resource_description": { "type": [ "string", "null" ] }, "resource_id_response_path": { "type": [ "string", "null" ], "description": "JSONPath to resource ID in response body (for ownership tracking)" }, "resource_id_url_pattern": { "type": [ "string", "null" ], "description": "URL pattern with :resourceId placeholder (for ownership tracking)" }, "resource_name": { "type": [ "string", "null" ] }, "routing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoRoutingConfig", "description": "Geographic routing configuration for geo-restricted upstream APIs" } ] }, "token_cache_ttl_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL for cached exchanged tokens in seconds (60-86400)" }, "token_exchange_method": { "type": [ "string", "null" ], "description": "HTTP method for exchange endpoint (POST or GET)" }, "token_exchange_mode": { "type": [ "string", "null" ], "description": "How to send Seren token: header, body, or query" }, "token_exchange_url": { "type": [ "string", "null" ], "description": "URL to call for exchanging Seren API keys for publisher auth tokens" }, "token_response_field": { "type": [ "string", "null" ], "description": "JSON field in exchange response containing the token (default: access_token)" }, "undocumented_endpoint_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UndocumentedEndpointPolicy", "description": "Policy for handling requests to paths not in the endpoints catalog (\"allow\" or \"block\")" } ] }, "unresolved_fallback_charge": { "type": [ "string", "null" ], "description": "Fallback charge used when pay_per_use cost cannot be resolved from upstream response or token estimates." }, "upstream_api_key": { "type": [ "string", "null" ], "description": "Upstream static API key (will be encrypted)" }, "upstream_cost_response_path": { "type": [ "string", "null" ], "description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\"" }, "upstream_headers": { "description": "Non-sensitive headers to send to upstream API (e.g., User-Agent)" }, "usage_examples": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsageExample" }, "description": "Usage examples showing how to call the publisher's API" }, "use_cases": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Human-readable use case descriptions (e.g., \"Scrape dynamic JavaScript websites\")" }, "wallet_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WalletAddress", "description": "New wallet address for receiving payments" } ] }, "wallet_network_id": { "type": [ "string", "null" ], "description": "Network ID for wallet (must be provided if changing wallet_address)" } } }, "UpdateRoleRequest": { "type": "object", "description": "Request to update a role", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "permissions": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "UpdateWebhookRequest": { "type": "object", "description": "Request to update a webhook", "properties": { "enabled": { "type": [ "boolean", "null" ] }, "events": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "UpsertAgentCredentialSecretRequest": { "type": "object", "required": [ "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "scope": { "$ref": "#/components/schemas/AgentCredentialSecretScope" }, "value": { "type": "string" } } }, "UpsertFederatedResourceRequest": { "type": "object", "description": "Request to upsert a federated resource", "required": [ "resource_type", "external_id", "metadata" ], "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration timestamp" }, "external_id": { "type": "string", "description": "External ID of the resource (unique within publisher + type)" }, "metadata": { "description": "Resource metadata (JSON object with type-specific fields)" }, "org_database_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional database ID where the resource data lives" }, "publisher_slug": { "type": [ "string", "null" ], "description": "Optional publisher slug for disambiguation when an organization owns multiple publishers" }, "resource_type": { "type": "string", "description": "Type of resource being registered" }, "status": { "type": "string", "description": "Resource status (default: \"active\")" } } }, "UpsertOrganizationEmployeeCollaborationAssignmentRequest": { "type": "object", "properties": { "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "expected_assignment_generation": { "type": [ "integer", "null" ], "format": "int64", "description": "Generation returned by the last assignment read. Omit only when\ncreating an assignment that does not yet exist." }, "organization_artifact_write": { "type": "boolean" }, "organization_credential_use": { "type": "boolean" }, "organization_knowledge_read": { "type": "boolean" }, "organization_skill_use": { "type": "boolean" } }, "additionalProperties": false }, "UsageEventDebugRecord": { "type": "object", "description": "Debug view: usage_events entry for an endpoint", "required": [ "event_type", "quantity", "unit", "metadata", "event_timestamp" ], "properties": { "event_timestamp": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "type": "string" }, "quantity": { "type": "number", "format": "double" }, "unit": { "type": "string" } } }, "UsageExample": { "type": "object", "description": "A single usage example showing how to call a publisher's API", "properties": { "curl": { "type": [ "string", "null" ], "description": "Full curl command example" }, "description": { "type": [ "string", "null" ], "description": "Description of what this example demonstrates" }, "title": { "type": [ "string", "null" ], "description": "Short title for the example (e.g., \"Create a collection\")" } } }, "UsageSummary": { "type": "object", "description": "Usage summary for billing period", "required": [ "organization_id", "project_id", "project_name", "project_region", "period_start", "period_end", "compute_hours_small", "compute_hours_medium", "compute_hours_large", "compute_hours_xlarge", "storage_gb_avg", "pitr_gb_avg", "compute_cost_usd", "storage_cost_usd", "total_cost_usd" ], "properties": { "compute_cost_usd": { "type": "string" }, "compute_hours_large": { "type": "number", "format": "double" }, "compute_hours_medium": { "type": "number", "format": "double" }, "compute_hours_small": { "type": "number", "format": "double" }, "compute_hours_xlarge": { "type": "number", "format": "double" }, "organization_id": { "type": "string", "format": "uuid" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "pitr_gb_avg": { "type": "number", "format": "double" }, "project_id": { "type": "string", "format": "uuid" }, "project_name": { "type": "string", "description": "Human-readable project name (denormalized for convenience)." }, "project_region": { "type": "string", "description": "Cloud region for the project (e.g., aws-us-east-1)." }, "storage_cost_usd": { "type": "string" }, "storage_gb_avg": { "type": "number", "format": "double" }, "total_cost_usd": { "type": "string" } } }, "UserInfo": { "type": "object", "description": "Combined user view for API responses", "required": [ "id", "email", "name", "status", "created_at" ], "properties": { "affiliate_referral_code": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "email": { "$ref": "#/components/schemas/Email" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/UserStatus" } } }, "UserMe": { "allOf": [ { "$ref": "#/components/schemas/UserInfo" }, { "type": "object", "required": [ "default_organization_id" ], "properties": { "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present when the API key is bound to an agent identity." }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present when /auth/me is authenticated by an API key." }, "api_key_scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Normalized least-privilege scopes for a restricted API key. Omitted for\nsigned user sessions and unrestricted user API keys." }, "api_key_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiKeyType", "description": "Present when /auth/me is authenticated by an API key." } ] }, "default_organization_id": { "type": "string", "format": "uuid", "description": "The user's default organization ID for API calls requiring an organization context.\nThis is typically the first organization the user joined (their personal org)." } } } ], "description": "Response for GET /auth/me - current user info with default organization" }, "UserOAuthConnectionResponse": { "type": "object", "description": "Response type for user OAuth connection (excludes tokens)", "required": [ "id", "provider_id", "provider_slug", "provider_name", "scopes", "is_valid", "is_default", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "is_valid": { "type": "boolean" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "provider_email": { "type": [ "string", "null" ] }, "provider_id": { "type": "string", "format": "uuid" }, "provider_logo_url": { "type": [ "string", "null" ] }, "provider_name": { "type": "string" }, "provider_slug": { "type": "string" }, "provider_user_id": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "UserStatus": { "type": "string", "description": "User status enum matching PostgreSQL enum", "enum": [ "active", "deleted", "disabled", "paused" ] }, "VerificationSent": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "VerifyEmailRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "WalletAddress": { "type": "string", "description": "A validated wallet address (EVM or Solana).\n\nThis type ensures wallet addresses are validated at construction time.\nStored as TEXT in the database via SQLx's transparent encoding.\n\n# Examples\n\n```\nuse seren_core::models::WalletAddress;\n\n// EVM address\nlet evm = WalletAddress::new(\"0x1234567890123456789012345678901234567890\").unwrap();\n\n// Solana address\nlet sol = WalletAddress::new(\"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\").unwrap();\n\n// Convert to alloy Address for EVM operations\nif let Some(addr) = evm.as_evm() {\n // Use with alloy...\n}\n```", "example": "0x1234567890123456789012345678901234567890" }, "WalletBalanceKind": { "type": "string", "enum": [ "funded", "promotional" ] }, "WalletBalanceResponse": { "type": "object", "description": "Wallet balance response (funded + promotional)", "required": [ "wallet_address", "balance_atomic", "balance_usd", "funded_balance_atomic", "funded_balance_usd", "promotional_balance_atomic", "promotional_balance_usd", "by_source", "total_purchases_cents", "total_purchases_usd", "has_recovery" ], "properties": { "balance_atomic": { "type": "integer", "format": "int64", "description": "Total wallet balance in atomic units" }, "balance_usd": { "type": "string" }, "by_source": { "type": "array", "items": { "$ref": "#/components/schemas/WalletSourceBalance" }, "description": "Breakdown by source" }, "funded_balance_atomic": { "type": "integer", "format": "int64", "description": "Total funded balance (fiat purchases + tier bonuses)" }, "funded_balance_usd": { "type": "string" }, "has_recovery": { "type": "boolean", "description": "Whether recovery is set up for this account" }, "promotional_balance_atomic": { "type": "integer", "format": "int64", "description": "Total promotional balance (bonuses, daily claims, referrals, admin grants)" }, "promotional_balance_usd": { "type": "string" }, "recovery_warning": { "type": [ "string", "null" ], "description": "Warning if funds exist but no recovery is set up" }, "total_purchases_cents": { "type": "integer", "format": "int64", "description": "Total lifetime SerenBucks purchases in cents (for plan upgrade tracking)" }, "total_purchases_usd": { "type": "string" }, "unread_received_transfers": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedTransferNotificationSummary" }, "description": "Recent unread wallet transfer notifications for this account." }, "wallet_address": { "type": "string" } } }, "WalletRecoverRequest": { "type": "object", "description": "Request to recover an agent account using a recovery code.\n\nUse this endpoint when you've lost access to your API key but still have\nyour recovery code (provided when setting up wallet recovery).", "required": [ "recovery_code" ], "properties": { "recovery_code": { "type": "string", "description": "Recovery code (24 characters). Dashes/whitespace are allowed; letters are case-insensitive." } } }, "WalletRecoverResponse": { "type": "object", "description": "Response from wallet recovery endpoint.", "required": [ "success", "message", "agent", "setup", "skill_files", "new_recovery_code" ], "properties": { "agent": { "$ref": "#/components/schemas/AgentInfo", "description": "The recovered agent account (with a new API key)" }, "message": { "type": "string", "description": "Message about recovery result" }, "new_recovery_code": { "type": "string", "description": "New recovery code (the old one has been rotated). Save this securely!" }, "setup": { "$ref": "#/components/schemas/SetupInstructions", "description": "Setup instructions for getting started" }, "skill_files": { "$ref": "#/components/schemas/SkillFiles", "description": "Links to skill files and documentation" }, "success": { "type": "boolean", "description": "Whether recovery was successful" } } }, "WalletSourceBalance": { "type": "object", "description": "Balance by source type", "required": [ "source", "kind", "balance_atomic", "balance_usd" ], "properties": { "balance_atomic": { "type": "integer", "format": "int64" }, "balance_usd": { "type": "string" }, "kind": { "$ref": "#/components/schemas/WalletBalanceKind" }, "source": { "$ref": "#/components/schemas/AgentCreditSource" } } }, "WalletTransactionDirection": { "type": "string", "description": "Response for a single transaction", "enum": [ "credit", "debit" ] }, "WalletTransactionHistoryResponse": { "type": "object", "description": "Response for transaction history", "required": [ "transactions", "total", "total_is_exact", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page when another page may exist." }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "total_is_exact": { "type": "boolean", "description": "Whether `total` is an exact count. When false, `total` is a pagination\nlower bound kept for older offset-based clients." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransactionResponse" } } } }, "WalletTransactionResponse": { "type": "object", "description": "Response for a single transaction", "required": [ "id", "direction", "source", "amount_atomic", "amount_usd", "created_at" ], "properties": { "alert": { "type": [ "string", "null" ], "description": "Optional alert string when the transaction appears anomalously expensive." }, "amount_atomic": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "balance_after_atomic": { "type": [ "integer", "null" ], "format": "int64", "description": "Wallet balance immediately after this debit (debit entries only)" }, "balance_after_usd": { "type": [ "string", "null" ], "description": "Wallet balance immediately after this debit in USD (debit entries only)" }, "bonus_amount_usd": { "type": [ "string", "null" ], "description": "Bonus amount included in this grant (only for tier_bonus source)" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "direction": { "$ref": "#/components/schemas/WalletTransactionDirection" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "paid_amount_usd": { "type": [ "string", "null" ], "description": "Original Stripe payment amount (only for fiat_purchase source)" }, "prompt": { "type": [ "string", "null" ], "description": "Prompt/query text associated with this transaction (when available)" }, "publisher_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Publisher context for this transaction (when available)" }, "publisher_name": { "type": [ "string", "null" ], "description": "Publisher name (when available)" }, "remaining_atomic": { "type": [ "integer", "null" ], "format": "int64", "description": "Remaining amount on the grant (credit entries only)" }, "remaining_usd": { "type": [ "string", "null" ], "description": "Remaining amount on the grant in USD (credit entries only)" }, "source": { "type": "string" } } }, "WalletTransferClaimRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "WalletTransferClaimResponse": { "type": "object", "required": [ "pending_transfer_id", "amount_received_cents", "balance_after_cents" ], "properties": { "amount_received_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "pending_transfer_id": { "type": "string", "format": "uuid" } } }, "WalletTransferDirection": { "type": "string", "enum": [ "sent", "received", "all" ] }, "WalletTransferExecuteResponse": { "oneOf": [ { "type": "object", "required": [ "transfer_id", "status", "settled_at", "balance_after_cents", "kind" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "kind": { "type": "string", "enum": [ "instant" ] }, "settled_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "transfer_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "pending_transfer_id", "status", "expires_at", "balance_after_cents", "kind" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "expires_at": { "type": "string", "format": "date-time" }, "invite_token": { "type": [ "string", "null" ] }, "invite_url": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "pending_invite" ] }, "pending_transfer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } } ] }, "WalletTransferListItem": { "type": "object", "required": [ "id", "kind", "direction", "status", "counterparty", "amount_cents", "amount_usd", "created_at" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "amount_usd": { "type": "string" }, "counterparty": { "type": "string" }, "counterparty_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "direction": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "memo": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "WalletTransferListResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransferListItem" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "WalletTransferPreviewResponse": { "oneOf": [ { "type": "object", "required": [ "recipient", "amount_cents", "balance_after_cents", "daily_remaining_cents", "kind" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "daily_remaining_cents": { "type": "integer", "format": "int64" }, "kind": { "type": "string", "enum": [ "instant" ] }, "memo": { "type": [ "string", "null" ] }, "recipient": { "$ref": "#/components/schemas/WalletTransferRecipient" } } }, { "type": "object", "required": [ "recipient_email", "amount_cents", "balance_after_cents", "daily_remaining_cents", "expires_at_estimate", "kind" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "balance_after_cents": { "type": "integer", "format": "int64" }, "daily_remaining_cents": { "type": "integer", "format": "int64" }, "expires_at_estimate": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "pending_invite" ] }, "memo": { "type": [ "string", "null" ] }, "recipient_email": { "type": "string" } } } ] }, "WalletTransferRecallResponse": { "type": "object", "required": [ "pending_transfer_id", "status", "refunded_amount_cents", "balance_after_cents" ], "properties": { "balance_after_cents": { "type": "integer", "format": "int64" }, "pending_transfer_id": { "type": "string", "format": "uuid" }, "refunded_amount_cents": { "type": "integer", "format": "int64" }, "status": { "type": "string" } } }, "WalletTransferRecipient": { "type": "object", "required": [ "user_id", "display_name" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "WalletTransferRequest": { "type": "object", "required": [ "recipient_email", "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "memo": { "type": [ "string", "null" ] }, "recipient_email": { "type": "string" } } }, "WebhookCreated": { "type": "object", "description": "Webhook created response (includes secret on creation only)", "required": [ "webhook", "secret" ], "properties": { "secret": { "type": "string", "description": "The webhook secret - only shown once at creation time" }, "webhook": { "$ref": "#/components/schemas/WebhookInfo" } } }, "WebhookDelivery": { "type": "object", "description": "Webhook delivery record", "required": [ "id", "webhook_id", "event_type", "event_id", "payload", "attempt_number", "created_at" ], "properties": { "attempt_number": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "payload": { "type": "object" }, "response_body": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ], "format": "int32" }, "webhook_id": { "type": "string", "format": "uuid" } } }, "WebhookInfo": { "type": "object", "description": "Webhook response (hides secret)", "required": [ "id", "organization_id", "name", "url", "events", "enabled", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "url": { "type": "string" } } }, "AddIpAllowListRequest": { "type": "object", "description": "Request to add an IP to the allow list", "required": [ "ip_address" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description for this IP entry" }, "ip_address": { "type": "string", "description": "IP address or CIDR range (e.g., \"192.168.1.0/24\" or \"10.0.0.1\")" } } }, "AssignProjectVpcEndpointRequest": { "type": "object", "required": [ "vpc_endpoint_id" ], "properties": { "label": { "type": [ "string", "null" ] }, "vpc_endpoint_id": { "type": "string", "format": "uuid" } } }, "Branch": { "type": "object", "description": "Branch represents a SerenDB timeline (database copy)", "required": [ "id", "name", "project_id", "timeline_id", "created_by", "created_at", "updated_at", "protected", "archived" ], "properties": { "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "init_source": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean", "description": "Computed field: true if this branch is the project's default branch.\nNot stored in DB - computed by comparing branch.id with project.default_branch_id." }, "last_reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "logical_size_bytes": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "parent_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_lsn": { "type": [ "string", "null" ] }, "parent_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "physical_size_bytes": { "type": "integer", "format": "int64" }, "project_id": { "type": "string", "format": "uuid" }, "protected": { "type": "boolean" }, "timeline_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BranchCreated": { "type": "object", "description": "Response after creating a branch", "required": [ "id", "name", "project_id", "timeline_id", "created_at", "protected", "archived" ], "properties": { "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "init_source": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean", "description": "True if this is the project's default branch" }, "logical_size_bytes": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "parent_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_lsn": { "type": [ "string", "null" ] }, "parent_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "physical_size_bytes": { "type": "integer", "format": "int64" }, "project_id": { "type": "string", "format": "uuid" }, "protected": { "type": "boolean" }, "timeline_id": { "type": "string", "format": "uuid" } } }, "BranchCreationResult": { "type": "object", "description": "Response wrapper returned when branch creation provisions auxiliary resources", "required": [ "branch" ], "properties": { "branch": { "$ref": "#/components/schemas/BranchCreated" }, "endpoint_error": { "type": [ "string", "null" ], "description": "Error message if endpoint provisioning failed.\nWhen present, the branch was created successfully but the endpoint failed.\nThe UI should show a \"Retry\" or \"Add Compute\" button." }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointCreated" } } } }, "BranchDetail": { "type": "object", "description": "Response for branch detail information", "required": [ "branch_id", "timeline_id", "last_record_lsn", "disk_consistent_lsn", "state" ], "properties": { "ancestor_lsn": { "type": [ "string", "null" ] }, "ancestor_timeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "branch_id": { "type": "string", "format": "uuid" }, "current_logical_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "disk_consistent_lsn": { "type": "string" }, "last_record_lsn": { "type": "string" }, "prev_record_lsn": { "type": [ "string", "null" ] }, "remote_consistent_lsn": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "timeline_id": { "type": "string", "format": "uuid" } } }, "BranchEndpointRequest": { "type": "object", "properties": { "endpoint_type": { "type": [ "string", "null" ] }, "settings": {} } }, "BranchProtection": { "type": "object", "description": "Branch protection response (API output)", "required": [ "id", "project_id", "branch_id", "prevent_deletion", "prevent_reset", "require_approval_for_changes", "allowed_bypass_roles", "created_at", "updated_at" ], "properties": { "allowed_bypass_roles": { "type": "array", "items": { "type": "string" } }, "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "prevent_deletion": { "type": "boolean" }, "prevent_reset": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "require_approval_for_changes": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BranchRestored": { "type": "object", "description": "Response after restoring a branch", "required": [ "branch", "backup_branch" ], "properties": { "backup_branch": { "$ref": "#/components/schemas/Branch", "description": "The backup branch containing the pre-restore state" }, "branch": { "$ref": "#/components/schemas/Branch", "description": "The restored branch" } } }, "ConnectionString": { "type": "object", "description": "Response for a single, canonical connection string.\n\nThe backend always prefers SerenDB proxy-based connection strings when\nproxy configuration is available, and falls back to direct compute\nconnection strings only when the proxy is not configured.", "required": [ "connection_string" ], "properties": { "connection_string": { "type": "string", "description": "Fully resolved PostgreSQL connection string (proxy preferred)." } } }, "CreateBranchProtectionRequest": { "type": "object", "description": "Request to create or update branch protection", "properties": { "allowed_bypass_roles": { "type": "array", "items": { "type": "string" } }, "prevent_deletion": { "type": "boolean" }, "prevent_reset": { "type": "boolean" }, "require_approval_for_changes": { "type": "boolean" } } }, "CreateBranchRequest": { "type": "object", "description": "Request to create a new branch", "required": [ "name" ], "properties": { "add_endpoint": { "type": "boolean", "description": "Whether to automatically create an endpoint for this branch.\nDefaults to true.\nSet to false to create a branch without compute (equivalent to --no-compute)." }, "archived": { "type": [ "boolean", "null" ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/BranchEndpointRequest" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration timestamp for auto-deletion of this branch.\nUseful for temporary dev/preview branches." }, "init_source": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "parent_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_lsn": { "type": [ "string", "null" ] }, "parent_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "protected": { "type": [ "boolean", "null" ] }, "schema_only": { "type": "boolean", "description": "Create branch with schema only (no data).\nWhen true, only the database schema is copied, not the data." } } }, "CreateDatabaseRequest": { "type": "object", "description": "Request to create a new database", "required": [ "name" ], "properties": { "name": { "type": "string" }, "owner_name": { "type": [ "string", "null" ] } } }, "CreateDbRoleRequest": { "type": "object", "description": "Request to create a new PostgreSQL database role", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateEndpointRequest": { "type": "object", "description": "Request to create a new endpoint", "properties": { "autoscaling_max": { "type": "integer", "format": "int32" }, "autoscaling_min": { "type": "integer", "format": "int32" }, "compute_unit": { "type": "string" }, "endpoint_type": { "$ref": "#/components/schemas/EndpointType", "description": "Type of endpoint: read_write (default) or read_only (replica)" }, "name": { "type": "string", "description": "Optional name for the endpoint. If not provided, a name will be auto-generated." }, "pooler_enabled": { "type": "boolean" }, "pooler_mode": { "$ref": "#/components/schemas/PoolerMode" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" } } }, "CreateProjectRequest": { "type": "object", "description": "Request to create a new project", "required": [ "name", "region" ], "properties": { "block_public_connections": { "type": [ "boolean", "null" ] }, "block_vpc_connections": { "type": [ "boolean", "null" ] }, "compute_unit_max": { "type": [ "integer", "null" ], "format": "int32" }, "compute_unit_min": { "type": [ "integer", "null" ], "format": "int32" }, "enable_logical_replication": { "type": [ "boolean", "null" ], "description": "Enable logical replication for this project. Sets wal_level=logical for all compute endpoints.\nOnce enabled, this cannot be disabled." }, "hipaa": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "protected_branches_only": { "type": [ "boolean", "null" ] }, "region": { "type": "string" } } }, "CreatePublicationRequest": { "type": "object", "description": "Request to create a publication", "required": [ "name" ], "properties": { "name": { "type": "string" }, "publish_delete": { "type": "boolean" }, "publish_insert": { "type": "boolean" }, "publish_truncate": { "type": "boolean" }, "publish_update": { "type": "boolean" }, "tables": { "type": "array", "items": { "type": "string" }, "description": "Tables to include (empty/null means ALL TABLES)" } } }, "CreateReplicationSlotRequest": { "type": "object", "description": "Request to create a replication slot", "required": [ "name" ], "properties": { "name": { "type": "string" }, "plugin": { "type": "string", "description": "Plugin for logical slots (default: pgoutput)" }, "slot_type": { "type": "string", "description": "Slot type: logical or physical (default: logical)" } } }, "BranchResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Branch represents a SerenDB timeline (database copy)", "required": [ "id", "name", "project_id", "timeline_id", "created_by", "created_at", "updated_at", "protected", "archived" ], "properties": { "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "init_source": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean", "description": "Computed field: true if this branch is the project's default branch.\nNot stored in DB - computed by comparing branch.id with project.default_branch_id." }, "last_reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "logical_size_bytes": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "parent_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_lsn": { "type": [ "string", "null" ] }, "parent_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "physical_size_bytes": { "type": "integer", "format": "int64" }, "project_id": { "type": "string", "format": "uuid" }, "protected": { "type": "boolean" }, "timeline_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "BranchCreationResultResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response wrapper returned when branch creation provisions auxiliary resources", "required": [ "branch" ], "properties": { "branch": { "$ref": "#/components/schemas/BranchCreated" }, "endpoint_error": { "type": [ "string", "null" ], "description": "Error message if endpoint provisioning failed.\nWhen present, the branch was created successfully but the endpoint failed.\nThe UI should show a \"Retry\" or \"Add Compute\" button." }, "endpoints": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/EndpointCreated" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BranchDetail": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for branch detail information", "required": [ "branch_id", "timeline_id", "last_record_lsn", "disk_consistent_lsn", "state" ], "properties": { "ancestor_lsn": { "type": [ "string", "null" ] }, "ancestor_timeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "branch_id": { "type": "string", "format": "uuid" }, "current_logical_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "disk_consistent_lsn": { "type": "string" }, "last_record_lsn": { "type": "string" }, "prev_record_lsn": { "type": [ "string", "null" ] }, "remote_consistent_lsn": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "timeline_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BranchProtection": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Branch protection response (API output)", "required": [ "id", "project_id", "branch_id", "prevent_deletion", "prevent_reset", "require_approval_for_changes", "allowed_bypass_roles", "created_at", "updated_at" ], "properties": { "allowed_bypass_roles": { "type": "array", "items": { "type": "string" } }, "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "prevent_deletion": { "type": "boolean" }, "prevent_reset": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "require_approval_for_changes": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BranchRestored": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after restoring a branch", "required": [ "branch", "backup_branch" ], "properties": { "backup_branch": { "$ref": "#/components/schemas/Branch", "description": "The backup branch containing the pre-restore state" }, "branch": { "$ref": "#/components/schemas/Branch", "description": "The restored branch" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ConnectionString": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for a single, canonical connection string.\n\nThe backend always prefers SerenDB proxy-based connection strings when\nproxy configuration is available, and falls back to direct compute\nconnection strings only when the proxy is not configured.", "required": [ "connection_string" ], "properties": { "connection_string": { "type": "string", "description": "Fully resolved PostgreSQL connection string (proxy preferred)." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DatabaseCreatedResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating a database", "required": [ "id", "name", "branch_id", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_role_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DatabaseWithOwnerResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Database with owner role name included", "required": [ "id", "name", "branch_id", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_name": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "EndpointCreatedResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating an endpoint", "required": [ "id", "name", "branch_id", "compute_unit", "suspend_timeout_seconds", "effective_suspend_timeout_seconds", "endpoint_type", "status", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "compute_unit": { "type": "string" }, "connection_string": { "type": [ "string", "null" ] }, "connection_string_direct": { "type": [ "string", "null" ] }, "connection_string_pooled": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "endpoint_type": { "type": "string", "description": "Type of endpoint: read_write (primary) or read_only (replica)" }, "id": { "type": "string", "format": "uuid" }, "internal_http_address": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pg_address": { "type": [ "string", "null" ] }, "primary_endpoint_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Reference to the primary endpoint for read replicas" }, "status": { "type": "string" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "warnings": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_EndpointResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Endpoint" }, { "type": "object", "required": [ "effective_suspend_timeout_seconds" ], "properties": { "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" } } } ] }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "EndpointStatusInfoResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Status response used by lifecycle endpoints", "required": [ "id", "status", "k8s_ready", "suspend_timeout_seconds", "effective_suspend_timeout_seconds" ], "properties": { "compute_status": { "type": [ "string", "null" ] }, "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "k8s_ready": { "type": "boolean" }, "status": { "type": "string" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_IpAllowList": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "IP allow list entry for project-level access control", "required": [ "id", "project_id", "ip_address", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": "string", "description": "IP address or CIDR range (stored as PostgreSQL CIDR type)" }, "project_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_LogicalReplicationSettings": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Project logical replication settings", "required": [ "project_id", "enabled", "publications_count", "slots_count" ], "properties": { "enabled": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "publications_count": { "type": "integer", "format": "int64" }, "slots_count": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_LsnByTimestamp": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for LSN by timestamp query", "required": [ "lsn" ], "properties": { "lsn": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "ProjectResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Project represents a SerenDB database instance", "required": [ "id", "name", "organization_id", "region", "tenant_id", "created_by", "created_at", "updated_at", "block_public_connections", "block_vpc_connections", "hipaa", "protected_branches_only", "compute_unit_min", "compute_unit_max" ], "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "block_public_connections": { "type": "boolean" }, "block_vpc_connections": { "type": "boolean" }, "branch_count": { "type": "integer", "format": "int32" }, "compute_last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_unit_max": { "type": "integer", "format": "int32" }, "compute_unit_min": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "default_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_compute_size_max": { "type": "number", "format": "float" }, "default_compute_size_min": { "type": "number", "format": "float" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "enable_logical_replication": { "type": "boolean" }, "hipaa": { "type": "boolean" }, "history_retention_seconds": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "is_service_project": { "type": "boolean", "description": "Whether this is a service project (hidden from normal listings, contains seren_* databases)" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "postgres_version": { "type": "string" }, "protected_branches_only": { "type": "boolean" }, "region": { "type": "string" }, "storage_bytes": { "type": "integer", "format": "int64" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "ProjectConnectionUriDataResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "uri" ], "properties": { "uri": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ProjectConsumption": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "ProjectConsumption wraps consumption data for API responses", "required": [ "project_id", "from", "to", "periods", "current_month" ], "properties": { "current_month": { "$ref": "#/components/schemas/ConsumptionSummary" }, "from": { "type": "string", "format": "date-time" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionPeriodData" } }, "project_id": { "type": "string", "format": "uuid" }, "to": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "ProjectCreatedResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating a project", "required": [ "id", "name", "organization_id", "region", "tenant_id", "created_at", "block_public_connections", "block_vpc_connections", "hipaa", "protected_branches_only", "compute_unit_min", "compute_unit_max" ], "properties": { "block_public_connections": { "type": "boolean" }, "block_vpc_connections": { "type": "boolean" }, "branch_count": { "type": "integer", "format": "int32" }, "compute_unit_max": { "type": "integer", "format": "int32" }, "compute_unit_min": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "default_branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The main branch for this project" }, "enable_logical_replication": { "type": "boolean", "description": "Whether logical replication is enabled for this project" }, "hipaa": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "is_service_project": { "type": "boolean", "description": "Whether this is a service project (hidden from normal listings, contains seren_* databases)" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "postgres_version": { "type": "string" }, "protected_branches_only": { "type": "boolean" }, "region": { "type": "string" }, "storage_bytes": { "type": "integer", "format": "int64" }, "tenant_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ProjectSize": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for project storage size", "required": [ "project_id", "size_bytes" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 0 } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PublicationInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Publication response (API output)", "required": [ "id", "project_id", "branch_id", "name", "tables", "publish_insert", "publish_update", "publish_delete", "publish_truncate", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "publish_delete": { "type": "boolean" }, "publish_insert": { "type": "boolean" }, "publish_truncate": { "type": "boolean" }, "publish_update": { "type": "boolean" }, "tables": { "type": "array", "items": { "type": "string" }, "description": "Tables to replicate (empty means ALL TABLES)" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_QueryResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Query result returned to the caller.", "required": [ "columns", "rows", "row_count" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ReplicationSlotInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Replication slot response (API output)", "required": [ "id", "project_id", "branch_id", "name", "slot_type", "plugin", "status", "created_at", "updated_at" ], "properties": { "active_pid": { "type": [ "integer", "null" ], "format": "int32" }, "branch_id": { "type": "string", "format": "uuid" }, "confirmed_flush_lsn": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plugin": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "restart_lsn": { "type": [ "string", "null" ] }, "slot_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "RoleCreatedResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after creating a role", "required": [ "id", "name", "branch_id", "password", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "password": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "RolePasswordResetResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response after resetting password", "required": [ "role_id", "password" ], "properties": { "password": { "type": "string" }, "role_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_TimestampByLsn": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for timestamp by LSN query", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Value": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": {}, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "BranchesResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Branch represents a SerenDB timeline (database copy)", "required": [ "id", "name", "project_id", "timeline_id", "created_by", "created_at", "updated_at", "protected", "archived" ], "properties": { "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "init_source": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean", "description": "Computed field: true if this branch is the project's default branch.\nNot stored in DB - computed by comparing branch.id with project.default_branch_id." }, "last_reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "logical_size_bytes": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "parent_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_lsn": { "type": [ "string", "null" ] }, "parent_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "physical_size_bytes": { "type": "integer", "format": "int64" }, "project_id": { "type": "string", "format": "uuid" }, "protected": { "type": "boolean" }, "timeline_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_BranchProtection": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Branch protection response (API output)", "required": [ "id", "project_id", "branch_id", "prevent_deletion", "prevent_reset", "require_approval_for_changes", "allowed_bypass_roles", "created_at", "updated_at" ], "properties": { "allowed_bypass_roles": { "type": "array", "items": { "type": "string" } }, "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "prevent_deletion": { "type": "boolean" }, "prevent_reset": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "require_approval_for_changes": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DatabasesWithOwnerResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Database with owner role name included", "required": [ "id", "name", "branch_id", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_name": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_EndpointResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Endpoint" }, { "type": "object", "required": [ "effective_suspend_timeout_seconds" ], "properties": { "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" } } } ] } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_IpAllowList": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "IP allow list entry for project-level access control", "required": [ "id", "project_id", "ip_address", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": "string", "description": "IP address or CIDR range (stored as PostgreSQL CIDR type)" }, "project_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "PaginatedProjectResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Project represents a SerenDB database instance", "required": [ "id", "name", "organization_id", "region", "tenant_id", "created_by", "created_at", "updated_at", "block_public_connections", "block_vpc_connections", "hipaa", "protected_branches_only", "compute_unit_min", "compute_unit_max" ], "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "block_public_connections": { "type": "boolean" }, "block_vpc_connections": { "type": "boolean" }, "branch_count": { "type": "integer", "format": "int32" }, "compute_last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_unit_max": { "type": "integer", "format": "int32" }, "compute_unit_min": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "default_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_compute_size_max": { "type": "number", "format": "float" }, "default_compute_size_min": { "type": "number", "format": "float" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "enable_logical_replication": { "type": "boolean" }, "hipaa": { "type": "boolean" }, "history_retention_seconds": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "is_service_project": { "type": "boolean", "description": "Whether this is a service project (hidden from normal listings, contains seren_* databases)" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "postgres_version": { "type": "string" }, "protected_branches_only": { "type": "boolean" }, "region": { "type": "string" }, "storage_bytes": { "type": "integer", "format": "int64" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_PublicationInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Publication response (API output)", "required": [ "id", "project_id", "branch_id", "name", "tables", "publish_insert", "publish_update", "publish_delete", "publish_truncate", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "publish_delete": { "type": "boolean" }, "publish_insert": { "type": "boolean" }, "publish_truncate": { "type": "boolean" }, "publish_update": { "type": "boolean" }, "tables": { "type": "array", "items": { "type": "string" }, "description": "Tables to replicate (empty means ALL TABLES)" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_ReplicationSlotInfo": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Replication slot response (API output)", "required": [ "id", "project_id", "branch_id", "name", "slot_type", "plugin", "status", "created_at", "updated_at" ], "properties": { "active_pid": { "type": [ "integer", "null" ], "format": "int32" }, "branch_id": { "type": "string", "format": "uuid" }, "confirmed_flush_lsn": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plugin": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "restart_lsn": { "type": [ "string", "null" ] }, "slot_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "RoleInfosResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Public role info (without password hash)", "required": [ "id", "name", "branch_id", "protected", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "protected": { "type": "boolean" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DatabaseCreated": { "type": "object", "description": "Response after creating a database", "required": [ "id", "name", "branch_id", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_role_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "DatabaseWithOwner": { "type": "object", "description": "Database with owner role name included", "required": [ "id", "name", "branch_id", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "owner_name": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "Endpoint": { "type": "object", "description": "Endpoint represents a compute instance for a branch", "required": [ "id", "name", "branch_id", "tenant_id", "timeline_id", "endpoint_type", "compute_unit", "autoscaling_min", "autoscaling_max", "suspend_timeout_seconds", "status", "pooler_enabled", "pooler_mode", "created_by", "created_at", "updated_at" ], "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "autoscaling_max": { "type": "integer", "format": "int32" }, "autoscaling_min": { "type": "integer", "format": "int32" }, "branch_id": { "type": "string", "format": "uuid" }, "compute_unit": { "type": "string" }, "connection_count": { "type": "integer", "format": "int32" }, "connection_string": { "type": [ "string", "null" ] }, "connection_string_direct": { "type": [ "string", "null" ] }, "connection_string_pooled": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "current_state": { "type": [ "string", "null" ] }, "endpoint_type": { "type": "string", "description": "Type of endpoint: read_write (primary) or read_only (replica)" }, "id": { "type": "string", "format": "uuid" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "pooler_enabled": { "type": "boolean" }, "pooler_mode": { "type": "string" }, "primary_endpoint_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Reference to the primary endpoint for read replicas (NULL for read_write endpoints)" }, "proxy_host": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "tenant_id": { "type": "string", "format": "uuid" }, "timeline_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EndpointCreated": { "type": "object", "description": "Response after creating an endpoint", "required": [ "id", "name", "branch_id", "compute_unit", "suspend_timeout_seconds", "effective_suspend_timeout_seconds", "endpoint_type", "status", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "compute_unit": { "type": "string" }, "connection_string": { "type": [ "string", "null" ] }, "connection_string_direct": { "type": [ "string", "null" ] }, "connection_string_pooled": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "endpoint_type": { "type": "string", "description": "Type of endpoint: read_write (primary) or read_only (replica)" }, "id": { "type": "string", "format": "uuid" }, "internal_http_address": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pg_address": { "type": [ "string", "null" ] }, "primary_endpoint_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Reference to the primary endpoint for read replicas" }, "status": { "type": "string" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "warnings": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "EndpointResponse": { "allOf": [ { "$ref": "#/components/schemas/Endpoint" }, { "type": "object", "required": [ "effective_suspend_timeout_seconds" ], "properties": { "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" } } } ] }, "EndpointStatusInfo": { "type": "object", "description": "Status response used by lifecycle endpoints", "required": [ "id", "status", "k8s_ready", "suspend_timeout_seconds", "effective_suspend_timeout_seconds" ], "properties": { "compute_status": { "type": [ "string", "null" ] }, "effective_suspend_timeout_seconds": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "k8s_ready": { "type": "boolean" }, "status": { "type": "string" }, "suspend_timeout_seconds": { "type": "integer", "format": "int32" } } }, "EndpointType": { "type": "string", "description": "Endpoint type enum - distinguishes between primary and replica endpoints", "enum": [ "read_write", "read_only" ] }, "IpAllowList": { "type": "object", "description": "IP allow list entry for project-level access control", "required": [ "id", "project_id", "ip_address", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": "string", "description": "IP address or CIDR range (stored as PostgreSQL CIDR type)" }, "project_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LogicalReplicationSettings": { "type": "object", "description": "Project logical replication settings", "required": [ "project_id", "enabled", "publications_count", "slots_count" ], "properties": { "enabled": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "publications_count": { "type": "integer", "format": "int64" }, "slots_count": { "type": "integer", "format": "int64" } } }, "LsnByTimestamp": { "type": "object", "description": "Response for LSN by timestamp query", "required": [ "lsn" ], "properties": { "lsn": { "type": "string" } } }, "ManagedSkillDatabaseScope": { "type": "string", "enum": [ "organization", "user" ] }, "PointInTime": { "oneOf": [ { "type": "object", "description": "ISO 8601 timestamp (e.g., \"2024-05-06T10:00:00.000Z\")", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time" } } }, { "type": "object", "description": "Log Sequence Number from PostgreSQL WAL", "required": [ "lsn" ], "properties": { "lsn": { "type": "string" } } } ], "description": "Point in time specification (timestamp or LSN)" }, "PoolerMode": { "type": "string", "description": "Pooler mode enum", "enum": [ "transaction", "session" ] }, "Project": { "type": "object", "description": "Project represents a SerenDB database instance", "required": [ "id", "name", "organization_id", "region", "tenant_id", "created_by", "created_at", "updated_at", "block_public_connections", "block_vpc_connections", "hipaa", "protected_branches_only", "compute_unit_min", "compute_unit_max" ], "properties": { "active_time_seconds": { "type": "number", "format": "double" }, "block_public_connections": { "type": "boolean" }, "block_vpc_connections": { "type": "boolean" }, "branch_count": { "type": "integer", "format": "int32" }, "compute_last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_unit_max": { "type": "integer", "format": "int32" }, "compute_unit_min": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid" }, "default_branch_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_compute_size_max": { "type": "number", "format": "float" }, "default_compute_size_min": { "type": "number", "format": "float" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_by": { "type": [ "string", "null" ], "format": "uuid" }, "enable_logical_replication": { "type": "boolean" }, "hipaa": { "type": "boolean" }, "history_retention_seconds": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "is_service_project": { "type": "boolean", "description": "Whether this is a service project (hidden from normal listings, contains seren_* databases)" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "postgres_version": { "type": "string" }, "protected_branches_only": { "type": "boolean" }, "region": { "type": "string" }, "storage_bytes": { "type": "integer", "format": "int64" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectConnectionUri": { "type": "object", "required": [ "uri" ], "properties": { "uri": { "type": "string" } } }, "ProjectConsumption": { "type": "object", "description": "ProjectConsumption wraps consumption data for API responses", "required": [ "project_id", "from", "to", "periods", "current_month" ], "properties": { "current_month": { "$ref": "#/components/schemas/ConsumptionSummary" }, "from": { "type": "string", "format": "date-time" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionPeriodData" } }, "project_id": { "type": "string", "format": "uuid" }, "to": { "type": "string", "format": "date-time" } } }, "ProjectCreated": { "type": "object", "description": "Response after creating a project", "required": [ "id", "name", "organization_id", "region", "tenant_id", "created_at", "block_public_connections", "block_vpc_connections", "hipaa", "protected_branches_only", "compute_unit_min", "compute_unit_max" ], "properties": { "block_public_connections": { "type": "boolean" }, "block_vpc_connections": { "type": "boolean" }, "branch_count": { "type": "integer", "format": "int32" }, "compute_unit_max": { "type": "integer", "format": "int32" }, "compute_unit_min": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "default_branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The main branch for this project" }, "enable_logical_replication": { "type": "boolean", "description": "Whether logical replication is enabled for this project" }, "hipaa": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "is_service_project": { "type": "boolean", "description": "Whether this is a service project (hidden from normal listings, contains seren_* databases)" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "postgres_version": { "type": "string" }, "protected_branches_only": { "type": "boolean" }, "region": { "type": "string" }, "storage_bytes": { "type": "integer", "format": "int64" }, "tenant_id": { "type": "string", "format": "uuid" } } }, "ProjectSize": { "type": "object", "description": "Response for project storage size", "required": [ "project_id", "size_bytes" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PublicationInfo": { "type": "object", "description": "Publication response (API output)", "required": [ "id", "project_id", "branch_id", "name", "tables", "publish_insert", "publish_update", "publish_delete", "publish_truncate", "created_at", "updated_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "publish_delete": { "type": "boolean" }, "publish_insert": { "type": "boolean" }, "publish_truncate": { "type": "boolean" }, "publish_update": { "type": "boolean" }, "tables": { "type": "array", "items": { "type": "string" }, "description": "Tables to replicate (empty means ALL TABLES)" }, "updated_at": { "type": "string", "format": "date-time" } } }, "QueryRequest": { "type": "object", "description": "JSON body for the query endpoint.", "required": [ "query" ], "properties": { "branch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Branch ID (uses default branch if omitted)" }, "database": { "type": [ "string", "null" ], "description": "Explicit target database name for user access or an attached existing database." }, "database_identifier": { "type": [ "string", "null" ], "description": "Database identifier declared by the skill." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Explicit target project ID for user access or an attached existing database." }, "query": { "type": "string", "description": "SQL query to execute" }, "read_only": { "type": [ "boolean", "null" ], "description": "Execute query in a read-only transaction. When omitted, obvious read-only queries\nrun read-only and all other statements run read-write." }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedSkillDatabaseScope", "description": "Whether the managed database is shared by the organization or isolated to the user." } ] }, "skill_slug": { "type": [ "string", "null" ], "description": "Canonical skill slug that owns a platform-managed skill database." } }, "additionalProperties": false }, "QueryResult": { "type": "object", "description": "Query result returned to the caller.", "required": [ "columns", "rows", "row_count" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "rows": { "type": "array", "items": { "type": "array", "items": {} } } } }, "RenameBranchRequest": { "type": "object", "description": "Request to rename a branch", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "ReplicationSlotInfo": { "type": "object", "description": "Replication slot response (API output)", "required": [ "id", "project_id", "branch_id", "name", "slot_type", "plugin", "status", "created_at", "updated_at" ], "properties": { "active_pid": { "type": [ "integer", "null" ], "format": "int32" }, "branch_id": { "type": "string", "format": "uuid" }, "confirmed_flush_lsn": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plugin": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "restart_lsn": { "type": [ "string", "null" ] }, "slot_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ResetBranchRequest": { "type": "object", "description": "Request to reset a branch to its parent's latest state", "required": [ "parent" ], "properties": { "parent": { "type": "boolean", "description": "Whether to reset to parent (currently the only supported option)" } } }, "ResetIpAllowListEntry": { "type": "object", "description": "Entry used when resetting the IP allow list", "required": [ "ip_address" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description for the entry" }, "ip_address": { "type": "string", "description": "IP address or CIDR range to allow" } } }, "ResetIpAllowListRequest": { "type": "object", "description": "Request to replace the entire IP allow list", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ResetIpAllowListEntry" }, "description": "Entries that should remain in the allow list after the reset.\nEmpty list means the allow list is cleared." } } }, "RestoreBranchRequest": { "type": "object", "description": "Request to restore a branch to a point in time", "required": [ "source", "preserve_under_name" ], "properties": { "preserve_under_name": { "type": "string", "description": "Name for the backup branch that will preserve the current state" }, "source": { "$ref": "#/components/schemas/RestoreSource", "description": "Source to restore from" } } }, "RestoreSource": { "oneOf": [ { "type": "object", "description": "Restore to an earlier point in the branch's own history", "required": [ "point_in_time", "type" ], "properties": { "point_in_time": { "$ref": "#/components/schemas/PointInTime" }, "type": { "type": "string", "enum": [ "^self" ] } } }, { "type": "object", "description": "Restore to parent branch (optionally at a point in time)", "required": [ "type" ], "properties": { "point_in_time": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PointInTime" } ] }, "type": { "type": "string", "enum": [ "^parent" ] } } }, { "type": "object", "description": "Restore to a specific source branch (optionally at a point in time)", "required": [ "source_branch_id", "type" ], "properties": { "point_in_time": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PointInTime" } ] }, "source_branch_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "branch" ] } } } ], "description": "Restore source for point-in-time recovery" }, "RoleCreated": { "type": "object", "description": "Response after creating a role", "required": [ "id", "name", "branch_id", "password", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "password": { "type": "string" } } }, "RoleInfo": { "type": "object", "description": "Public role info (without password hash)", "required": [ "id", "name", "branch_id", "protected", "created_at" ], "properties": { "branch_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "protected": { "type": "boolean" } } }, "RolePasswordReset": { "type": "object", "description": "Response after resetting password", "required": [ "role_id", "password" ], "properties": { "password": { "type": "string" }, "role_id": { "type": "string", "format": "uuid" } } }, "SetBranchArchivedRequest": { "type": "object", "description": "Request to set branch archived status", "required": [ "archived" ], "properties": { "archived": { "type": "boolean" } } }, "SetBranchExpirationRequest": { "type": "object", "description": "Request to set branch expiration", "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TimestampByLsn": { "type": "object", "description": "Response for timestamp by LSN query", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string" } } }, "UpdateBranchProtectionRequest": { "type": "object", "description": "Request to update branch protection", "properties": { "allowed_bypass_roles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "prevent_deletion": { "type": [ "boolean", "null" ] }, "prevent_reset": { "type": [ "boolean", "null" ] }, "require_approval_for_changes": { "type": [ "boolean", "null" ] } } }, "UpdateDatabaseRequest": { "type": "object", "description": "Request to update a database", "properties": { "owner_name": { "type": [ "string", "null" ] } } }, "UpdateEndpointRequest": { "type": "object", "description": "Request to update an endpoint", "properties": { "autoscaling_max": { "type": [ "integer", "null" ], "format": "int32" }, "autoscaling_min": { "type": [ "integer", "null" ], "format": "int32" }, "compute_unit": { "type": [ "string", "null" ] }, "pooler_enabled": { "type": [ "boolean", "null" ] }, "pooler_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PoolerMode" } ] }, "suspend_timeout_seconds": { "type": [ "integer", "null" ], "format": "int32" } } }, "UpdateLogicalReplicationRequest": { "type": "object", "description": "Request to update logical replication settings", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "UpdateProjectRequest": { "type": "object", "description": "Request to update a project", "properties": { "block_public_connections": { "type": [ "boolean", "null" ] }, "block_vpc_connections": { "type": [ "boolean", "null" ] }, "compute_unit_max": { "type": [ "integer", "null" ], "format": "int32" }, "compute_unit_min": { "type": [ "integer", "null" ], "format": "int32" }, "enable_logical_replication": { "type": [ "boolean", "null" ], "description": "Enable logical replication for this project. Sets wal_level=logical for all compute endpoints.\nOnce enabled, this cannot be disabled. Enabling will suspend all active endpoints." }, "hipaa": { "type": [ "boolean", "null" ] }, "history_retention_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "History retention period in seconds for point-in-time recovery (PITR).\nDetermines how far back you can create branches from historical data.\nDefault is 21600 (6 hours). Minimum is 3600 (1 hour). Maximum is 2592000 (30 days)." }, "name": { "type": [ "string", "null" ] }, "protected_branches_only": { "type": [ "boolean", "null" ] } } }, "UpdatePublicationRequest": { "type": "object", "description": "Request to update a publication", "properties": { "publish_delete": { "type": [ "boolean", "null" ] }, "publish_insert": { "type": [ "boolean", "null" ] }, "publish_truncate": { "type": [ "boolean", "null" ] }, "publish_update": { "type": [ "boolean", "null" ] }, "tables": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "AgentAssetFile": { "type": "object", "description": "Non-prompt file that belongs to an agent bundle.", "required": [ "path", "content_base64" ], "properties": { "content_base64": { "type": "string", "description": "Base64-encoded file body." }, "content_type": { "type": [ "string", "null" ], "description": "Optional MIME type supplied by the caller." }, "path": { "type": "string", "description": "Agent-bundle relative path." }, "purpose": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentAssetPurpose", "description": "Optional caller-supplied purpose for UI grouping and runtime materialization." } ] }, "sha256": { "type": [ "string", "null" ], "description": "Optional content digest for provenance. When present, the server verifies it." } }, "additionalProperties": false }, "AgentAssetPurpose": { "type": "string", "enum": [ "reference", "script", "schema", "resource", "eval" ] }, "AgentBundle": { "type": "object", "description": "Authored agent bundle used by LLM workloads.", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAssetFile" }, "description": "Additional files available to the agent runtime." }, "instructions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstructionFile" }, "description": "Prompt-bearing instruction files rendered server-side into the runtime\nsystem prompt." } }, "additionalProperties": false }, "AgentInstructionFile": { "type": "object", "description": "One authored instruction file.\n\nSupports inline instruction bodies as well as packaged workload metadata.", "required": [ "kind", "content" ], "properties": { "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional tool allowlist carried by skill metadata." }, "content": { "type": "string", "description": "File body. Packaged workloads should provide the materialized instruction text." }, "kind": { "$ref": "#/components/schemas/AgentInstructionKind" }, "path": { "type": [ "string", "null" ], "description": "Original or packaged path, when known." }, "sha256": { "type": [ "string", "null" ], "description": "Optional content digest for packaged workload provenance." }, "skill_name": { "type": [ "string", "null" ], "description": "Skill directory name, when the instruction came from a packaged skill." } }, "additionalProperties": false }, "AgentInstructionKind": { "type": "string", "description": "Typed instruction-file kind for managed LLM workloads.", "enum": [ "identity", "soul", "skill", "agents", "user", "tools", "memory", "heartbeat", "eval" ] }, "ApprovalDecisionState": { "type": "string", "description": "Lifecycle state of a single inbox entry.\n\nThe state machine is `pending -> approved | denied | expired`. Decisions are\nterminal; an entry can never transition from a terminal state back to\npending. `expired` is a passive transition driven by `expires_at`.", "enum": [ "pending", "approved", "denied", "expired" ] }, "ApprovalInboxBlockedEgress": { "type": "object", "description": "Blocked egress approval surfaced when `AgentNetworkPolicy.blocked_request_inbox`\nholds a request for operator review.\n\n`request_id` is the durable identifier the runtime emitted with the\n`BlockedEgress` event so a decision can be threaded back to the originating\nrequest.", "required": [ "request_id", "host", "port" ], "properties": { "details": { "description": "Free-form additional context captured at block time (rule id, matched\nhostname pattern, request size, etc.)." }, "host": { "type": "string" }, "method": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "reason": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "format": "uuid" } } }, "ApprovalInboxDecisionRequest": { "type": "object", "description": "Body for `POST /inbox/approvals/{entry_id}/decide`.", "required": [ "decision" ], "properties": { "comment": { "type": [ "string", "null" ], "description": "Optional operator note recorded in the audit chain alongside the\ndecision." }, "decision": { "$ref": "#/components/schemas/ApprovalInboxDecisionVerb" } } }, "ApprovalInboxDecisionResponse": { "type": "object", "description": "Response returned after recording a decision.", "required": [ "entry_id", "decision_state" ], "properties": { "decision_state": { "$ref": "#/components/schemas/ApprovalDecisionState" }, "entry_id": { "type": "string" } } }, "ApprovalInboxDecisionVerb": { "type": "string", "description": "Decision verb accepted by the inbox decision endpoint.\n\nDistinct from `CloudRunApprovalDecisionValue` (which uses `approve`/`reject`)\nbecause the inbox is the operator surface and `deny` reads better than\n`reject` for non-tool kinds like blocked egress. The mapping into the\nexisting tool-call resume path is internal.", "enum": [ "approve", "deny" ] }, "ApprovalInboxEntry": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApprovalInboxToolCall" }, { "type": "object", "required": [ "entry_id", "deployment_id", "run_id", "created_at", "decision_state" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "decision_state": { "$ref": "#/components/schemas/ApprovalDecisionState" }, "deployment_id": { "type": "string", "format": "uuid" }, "entry_id": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "tool_call" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApprovalInboxBlockedEgress" }, { "type": "object", "required": [ "entry_id", "deployment_id", "created_at", "decision_state" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "decision_state": { "$ref": "#/components/schemas/ApprovalDecisionState" }, "deployment_id": { "type": "string", "format": "uuid" }, "entry_id": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Egress can fire outside of a run (background reconciliation,\nscheduled jobs that haven't claimed a run row yet)." } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "blocked_egress" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApprovalInboxOther" }, { "type": "object", "required": [ "entry_id", "deployment_id", "created_at", "decision_state" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "decision_state": { "$ref": "#/components/schemas/ApprovalDecisionState" }, "deployment_id": { "type": "string", "format": "uuid" }, "entry_id": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "other" ] } } } ] } ], "description": "One entry in the unified approval inbox.\n\n`entry_id` is inbox-scoped and stable for the lifetime of the entry; callers\npass it back to the decision endpoint. Tool-call entries encode\n`(run_id, tool_call_id)` so the inbox does not need a separate persistence\nrow. Blocked-egress entries use a real UUID backed by storage." }, "ApprovalInboxListResponse": { "type": "object", "description": "Listing response for the approval inbox.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalInboxEntry" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; absent when no further entries exist." } } }, "ApprovalInboxOther": { "type": "object", "description": "Catch-all variant so future approval kinds can land in the inbox without a\nmodel rev. Callers that do not yet know the subkind should still be able\nto render the row.\n\n`subkind` (rather than `kind`) avoids clashing with the enum-level\n`kind` discriminator tag.", "required": [ "subkind" ], "properties": { "payload": {}, "reason": { "type": [ "string", "null" ] }, "subkind": { "type": "string" } } }, "ApprovalInboxToolCall": { "type": "object", "description": "Tool-call approval surfaced from an `awaiting_approval` run.\n\n`tool_call_id` is the orchestrator-supplied id that round-trips into the\n`approval_decisions` array on resume. `tool_ref` is the human-meaningful\ntool name (e.g. `seren_publisher_request`).", "required": [ "tool_call_id", "tool_ref" ], "properties": { "function_call_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "request_payload_summary": { "description": "Arguments preview. Callers may truncate large payloads upstream; this\nfield is opaque JSON so the renderer decides how to display it." }, "tool_call_id": { "type": "string" }, "tool_ref": { "type": "string" } } }, "AttachManagedStorageRequest": { "type": "object", "required": [ "bucket_slug", "permission" ], "properties": { "bucket_slug": { "type": "string" }, "permission": { "$ref": "#/components/schemas/ManagedStoragePermission" }, "workspace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedStorageWorkspaceRequest" } ] } }, "additionalProperties": false }, "AuditEntry": { "type": "object", "description": "A single audit trail entry.", "required": [ "id", "organization_id", "sequence_number", "action", "actor", "details", "entry_hash", "prev_hash", "created_at" ], "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "details": {}, "entry_hash": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invocation_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "publisher_id": { "type": [ "string", "null" ], "format": "uuid" }, "sequence_number": { "type": "integer", "format": "int64" } } }, "BindConnectorSecretsRequest": { "type": "object", "required": [ "secret_refs" ], "properties": { "secret_refs": { "type": "object", "description": "Connector credential field names mapped to opaque Seren Secrets references.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "BoundConnectorSecrets": { "type": "object", "required": [ "deployment_id", "connector_ref", "secret_fields", "secret_refs" ], "properties": { "connector_ref": { "type": "string" }, "deployment_id": { "type": "string", "format": "uuid" }, "secret_fields": { "type": "array", "items": { "type": "string" } }, "secret_refs": { "type": "array", "items": { "type": "string" }, "description": "Complete opaque reference set the client must cover with the next\nuser-signed secret resolution delegation." } } }, "ChannelBindingRef": { "type": "object", "description": "Current Core-owned identity of an organization channel binding.\n\nThe binding is provider-neutral. Core resolves it to the configured\nconnector account and external conversation and rechecks the generation\nbefore minting a target-scoped identity. Downstream services still recheck\ntheir own resource grants.", "required": [ "binding_id", "generation" ], "properties": { "binding_id": { "type": "string", "format": "uuid" }, "generation": { "type": "integer", "format": "int64" } } }, "CloudConversationListResponse": { "type": "object", "required": [ "conversations", "has_more" ], "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/CloudConversationResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "CloudConversationMessageResponse": { "type": "object", "required": [ "message_id", "conversation_id", "deployment_id", "organization_id", "user_id", "role", "source", "collaboration_target", "content", "events", "created_at", "updated_at" ], "properties": { "client_message_id": { "type": [ "string", "null" ] }, "collaboration_target": { "$ref": "#/components/schemas/CloudRunCollaborationTarget" }, "content": { "type": "string" }, "conversation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunOutputEventEnvelope" } }, "message_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunEvent" } ] }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_summary": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudConversationMessageRunSummary" } ] }, "source": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudConversationMessageRunSummary": { "type": "object", "required": [ "run_id", "status", "started_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudConversationMessagesResponse": { "type": "object", "required": [ "messages", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CloudConversationMessageResponse" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CloudConversationResponse": { "type": "object", "required": [ "id", "conversation_id", "deployment_id", "organization_id", "user_id", "message_count", "last_activity_at", "created_at", "updated_at" ], "properties": { "conversation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_activity_at": { "type": "string", "format": "date-time" }, "last_source": { "type": [ "string", "null" ] }, "message_count": { "type": "integer", "format": "int64" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudDeploymentActionStatusResponse": { "type": "object", "description": "Generic status payload used by cloud deployment lifecycle endpoints.", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "CloudDeploymentAgentSchedule": { "type": "object", "required": [ "id", "deployment_id", "schedule_key", "schedule_kind", "next_run_at", "status", "attempts", "max_attempts", "created_at", "updated_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_event_id": { "type": [ "string", "null" ], "format": "uuid" }, "max_attempts": { "type": "integer", "format": "int32" }, "next_run_at": { "type": "string", "format": "date-time" }, "schedule_key": { "type": "string" }, "schedule_kind": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudDeploymentAgentScheduleRequest": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "cron": { "type": [ "string", "null" ] }, "delay_seconds": { "type": [ "integer", "null" ], "format": "int64" }, "max_attempts": { "type": [ "integer", "null" ], "format": "int32" }, "message": { "type": [ "string", "null" ] }, "payload": {}, "run_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule_key": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] } } }, "CloudDeploymentAlertEvent": { "type": "string", "description": "Run-status event that can trigger a deployment alert webhook.", "enum": [ "awaiting_approval", "failed", "blocked", "timeout", "completed", "cancelled" ] }, "CloudDeploymentAlertPolicy": { "type": "object", "description": "Deployment-level operator alert policy.", "required": [ "webhook_secret_key" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/CloudDeploymentAlertEvent" }, "description": "Run events that should trigger the webhook." }, "webhook_secret_key": { "type": "string", "description": "Secret key whose value is the destination webhook URL." } } }, "CloudDeploymentBundle": { "type": "object", "description": "Deployment bundle metadata without raw bundle content.", "required": [ "id", "organization_id", "user_id", "sha256", "size_bytes", "source_kind", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" }, "updated_at": { "type": "string", "format": "date-time" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudDeploymentBundleDetail": { "type": "object", "description": "Deployment bundle metadata plus current deployment references.", "required": [ "bundle", "deployment_ids" ], "properties": { "bundle": { "$ref": "#/components/schemas/CloudDeploymentBundle" }, "deployment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "CloudDeploymentBundleDownloadResponse": { "type": "object", "description": "Short-lived download instructions for a deployment's runtime bundle.", "required": [ "deployment_id", "deployment_bundle_id", "sha256", "size_bytes", "source_kind", "download_url", "download_expires_at" ], "properties": { "deployment_bundle_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" } } }, "CloudDeploymentBundleSourceKind": { "type": "string", "description": "Deployment bundle artifact format.\n\nThis is intentionally a closed server-supported set. Add formats by\nmigration when Seren Cloud can validate and execute them.", "enum": [ "tar_gz" ] }, "CloudDeploymentComputeBackend": { "type": "string", "description": "Cloud deployment compute backend target.", "enum": [ "aws_container", "cloudflare_worker", "daytona" ] }, "CloudDeploymentEnvironment": { "type": "object", "description": "Reusable execution environment profile for cloud deployments.", "required": [ "id", "organization_id", "user_id", "name", "docker_image", "setup_commands", "is_default", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "docker_image": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "setup_commands": {}, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudDeploymentEvalDrift": { "type": "object", "description": "Snapshot of the current eval-set verdict alongside the baseline captured at\nthe last successful apply. Reports the delta on `passed` so operators can\nsee regressions explicitly. `current_passed`/`current_failed` are `None`\nwhen no eval run has completed against the gated set yet; in that case the\nstatus carries an explanatory `reason`.", "required": [ "deployment_id", "eval_gate_set_id", "message", "checked_at" ], "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGateDriftBaseline" } ] }, "checked_at": { "type": "string", "format": "date-time" }, "current_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_failed": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "current_passed": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "current_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_run_status": { "type": [ "string", "null" ] }, "current_verdict_status": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_set_id": { "type": "string", "format": "uuid" }, "failed_delta": { "type": [ "integer", "null" ], "format": "int32", "description": "`current_failed - baseline_failed` when both sides are present." }, "message": { "type": "string", "description": "Operator-safe one-line summary of the drift state. Always present." }, "passed_delta": { "type": [ "integer", "null" ], "format": "int32", "description": "`current_passed - baseline_passed` when both sides are present." } } }, "CloudDeploymentEvalGateStatus": { "type": "object", "description": "Computed evaluation gate status for a deployment.", "required": [ "state", "blocking", "message", "eval_gate_set_id", "eval_gate_max_age_seconds", "checked_at" ], "properties": { "blocking": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "eval_gate_max_age_seconds": { "type": "integer", "format": "int32" }, "eval_gate_set_id": { "type": "string", "format": "uuid" }, "fresh_until": { "type": [ "string", "null" ], "format": "date-time" }, "latest_eval_run_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_eval_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "latest_eval_run_status": { "type": [ "string", "null" ] }, "latest_verdict_passed": { "type": [ "boolean", "null" ] }, "latest_verdict_status": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "state": { "type": "string" } } }, "CloudDeploymentMode": { "type": "string", "description": "Cloud deployment execution mode.", "enum": [ "always_on", "cron", "job" ] }, "CloudDeploymentNetworkPolicy": { "type": "object", "description": "Deployment-level outbound network restrictions for sandboxed execution backends.", "properties": { "allow_list": { "type": "array", "items": { "type": "string" }, "description": "Explicit IPv4 CIDR ranges allowed for outbound access." }, "block_all": { "type": "boolean", "description": "When true, block all outbound network access from the deployment runtime." } } }, "CloudDeploymentRunArtifact": { "type": "object", "description": "Artifact emitted by a cloud run (for example PR links, plans, screenshots).", "required": [ "id", "run_event_id", "deployment_id", "organization_id", "user_id", "artifact_type", "payload", "created_at", "updated_at" ], "properties": { "artifact_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "payload": {}, "run_event_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudDeploymentRunEvent": { "type": "object", "description": "A single execution run event for a cloud deployment.", "required": [ "id", "deployment_id", "organization_id", "user_id", "execution_id", "compute_backend", "source", "status", "execution_time_ms", "billed_duration_ms", "requested_cpu_millicores", "requested_memory_mib", "compute_cost_atomic", "compute_cost_usd", "inference_input_tokens", "inference_output_tokens", "inference_cost_atomic", "inference_cost_usd", "started_at", "invocation_payload", "metadata", "created_at", "updated_at" ], "properties": { "billed_duration_ms": { "type": "integer", "format": "int32" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "compute_cost_atomic": { "type": "integer", "format": "int64" }, "compute_cost_usd": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string" }, "execution_time_ms": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "inference_cost_atomic": { "type": "integer", "format": "int64" }, "inference_cost_usd": { "type": "string" }, "inference_input_tokens": { "type": "integer", "format": "int64" }, "inference_output_tokens": { "type": "integer", "format": "int64" }, "invocation_payload": { "description": "Canonical JSON payload submitted to trigger the run." }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": { "type": [ "string", "null" ], "description": "Raw stdout/stderr output. Universal fallback for all backend types." }, "output_events": { "description": "Structured event trace for agentic executions (thinking, tool calls, text).\nNull for non-agentic scripts that produce plain stdout/stderr." }, "requested_cpu_millicores": { "type": "integer", "format": "int32" }, "requested_memory_mib": { "type": "integer", "format": "int32" }, "run_name": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "session_url": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "CloudDeploymentRunInvocationResponse": { "type": "object", "description": "Response envelope for triggering a cloud deployment run.\n\nThis schema intentionally covers both synchronous and asynchronous responses\nacross compute backends (`always_on`, `cron`, Cloudflare, Daytona).", "required": [ "status" ], "properties": { "compute_cost_atomic": { "type": [ "integer", "null" ], "format": "int64", "description": "Atomic compute cost units when emitted by the backend." }, "execution_id": { "type": [ "string", "null" ], "description": "Backend execution ID for correlating orchestrator/job-level status." }, "execution_time_ms": { "type": [ "integer", "null" ], "format": "int32", "description": "Execution duration in milliseconds when available." }, "exit_code": { "type": [ "integer", "null" ], "format": "int32", "description": "Process exit code for runtimes that expose it (for example Daytona)." }, "job_name": { "type": [ "string", "null" ], "description": "K8s Job name for queued cron executions." }, "result": { "description": "Backend-specific result payload." }, "run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Persisted run event ID when the invocation is tracked in the run history table." }, "sandbox_id": { "type": [ "string", "null" ], "description": "Daytona sandbox ID when applicable." }, "script_name": { "type": [ "string", "null" ], "description": "Cloudflare Worker script name when applicable." }, "status": { "type": "string", "description": "Lifecycle status reported by the backend (`queued`, `running`, `completed`, etc.)." } } }, "CloudDeploymentRunRequest": { "type": "object", "description": "Request body for triggering a cloud deployment run.\n\nAdditional JSON fields are allowed and forwarded to the runtime.", "properties": { "approval_decisions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudRunApprovalDecision" }, "description": "Optional approval decisions for runtimes that support inline resume." }, "async": { "type": [ "boolean", "null" ], "description": "Whether to request async execution for always-on orchestrators." }, "collaboration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunCollaborationSelection", "description": "Explicit audience and governed knowledge selection for this invocation.\nOmit this field to preserve individual employee behavior." } ] }, "message": { "type": [ "string", "null" ], "description": "Optional message for orchestrated runtimes." }, "resume_checkpoint_id": { "type": [ "string", "null" ], "description": "Optional checkpoint identifier for runtimes that support inline resume." }, "run_id": { "type": [ "string", "null" ], "description": "Optional client correlation identifier used by some orchestrators.\nDeployment-scoped callers must omit it because Seren Cloud assigns\nchild run identifiers." } } }, "CloudDeploymentRunResumeRequest": { "type": "object", "properties": { "approval_decisions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudRunApprovalDecision" }, "description": "Complete decision set for the checkpoint's current pending approvals." }, "include_raw_tool_outputs": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] }, "resume_checkpoint_id": { "type": [ "string", "null" ], "description": "Checkpoint returned with the current pending approvals. Approval decisions\nmust name the exact checkpoint that owns them." } } }, "CloudDeploymentRuntimeKind": { "type": "string", "description": "Cloud deployment runtime kind (language/runtime format).", "enum": [ "python", "javascript", "typescript", "rust", "rust_wasm" ] }, "CloudDeploymentStatus": { "type": "string", "description": "Cloud deployment lifecycle status.", "enum": [ "pending", "building", "running", "stopped", "failed" ] }, "CloudDeploymentSummary": { "type": "object", "description": "Summary view for listing deployments (excludes large fields like code_bundle).", "required": [ "id", "organization_id", "user_id", "name", "skill_slug", "compute_backend", "runtime_kind", "mode", "status", "code_bundle_hash", "orchestration_mode", "requirements", "visibility", "created_at", "updated_at" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current managed-agent revision, when this is a managed seren-agent deployment." }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy" } ] }, "code_bundle_hash": { "type": "string" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "dashboard_config": {}, "deployment_bundle_id": { "type": [ "string", "null" ], "format": "uuid" }, "endpoint_url": { "type": [ "string", "null" ] }, "environment_id": { "type": [ "string", "null" ], "format": "uuid" }, "error_message": { "type": [ "string", "null" ] }, "eval_gate_max_age_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "eval_gate_set_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus" } ] }, "id": { "type": "string", "format": "uuid" }, "managed_agent": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSummary" } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy" } ] }, "orchestration_mode": { "$ref": "#/components/schemas/OrchestrationMode" }, "organization_id": { "type": "string", "format": "uuid" }, "publisher_only": { "type": "boolean" }, "requirements": {}, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "skill_slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "description": "Visibility mode: \"open\" (default) or \"opaque\" (redacts selected details from non-owners)." } } }, "CloudEvalCase": { "type": "object", "description": "Reusable eval baseline captured from a run or created manually later.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "source_kind", "name", "invocation_payload", "expected_eval_capture", "expected_replay_events", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output": { "type": [ "string", "null" ] }, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "id": { "type": "string", "format": "uuid" }, "invocation_payload": {}, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "source_kind": { "type": "string" }, "source_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudEvalCaseResult": { "type": "object", "description": "Per-case result row captured when running an eval set.", "required": [ "id", "eval_run_id", "eval_set_id", "eval_case_id", "organization_id", "status", "expected_eval_capture", "actual_eval_capture", "expected_replay_events", "actual_replay_events", "comparison", "metadata", "created_at", "updated_at" ], "properties": { "actual_eval_capture": {}, "actual_output_sha256": { "type": [ "string", "null" ] }, "actual_replay_events": {}, "actual_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "actual_status": { "type": [ "string", "null" ] }, "comparison": {}, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_case_id": { "type": "string", "format": "uuid" }, "eval_run_id": { "type": "string", "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "expected_status": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudEvalCriteria": { "type": "object", "description": "Durable pass/fail criteria for a seren-cloud eval set.", "properties": { "max_errored_cases": { "type": "integer", "format": "int32" }, "max_failed_cases": { "type": "integer", "format": "int32" }, "max_missing_actual_eval_capture_cases": { "type": "integer", "format": "int32" }, "max_missing_actual_replay_cases": { "type": "integer", "format": "int32" }, "max_output_mismatches": { "type": "integer", "format": "int32" }, "max_status_mismatches": { "type": "integer", "format": "int32" }, "max_trajectory_mismatches": { "type": "integer", "format": "int32" }, "min_completion_rate": { "type": "number", "format": "double" }, "min_field_match_rate": { "type": "number", "format": "double" }, "min_score": { "type": "number", "format": "double" } } }, "CloudEvalRun": { "type": "object", "description": "Durable execution record for running an eval set against a deployment.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "status", "total_cases", "completed_cases", "passed_cases", "failed_cases", "errored_cases", "summary", "verdict", "metadata", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_cases": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "errored_cases": { "type": "integer", "format": "int32" }, "eval_set_id": { "type": "string", "format": "uuid" }, "failed_cases": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "passed_cases": { "type": "integer", "format": "int32" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/CloudEvalRunSummary" }, "total_cases": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" }, "verdict": { "$ref": "#/components/schemas/CloudEvalRunVerdict" } } }, "CloudEvalRunFailureExample": { "type": "object", "description": "Representative failures attached to an eval run summary.", "required": [ "eval_case_id", "status" ], "properties": { "actual_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "case_name": { "type": [ "string", "null" ] }, "eval_case_id": { "type": "string", "format": "uuid" }, "notes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } }, "CloudEvalRunSummary": { "type": "object", "description": "Roll-up summary for an eval run.", "required": [ "score", "pass_rate", "completion_rate", "compared_cases", "output_checked_cases", "output_mismatches", "status_checked_cases", "status_mismatches", "trajectory_checked_cases", "trajectory_mismatches", "missing_actual_eval_capture_cases", "missing_actual_replay_cases", "field_comparisons", "field_mismatches", "field_match_rate" ], "properties": { "compared_cases": { "type": "integer", "format": "int32" }, "completion_rate": { "type": "number", "format": "double" }, "failure_examples": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalRunFailureExample" } }, "field_comparisons": { "type": "integer", "format": "int32" }, "field_match_rate": { "type": "number", "format": "double" }, "field_mismatches": { "type": "integer", "format": "int32" }, "first_errored_case_id": { "type": [ "string", "null" ], "format": "uuid" }, "first_failed_case_id": { "type": [ "string", "null" ], "format": "uuid" }, "missing_actual_eval_capture_cases": { "type": "integer", "format": "int32" }, "missing_actual_replay_cases": { "type": "integer", "format": "int32" }, "output_checked_cases": { "type": "integer", "format": "int32" }, "output_mismatches": { "type": "integer", "format": "int32" }, "pass_rate": { "type": "number", "format": "double" }, "score": { "type": "number", "format": "double" }, "status_checked_cases": { "type": "integer", "format": "int32" }, "status_mismatches": { "type": "integer", "format": "int32" }, "trajectory_checked_cases": { "type": "integer", "format": "int32" }, "trajectory_mismatches": { "type": "integer", "format": "int32" } } }, "CloudEvalRunVerdict": { "type": "object", "description": "Durable pass/fail verdict derived from an eval run and its criteria.", "required": [ "status", "criteria" ], "properties": { "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "evaluated_at": { "type": [ "string", "null" ], "format": "date-time" }, "failing_checks": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalRunVerdictCheck" } }, "status": { "type": "string" } } }, "CloudEvalRunVerdictCheck": { "type": "object", "description": "Individual threshold failure that contributed to an eval verdict.", "required": [ "key", "label", "operator", "target", "actual", "message" ], "properties": { "actual": {}, "key": { "type": "string" }, "label": { "type": "string" }, "message": { "type": "string" }, "operator": { "type": "string" }, "target": {} } }, "CloudEvalSet": { "type": "object", "description": "Durable grouping for reusable seren-cloud eval cases.", "required": [ "id", "organization_id", "created_by_user_id", "name", "criteria", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudEvalSetSchedule" } ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudEvalSetSchedule": { "type": "object", "description": "Scheduler state for automatically executing a seren-cloud eval set.", "required": [ "schedule_cron", "schedule_timezone", "schedule_next_run_at" ], "properties": { "schedule_cron": { "type": "string" }, "schedule_last_attempted_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule_last_eval_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "schedule_last_message": { "type": [ "string", "null" ] }, "schedule_last_status": { "type": [ "string", "null" ] }, "schedule_next_run_at": { "type": "string", "format": "date-time" }, "schedule_timezone": { "type": "string" } } }, "CloudEvalSetScheduleRequest": { "type": "object", "description": "Request body for enabling or updating scheduled eval execution.", "required": [ "schedule_cron", "schedule_timezone" ], "properties": { "schedule_cron": { "type": "string" }, "schedule_timezone": { "type": "string" } } }, "CloudInteractiveSessionDetailResponse": { "type": "object", "required": [ "session", "messages", "message_pagination" ], "properties": { "message_pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CloudInteractiveSessionHistoryMessage" } }, "session": { "$ref": "#/components/schemas/CloudInteractiveSessionResponse" } } }, "CloudInteractiveSessionHistoryMessage": { "type": "object", "required": [ "message_id", "session_id", "deployment_id", "client_message_id", "content", "created_at", "updated_at" ], "properties": { "client_message_id": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunEvent" } ] }, "session_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudInteractiveSessionMessageRequest": { "type": "object", "required": [ "content", "client_message_id", "idempotency_key" ], "properties": { "client_message_id": { "type": "string" }, "content": { "type": "string" }, "idempotency_key": { "type": "string" }, "metadata": {} } }, "CloudInteractiveSessionMessageResponse": { "type": "object", "required": [ "message_id", "session_id", "client_message_id", "duplicate", "stream_url" ], "properties": { "client_message_id": { "type": "string" }, "duplicate": { "type": "boolean" }, "message_id": { "type": "string", "format": "uuid" }, "run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunInvocationResponse" } ] }, "session_id": { "type": "string", "format": "uuid" }, "stream_url": { "type": "string" } } }, "CloudInteractiveSessionOpenRequest": { "type": "object", "properties": { "actor_label_hint": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] } } }, "CloudInteractiveSessionOpenResponse": { "type": "object", "required": [ "session_id", "conversation_id", "status", "stream_url", "ws_url", "ws_ticket", "expires_at", "idle_expires_at" ], "properties": { "conversation_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "idle_expires_at": { "type": "string", "format": "date-time" }, "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "stream_url": { "type": "string" }, "ws_ticket": { "type": "string" }, "ws_url": { "type": "string" } } }, "CloudInteractiveSessionResponse": { "type": "object", "required": [ "session_id", "conversation_id", "deployment_id", "organization_id", "user_id", "status", "stream_url", "ws_url", "idle_expires_at", "created_at", "updated_at" ], "properties": { "close_reason": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "conversation_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "idle_expires_at": { "type": "string", "format": "date-time" }, "interactive_session_id": { "type": [ "string", "null" ], "format": "uuid" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string" }, "status": { "type": "string" }, "stream_url": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" }, "ws_url": { "type": "string" } } }, "CloudPendingApprovalRun": { "type": "object", "description": "Awaiting-approval run entry returned by the approval inbox endpoints.", "required": [ "run_id", "deployment_id", "execution_id", "compute_backend", "source", "status", "started_at", "updated_at" ], "properties": { "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "deployment_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string" }, "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunPendingApproval" } }, "run_id": { "type": "string", "format": "uuid" }, "run_name": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudRunApprovalDecision": { "type": "object", "description": "One decision submitted for a pending approval.", "required": [ "id", "decision" ], "properties": { "decision": { "$ref": "#/components/schemas/CloudRunApprovalDecisionValue" }, "id": { "type": "string" } } }, "CloudRunApprovalDecisionKind": { "type": "string", "description": "Decision recorded by an approval event.", "enum": [ "approve", "reject", "escalate" ] }, "CloudRunApprovalDecisionValue": { "type": "string", "enum": [ "approve", "reject" ] }, "CloudRunCollaborationSelection": { "type": "object", "required": [ "invocation_origin", "knowledge_capture_target", "output_audience" ], "properties": { "invocation_origin": { "$ref": "#/components/schemas/InvocationOrigin", "description": "Requested source for this invocation. Core accepts only origins whose\nauthority boundary is implemented for the selected deployment." }, "knowledge_capture_target": { "$ref": "#/components/schemas/KnowledgeCaptureTarget", "description": "Explicit destination for captured interaction data." }, "knowledge_selection": { "$ref": "#/components/schemas/KnowledgeSelection", "description": "Provider-owned organization knowledge requested for this invocation." }, "output_audience": { "$ref": "#/components/schemas/OutputAudience", "description": "Audience permitted to receive output or protected side effects." }, "task_label": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskLabel", "description": "Optional organization-defined task label constrained by the assignment." } ] } }, "additionalProperties": false }, "CloudRunCollaborationTarget": { "type": "string", "enum": [ "individual", "organization" ] }, "CloudRunDoneStatus": { "type": "string", "description": "Terminal status reported by a `Done` event.", "enum": [ "ok", "error", "cancelled" ] }, "CloudRunErrorCause": { "type": "string", "description": "Typed cause of a terminal `error` event. Operator-safe descriptors only;\nthe offending content must not appear in the cause label.", "enum": [ "agent", "model", "tool", "session", "artifact", "memory", "config", "io", "serialization", "timeout", "task", "guardrail", "approval", "unknown" ] }, "CloudRunErrorCode": { "type": "string", "description": "Stable error code for expected run failures. This lets clients render\nconfiguration and tool failures without parsing provider messages.", "enum": [ "tool_unavailable", "tool_not_configured", "tool_missing_credential", "tool_permission_denied", "tool_rate_limited", "tool_provider_failed", "model_tool_response_rejected", "model_tool_calls_unsupported", "model_provider_rejected", "approval_required", "guardrail_blocked", "runtime_error", "timeout", "unknown" ] }, "CloudRunEvalsResponse": { "type": "object", "description": "Eval records linked to a run, either as the promoted source or as an actual replay target.", "required": [ "run_id" ], "properties": { "actual_eval_case_results": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalCaseResult" } }, "run_id": { "type": "string", "format": "uuid" }, "source_eval_cases": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalCase" } } } }, "CloudRunGuardrailAction": { "type": "string", "description": "How the run responded to a failing guardrail.", "enum": [ "retry", "block", "fix", "human" ] }, "CloudRunGuardrailTarget": { "type": "string", "description": "The target of a guardrail validator.", "enum": [ "input", "output", "tool_input", "tool_output" ] }, "CloudRunLiveState": { "type": "object", "description": "Operator-safe live status projection for a run.", "required": [ "run_id", "deployment_id", "status", "phase", "pending_approval_count", "latest_sequence", "started_at", "updated_at", "terminal" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "current_step": { "type": [ "string", "null" ] }, "current_tool": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "latest_event_kind": { "type": [ "string", "null" ] }, "latest_sequence": { "type": "integer", "format": "int64" }, "pending_approval_count": { "type": "integer", "format": "int64" }, "phase": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "terminal": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CloudRunOutputEvent": { "oneOf": [ { "type": "object", "description": "Plain text output from the agent.", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "description": "LLM thinking/reasoning block (collapsible in UI).", "required": [ "text", "type" ], "properties": { "duration_ms": { "type": [ "integer", "null" ], "format": "int32" }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "thinking" ] } } }, { "type": "object", "description": "Tool invocation by the agent.", "required": [ "id", "name", "type" ], "properties": { "arguments": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "tool_call" ] } } }, { "type": "object", "description": "Result returned from a tool invocation.", "required": [ "id", "content", "is_error", "type" ], "properties": { "code": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunErrorCode" } ] }, "content": { "type": "string" }, "id": { "type": "string" }, "is_error": { "type": "boolean" }, "retryable": { "type": "boolean" }, "type": { "type": "string", "enum": [ "tool_result" ] } } }, { "type": "object", "description": "Audit trail entry for a tool invocation that should be logged but not blocked.\n`reason` carries an operator-visible descriptor. Optional fields surface\nruntime context (tool_ref kind, action, lease ref, status, byte counts,\nlatency) for operator inspection without changing the legacy wire shape.", "required": [ "id", "tool", "reason", "type" ], "properties": { "action": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "input_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "latency_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lease_ref": { "type": [ "string", "null" ] }, "output_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "reason": { "type": "string" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunToolAuditStatus" } ] }, "tool": { "type": "string" }, "tool_ref_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunToolRefKind" } ] }, "type": { "type": "string", "enum": [ "tool_audit" ] } } }, { "type": "object", "description": "Workflow/checkpoint marker for resumable runs.", "required": [ "state", "type" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "contract_version": { "type": "integer", "format": "int32", "minimum": 0 }, "details": {}, "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunPendingApproval" } }, "state": { "type": "string" }, "type": { "type": "string", "enum": [ "workflow" ] } } }, { "type": "object", "description": "Run is paused waiting on a user or operator approval decision.", "required": [ "type" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "tool_call_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "approval_wait" ] } } }, { "type": "object", "description": "An approval decision was recorded for a previously paused checkpoint.", "required": [ "decision", "type" ], "properties": { "actor": { "type": [ "string", "null" ] }, "checkpoint_id": { "type": [ "string", "null" ] }, "decision": { "$ref": "#/components/schemas/CloudRunApprovalDecisionKind" }, "reason": { "type": [ "string", "null" ] }, "tool_call_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "approval_decision" ] } } }, { "type": "object", "description": "A guardrail check passed for the named target.", "required": [ "name", "target", "type" ], "properties": { "name": { "type": "string" }, "target": { "$ref": "#/components/schemas/CloudRunGuardrailTarget" }, "type": { "type": "string", "enum": [ "guardrail_pass" ] } } }, { "type": "object", "description": "A guardrail check failed; the action taken indicates how the run responded.", "required": [ "name", "target", "message", "action", "type" ], "properties": { "action": { "$ref": "#/components/schemas/CloudRunGuardrailAction" }, "attempt": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "message": { "type": "string" }, "name": { "type": "string" }, "target": { "$ref": "#/components/schemas/CloudRunGuardrailTarget" }, "type": { "type": "string", "enum": [ "guardrail_fail" ] } } }, { "type": "object", "description": "Control was handed off from one agent to another (multi-agent runs).", "required": [ "to_agent", "type" ], "properties": { "from_agent": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "to_agent": { "type": "string" }, "type": { "type": "string", "enum": [ "handoff" ] } } }, { "type": "object", "description": "An artifact (file, blob, dataset) was produced by the run.", "required": [ "id", "kind", "type" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "sha256": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "artifact" ] }, "uri": { "type": [ "string", "null" ] } } }, { "type": "object", "description": "Run completed; status indicates how it ended.", "required": [ "status", "type" ], "properties": { "reason": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CloudRunDoneStatus" }, "type": { "type": "string", "enum": [ "done" ] } } }, { "type": "object", "description": "Memory compaction started for the run. Carries the token count\nobserved before compaction and the summarizer model ref.", "required": [ "type" ], "properties": { "summarizer_model_ref": { "type": [ "string", "null" ] }, "token_threshold": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tokens_before": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "compaction_started" ] } } }, { "type": "object", "description": "Memory compaction finished. Carries token counts before/after, the\nretained event count, and the summarizer model ref.", "required": [ "type" ], "properties": { "retained_event_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "summarizer_model_ref": { "type": [ "string", "null" ] }, "tokens_after": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tokens_before": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "compaction_finished" ] } } }, { "type": "object", "description": "An error that occurred during execution.", "required": [ "message", "type" ], "properties": { "cause": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunErrorCause" } ] }, "code": { "$ref": "#/components/schemas/CloudRunErrorCode" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "type": { "type": "string", "enum": [ "error" ] } } } ], "description": "A single event in the structured output trace.\n\nMatches the seren-desktop `WorkerEvent` model for consistency.\nStored as a JSON array in `output_events`." }, "CloudRunOutputEventEnvelope": { "allOf": [ { "$ref": "#/components/schemas/CloudRunOutputEvent" }, { "type": "object", "properties": { "content_index": { "type": [ "integer", "null" ], "format": "int64" }, "event_type": { "type": [ "string", "null" ] }, "item_id": { "type": [ "string", "null" ] }, "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunOutputEventKind" } ] }, "output_index": { "type": [ "integer", "null" ], "format": "int64" }, "sequence_number": { "type": [ "integer", "null" ], "format": "int64" } } } ], "description": "Envelope carrying structured output event metadata." }, "CloudRunOutputEventKind": { "type": "string", "description": "Canonical taxonomy for structured run output events.", "enum": [ "text", "thinking", "tool_call_started", "tool_call_completed", "tool_audit", "workflow", "approval_wait", "approval_decision", "guardrail_pass", "guardrail_fail", "handoff", "artifact", "compaction_started", "compaction_finished", "done", "error", "unknown" ] }, "CloudRunPendingApproval": { "type": "object", "description": "One tool call that is waiting for an approval decision.", "required": [ "id", "tool" ], "properties": { "args": {}, "function_call_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "tool": { "type": "string" } }, "additionalProperties": false }, "CloudRunPendingApprovalsResponse": { "type": "object", "description": "Current approval state for a run.", "required": [ "run_id", "status" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunPendingApproval" } }, "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "CloudRunReplayComparison": { "type": "object", "description": "Comparison summary between two run replay captures.", "required": [ "baseline_run_id", "candidate_run_id", "baseline_deployment_id", "candidate_deployment_id", "baseline_status", "candidate_status", "baseline_eval_capture_present", "candidate_eval_capture_present", "baseline_replay_artifact_present", "candidate_replay_artifact_present", "overall_match", "field_matches" ], "properties": { "baseline_deployment_id": { "type": "string", "format": "uuid" }, "baseline_eval_capture_present": { "type": "boolean" }, "baseline_replay_artifact_present": { "type": "boolean" }, "baseline_run_id": { "type": "string", "format": "uuid" }, "baseline_status": { "type": "string" }, "candidate_deployment_id": { "type": "string", "format": "uuid" }, "candidate_eval_capture_present": { "type": "boolean" }, "candidate_replay_artifact_present": { "type": "boolean" }, "candidate_run_id": { "type": "string", "format": "uuid" }, "candidate_status": { "type": "string" }, "field_matches": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunReplayFieldComparison" } }, "first_event_mismatch": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunReplayEventMismatch" } ] }, "notes": { "type": "array", "items": { "type": "string" } }, "overall_match": { "type": "boolean" } } }, "CloudRunReplayEventMismatch": { "type": "object", "description": "The first structured replay event that differs between two runs.", "required": [ "index", "baseline", "candidate" ], "properties": { "baseline": {}, "baseline_kind": { "type": [ "string", "null" ] }, "candidate": {}, "candidate_kind": { "type": [ "string", "null" ] }, "index": { "type": "integer", "format": "int32" } } }, "CloudRunReplayFieldComparison": { "type": "object", "description": "Field-level replay/eval summary comparison between two runs.", "required": [ "field", "label", "baseline", "candidate", "matches" ], "properties": { "baseline": {}, "candidate": {}, "field": { "type": "string" }, "label": { "type": "string" }, "matches": { "type": "boolean" } } }, "CloudRunToolAuditStatus": { "type": "string", "description": "Success/failure status reported by a `tool_audit` event.", "enum": [ "success", "failure" ] }, "CloudRunToolRefKind": { "type": "string", "description": "Kind of underlying tool_ref a `tool_audit` event applies to. Mirrors the\n`AgentToolRef` variants so operators can distinguish publisher calls from\nMCP, connector, remote-agent, remote-HTTP, or preset-group invocations.", "enum": [ "publisher", "mcp", "connector", "remote_agent", "remote_http", "preset_group", "builtin", "unknown" ] }, "ConnectorCatalogEntry": { "type": "object", "description": "One connector the platform supports for managed deployments.", "required": [ "connector_ref", "display_name", "description", "capability", "credentials", "supports_webhook_ingress", "requires_always_on", "connected" ], "properties": { "capability": { "type": "string", "description": "Connector capability grouping; messaging connectors deliver chat events." }, "connected": { "type": "boolean", "description": "Whether the organization already has an approved connection binding." }, "connector_ref": { "type": "string", "description": "Value used in `AgentToolRef::Connector.connector_ref`." }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorCredentialField" }, "description": "Credential and configuration fields the connector expects." }, "description": { "type": "string", "description": "Short product description of what connecting it enables." }, "display_name": { "type": "string", "description": "Display name for setup surfaces." }, "requires_always_on": { "type": "boolean", "description": "Whether attaching this connector requires an always-on deployment." }, "setup_url": { "type": [ "string", "null" ], "description": "Provider console URL where the required credentials are created." }, "supports_webhook_ingress": { "type": "boolean", "description": "Whether Seren mints a public webhook route for inbound events." } } }, "ConnectorCatalogResponse": { "type": "object", "description": "Catalog response listing supported connectors for the organization.", "required": [ "connectors" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorCatalogEntry" } } } }, "ConnectorCredentialField": { "type": "object", "description": "One credential or configuration field a connector requires.", "required": [ "name", "label", "required", "secret" ], "properties": { "format_hint": { "type": [ "string", "null" ], "description": "Short hint about the expected value shape, such as a token prefix." }, "label": { "type": "string", "description": "Human-readable label for setup surfaces." }, "name": { "type": "string", "description": "Stable field name used as the secret key or config key." }, "required": { "type": "boolean", "description": "Whether the connector cannot operate without this field." }, "secret": { "type": "boolean", "description": "Whether the value must be stored as a secret rather than plain config." } } }, "ConversationMessageOrder": { "type": "string", "enum": [ "asc", "desc" ] }, "CreateCloudDeploymentBundleRequest": { "type": "object", "description": "Request body for registering a content-addressed deployment bundle.", "required": [ "sha256", "size_bytes", "source_kind" ], "properties": { "sha256": { "type": "string", "description": "Lowercase hex SHA-256 digest of the raw bundle bytes." }, "size_bytes": { "type": "integer", "format": "int64", "description": "Exact raw bundle size in bytes." }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind", "description": "Bundle artifact format." } }, "additionalProperties": false }, "CreateCloudDeploymentBundleResponse": { "type": "object", "description": "Response returned when a deployment bundle is registered.", "required": [ "deployment_bundle_id", "sha256", "size_bytes", "source_kind", "upload_required" ], "properties": { "deployment_bundle_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" }, "upload_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_required": { "type": "boolean" }, "upload_url": { "type": [ "string", "null" ] } } }, "CreateCloudDeploymentEnvironmentRequest": { "type": "object", "description": "Request body for creating a reusable execution environment.", "required": [ "name", "docker_image" ], "properties": { "description": { "type": [ "string", "null" ] }, "docker_image": { "type": "string" }, "is_default": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "setup_commands": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "CreateCloudDeploymentRequest": { "type": "object", "description": "Request body for creating a cloud deployment.\n\nThe deployment envelope (name, skill, mode, schedule, eval gate, dashboard,\nalert policy, visibility, environment) is on the request itself; all\nruntime concerns (execution strategy, compute backend, limits, secrets,\nconfig, requirements, etc.) live inside the embedded `WorkloadSpec`.", "required": [ "skill_slug", "mode", "workload" ], "properties": { "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy", "description": "Deployment-level alert webhook routing policy." } ] }, "cron_schedule": { "type": [ "string", "null" ], "description": "Cron expression, required when `mode` is `cron`." }, "cron_timezone": { "type": [ "string", "null" ], "description": "Timezone for cron schedules. Defaults to `UTC` when omitted." }, "dashboard_config": { "description": "UI rendering hints for custom dashboards." }, "environment_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional reusable execution environment." }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Optional eval gate that must pass before runs proceed." } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode", "description": "Deployment mode (always_on, cron, job)." }, "name": { "type": [ "string", "null" ], "description": "Human-readable deployment name. Auto-generated when omitted." }, "skill_slug": { "type": "string", "description": "Stable slug identifying the skill being deployed." }, "visibility": { "type": [ "string", "null" ], "description": "Visibility mode (`open` or `opaque`)." }, "workload": { "$ref": "#/components/schemas/WorkloadSpec", "description": "Runtime workload specification (execution strategy, compute, limits, ...)." } }, "additionalProperties": false }, "CreateCloudEvalRunRequest": { "type": "object", "description": "Request body for executing an eval set against a deployment.", "properties": { "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "metadata": {} } }, "CreateCloudEvalSetRequest": { "type": "object", "description": "Request body for creating a seren-cloud eval set.", "required": [ "name" ], "properties": { "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "metadata": {}, "name": { "type": "string" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudEvalSetScheduleRequest" } ] } } }, "DataResponse_ApprovalInboxDecisionResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response returned after recording a decision.", "required": [ "entry_id", "decision_state" ], "properties": { "decision_state": { "$ref": "#/components/schemas/ApprovalDecisionState" }, "entry_id": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ApprovalInboxListResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Listing response for the approval inbox.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalInboxEntry" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; absent when no further entries exist." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_AuditEntry": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A single audit trail entry.", "required": [ "id", "organization_id", "sequence_number", "action", "actor", "details", "entry_hash", "prev_hash", "created_at" ], "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "details": {}, "entry_hash": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invocation_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "publisher_id": { "type": [ "string", "null" ], "format": "uuid" }, "sequence_number": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_BoundConnectorSecrets": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "connector_ref", "secret_fields", "secret_refs" ], "properties": { "connector_ref": { "type": "string" }, "deployment_id": { "type": "string", "format": "uuid" }, "secret_fields": { "type": "array", "items": { "type": "string" } }, "secret_refs": { "type": "array", "items": { "type": "string" }, "description": "Complete opaque reference set the client must cover with the next\nuser-signed secret resolution delegation." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudConversationListResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "conversations", "has_more" ], "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/CloudConversationResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudConversationMessagesResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "messages", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CloudConversationMessageResponse" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentActionStatusResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Generic status payload used by cloud deployment lifecycle endpoints.", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentAgentSchedule": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deployment_id", "schedule_key", "schedule_kind", "next_run_at", "status", "attempts", "max_attempts", "created_at", "updated_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_event_id": { "type": [ "string", "null" ], "format": "uuid" }, "max_attempts": { "type": "integer", "format": "int32" }, "next_run_at": { "type": "string", "format": "date-time" }, "schedule_key": { "type": "string" }, "schedule_kind": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentBundle": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Deployment bundle metadata without raw bundle content.", "required": [ "id", "organization_id", "user_id", "sha256", "size_bytes", "source_kind", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" }, "updated_at": { "type": "string", "format": "date-time" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentBundleDetail": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Deployment bundle metadata plus current deployment references.", "required": [ "bundle", "deployment_ids" ], "properties": { "bundle": { "$ref": "#/components/schemas/CloudDeploymentBundle" }, "deployment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentBundleDownloadResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Short-lived download instructions for a deployment's runtime bundle.", "required": [ "deployment_id", "deployment_bundle_id", "sha256", "size_bytes", "source_kind", "download_url", "download_expires_at" ], "properties": { "deployment_bundle_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentEnvironment": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Reusable execution environment profile for cloud deployments.", "required": [ "id", "organization_id", "user_id", "name", "docker_image", "setup_commands", "is_default", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "docker_image": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "setup_commands": {}, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentEvalDrift": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Snapshot of the current eval-set verdict alongside the baseline captured at\nthe last successful apply. Reports the delta on `passed` so operators can\nsee regressions explicitly. `current_passed`/`current_failed` are `None`\nwhen no eval run has completed against the gated set yet; in that case the\nstatus carries an explanatory `reason`.", "required": [ "deployment_id", "eval_gate_set_id", "message", "checked_at" ], "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGateDriftBaseline" } ] }, "checked_at": { "type": "string", "format": "date-time" }, "current_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_failed": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "current_passed": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "current_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_run_status": { "type": [ "string", "null" ] }, "current_verdict_status": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_set_id": { "type": "string", "format": "uuid" }, "failed_delta": { "type": [ "integer", "null" ], "format": "int32", "description": "`current_failed - baseline_failed` when both sides are present." }, "message": { "type": "string", "description": "Operator-safe one-line summary of the drift state. Always present." }, "passed_delta": { "type": [ "integer", "null" ], "format": "int32", "description": "`current_passed - baseline_passed` when both sides are present." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentRunEvent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A single execution run event for a cloud deployment.", "required": [ "id", "deployment_id", "organization_id", "user_id", "execution_id", "compute_backend", "source", "status", "execution_time_ms", "billed_duration_ms", "requested_cpu_millicores", "requested_memory_mib", "compute_cost_atomic", "compute_cost_usd", "inference_input_tokens", "inference_output_tokens", "inference_cost_atomic", "inference_cost_usd", "started_at", "invocation_payload", "metadata", "created_at", "updated_at" ], "properties": { "billed_duration_ms": { "type": "integer", "format": "int32" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "compute_cost_atomic": { "type": "integer", "format": "int64" }, "compute_cost_usd": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string" }, "execution_time_ms": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "inference_cost_atomic": { "type": "integer", "format": "int64" }, "inference_cost_usd": { "type": "string" }, "inference_input_tokens": { "type": "integer", "format": "int64" }, "inference_output_tokens": { "type": "integer", "format": "int64" }, "invocation_payload": { "description": "Canonical JSON payload submitted to trigger the run." }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": { "type": [ "string", "null" ], "description": "Raw stdout/stderr output. Universal fallback for all backend types." }, "output_events": { "description": "Structured event trace for agentic executions (thinking, tool calls, text).\nNull for non-agentic scripts that produce plain stdout/stderr." }, "requested_cpu_millicores": { "type": "integer", "format": "int32" }, "requested_memory_mib": { "type": "integer", "format": "int32" }, "run_name": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "session_url": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentRunInvocationResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response envelope for triggering a cloud deployment run.\n\nThis schema intentionally covers both synchronous and asynchronous responses\nacross compute backends (`always_on`, `cron`, Cloudflare, Daytona).", "required": [ "status" ], "properties": { "compute_cost_atomic": { "type": [ "integer", "null" ], "format": "int64", "description": "Atomic compute cost units when emitted by the backend." }, "execution_id": { "type": [ "string", "null" ], "description": "Backend execution ID for correlating orchestrator/job-level status." }, "execution_time_ms": { "type": [ "integer", "null" ], "format": "int32", "description": "Execution duration in milliseconds when available." }, "exit_code": { "type": [ "integer", "null" ], "format": "int32", "description": "Process exit code for runtimes that expose it (for example Daytona)." }, "job_name": { "type": [ "string", "null" ], "description": "K8s Job name for queued cron executions." }, "result": { "description": "Backend-specific result payload." }, "run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Persisted run event ID when the invocation is tracked in the run history table." }, "sandbox_id": { "type": [ "string", "null" ], "description": "Daytona sandbox ID when applicable." }, "script_name": { "type": [ "string", "null" ], "description": "Cloudflare Worker script name when applicable." }, "status": { "type": "string", "description": "Lifecycle status reported by the backend (`queued`, `running`, `completed`, etc.)." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudDeploymentSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Summary view for listing deployments (excludes large fields like code_bundle).", "required": [ "id", "organization_id", "user_id", "name", "skill_slug", "compute_backend", "runtime_kind", "mode", "status", "code_bundle_hash", "orchestration_mode", "requirements", "visibility", "created_at", "updated_at" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current managed-agent revision, when this is a managed seren-agent deployment." }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy" } ] }, "code_bundle_hash": { "type": "string" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "dashboard_config": {}, "deployment_bundle_id": { "type": [ "string", "null" ], "format": "uuid" }, "endpoint_url": { "type": [ "string", "null" ] }, "environment_id": { "type": [ "string", "null" ], "format": "uuid" }, "error_message": { "type": [ "string", "null" ] }, "eval_gate_max_age_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "eval_gate_set_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus" } ] }, "id": { "type": "string", "format": "uuid" }, "managed_agent": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSummary" } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy" } ] }, "orchestration_mode": { "$ref": "#/components/schemas/OrchestrationMode" }, "organization_id": { "type": "string", "format": "uuid" }, "publisher_only": { "type": "boolean" }, "requirements": {}, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "skill_slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "description": "Visibility mode: \"open\" (default) or \"opaque\" (redacts selected details from non-owners)." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudEvalCase": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Reusable eval baseline captured from a run or created manually later.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "source_kind", "name", "invocation_payload", "expected_eval_capture", "expected_replay_events", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output": { "type": [ "string", "null" ] }, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "id": { "type": "string", "format": "uuid" }, "invocation_payload": {}, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "source_kind": { "type": "string" }, "source_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudEvalCaseResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Per-case result row captured when running an eval set.", "required": [ "id", "eval_run_id", "eval_set_id", "eval_case_id", "organization_id", "status", "expected_eval_capture", "actual_eval_capture", "expected_replay_events", "actual_replay_events", "comparison", "metadata", "created_at", "updated_at" ], "properties": { "actual_eval_capture": {}, "actual_output_sha256": { "type": [ "string", "null" ] }, "actual_replay_events": {}, "actual_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "actual_status": { "type": [ "string", "null" ] }, "comparison": {}, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_case_id": { "type": "string", "format": "uuid" }, "eval_run_id": { "type": "string", "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "expected_status": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudEvalRun": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Durable execution record for running an eval set against a deployment.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "status", "total_cases", "completed_cases", "passed_cases", "failed_cases", "errored_cases", "summary", "verdict", "metadata", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_cases": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "errored_cases": { "type": "integer", "format": "int32" }, "eval_set_id": { "type": "string", "format": "uuid" }, "failed_cases": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "passed_cases": { "type": "integer", "format": "int32" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/CloudEvalRunSummary" }, "total_cases": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" }, "verdict": { "$ref": "#/components/schemas/CloudEvalRunVerdict" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudEvalSet": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Durable grouping for reusable seren-cloud eval cases.", "required": [ "id", "organization_id", "created_by_user_id", "name", "criteria", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudEvalSetSchedule" } ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudInteractiveSessionDetailResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "session", "messages", "message_pagination" ], "properties": { "message_pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CloudInteractiveSessionHistoryMessage" } }, "session": { "$ref": "#/components/schemas/CloudInteractiveSessionResponse" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudInteractiveSessionMessageResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "message_id", "session_id", "client_message_id", "duplicate", "stream_url" ], "properties": { "client_message_id": { "type": "string" }, "duplicate": { "type": "boolean" }, "message_id": { "type": "string", "format": "uuid" }, "run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRunInvocationResponse" } ] }, "session_id": { "type": "string", "format": "uuid" }, "stream_url": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudInteractiveSessionOpenResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "session_id", "conversation_id", "status", "stream_url", "ws_url", "ws_ticket", "expires_at", "idle_expires_at" ], "properties": { "conversation_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "idle_expires_at": { "type": "string", "format": "date-time" }, "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "stream_url": { "type": "string" }, "ws_ticket": { "type": "string" }, "ws_url": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudRunEvalsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Eval records linked to a run, either as the promoted source or as an actual replay target.", "required": [ "run_id" ], "properties": { "actual_eval_case_results": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalCaseResult" } }, "run_id": { "type": "string", "format": "uuid" }, "source_eval_cases": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEvalCase" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudRunLiveState": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Operator-safe live status projection for a run.", "required": [ "run_id", "deployment_id", "status", "phase", "pending_approval_count", "latest_sequence", "started_at", "updated_at", "terminal" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "current_step": { "type": [ "string", "null" ] }, "current_tool": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "latest_event_kind": { "type": [ "string", "null" ] }, "latest_sequence": { "type": "integer", "format": "int64" }, "pending_approval_count": { "type": "integer", "format": "int64" }, "phase": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "terminal": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudRunPendingApprovalsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Current approval state for a run.", "required": [ "run_id", "status" ], "properties": { "checkpoint_id": { "type": [ "string", "null" ] }, "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunPendingApproval" } }, "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CloudRunReplayComparison": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Comparison summary between two run replay captures.", "required": [ "baseline_run_id", "candidate_run_id", "baseline_deployment_id", "candidate_deployment_id", "baseline_status", "candidate_status", "baseline_eval_capture_present", "candidate_eval_capture_present", "baseline_replay_artifact_present", "candidate_replay_artifact_present", "overall_match", "field_matches" ], "properties": { "baseline_deployment_id": { "type": "string", "format": "uuid" }, "baseline_eval_capture_present": { "type": "boolean" }, "baseline_replay_artifact_present": { "type": "boolean" }, "baseline_run_id": { "type": "string", "format": "uuid" }, "baseline_status": { "type": "string" }, "candidate_deployment_id": { "type": "string", "format": "uuid" }, "candidate_eval_capture_present": { "type": "boolean" }, "candidate_replay_artifact_present": { "type": "boolean" }, "candidate_run_id": { "type": "string", "format": "uuid" }, "candidate_status": { "type": "string" }, "field_matches": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunReplayFieldComparison" } }, "first_event_mismatch": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunReplayEventMismatch" } ] }, "notes": { "type": "array", "items": { "type": "string" } }, "overall_match": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ConnectorCatalogResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Catalog response listing supported connectors for the organization.", "required": [ "connectors" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorCatalogEntry" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_CreateCloudDeploymentBundleResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response returned when a deployment bundle is registered.", "required": [ "deployment_bundle_id", "sha256", "size_bytes", "source_kind", "upload_required" ], "properties": { "deployment_bundle_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_kind": { "$ref": "#/components/schemas/CloudDeploymentBundleSourceKind" }, "upload_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_required": { "type": "boolean" }, "upload_url": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_DeploymentSpendSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Aggregated spend summary for a single cloud deployment.", "required": [ "compute_cost_usd", "inference_cost_usd", "total_cost_usd", "run_count" ], "properties": { "compute_cost_usd": { "type": "string" }, "first_event_at": { "type": [ "string", "null" ], "format": "date-time" }, "inference_cost_usd": { "type": "string" }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_count": { "type": "integer", "format": "int64" }, "total_cost_usd": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedEmployeeSecretRefsPreview": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "secret_refs" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "secret_refs": { "type": "array", "items": { "type": "string" }, "description": "Complete reference set the client must cover with the next user-signed delegation." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedStorageAttachment": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "agent_identity_id", "bucket_slug", "permission" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "deployment_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/ManagedStoragePermission" }, "workspace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedStorageWorkspaceRequest" } ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_AuditEntry": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A single audit trail entry.", "required": [ "id", "organization_id", "sequence_number", "action", "actor", "details", "entry_hash", "prev_hash", "created_at" ], "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "details": {}, "entry_hash": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "invocation_id": { "type": [ "string", "null" ], "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "prev_hash": { "type": "string" }, "publisher_id": { "type": [ "string", "null" ], "format": "uuid" }, "sequence_number": { "type": "integer", "format": "int64" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudDeploymentAgentSchedule": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "deployment_id", "schedule_key", "schedule_kind", "next_run_at", "status", "attempts", "max_attempts", "created_at", "updated_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_event_id": { "type": [ "string", "null" ], "format": "uuid" }, "max_attempts": { "type": "integer", "format": "int32" }, "next_run_at": { "type": "string", "format": "date-time" }, "schedule_key": { "type": "string" }, "schedule_kind": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudDeploymentEnvironment": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Reusable execution environment profile for cloud deployments.", "required": [ "id", "organization_id", "user_id", "name", "docker_image", "setup_commands", "is_default", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "docker_image": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "setup_commands": {}, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudDeploymentRunArtifact": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Artifact emitted by a cloud run (for example PR links, plans, screenshots).", "required": [ "id", "run_event_id", "deployment_id", "organization_id", "user_id", "artifact_type", "payload", "created_at", "updated_at" ], "properties": { "artifact_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "payload": {}, "run_event_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudDeploymentRunEvent": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A single execution run event for a cloud deployment.", "required": [ "id", "deployment_id", "organization_id", "user_id", "execution_id", "compute_backend", "source", "status", "execution_time_ms", "billed_duration_ms", "requested_cpu_millicores", "requested_memory_mib", "compute_cost_atomic", "compute_cost_usd", "inference_input_tokens", "inference_output_tokens", "inference_cost_atomic", "inference_cost_usd", "started_at", "invocation_payload", "metadata", "created_at", "updated_at" ], "properties": { "billed_duration_ms": { "type": "integer", "format": "int32" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "compute_cost_atomic": { "type": "integer", "format": "int64" }, "compute_cost_usd": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string" }, "execution_time_ms": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "inference_cost_atomic": { "type": "integer", "format": "int64" }, "inference_cost_usd": { "type": "string" }, "inference_input_tokens": { "type": "integer", "format": "int64" }, "inference_output_tokens": { "type": "integer", "format": "int64" }, "invocation_payload": { "description": "Canonical JSON payload submitted to trigger the run." }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "output": { "type": [ "string", "null" ], "description": "Raw stdout/stderr output. Universal fallback for all backend types." }, "output_events": { "description": "Structured event trace for agentic executions (thinking, tool calls, text).\nNull for non-agentic scripts that produce plain stdout/stderr." }, "requested_cpu_millicores": { "type": "integer", "format": "int32" }, "requested_memory_mib": { "type": "integer", "format": "int32" }, "run_name": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "session_url": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudDeploymentSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Summary view for listing deployments (excludes large fields like code_bundle).", "required": [ "id", "organization_id", "user_id", "name", "skill_slug", "compute_backend", "runtime_kind", "mode", "status", "code_bundle_hash", "orchestration_mode", "requirements", "visibility", "created_at", "updated_at" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current managed-agent revision, when this is a managed seren-agent deployment." }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy" } ] }, "code_bundle_hash": { "type": "string" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "created_at": { "type": "string", "format": "date-time" }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "dashboard_config": {}, "deployment_bundle_id": { "type": [ "string", "null" ], "format": "uuid" }, "endpoint_url": { "type": [ "string", "null" ] }, "environment_id": { "type": [ "string", "null" ], "format": "uuid" }, "error_message": { "type": [ "string", "null" ] }, "eval_gate_max_age_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "eval_gate_set_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus" } ] }, "id": { "type": "string", "format": "uuid" }, "managed_agent": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSummary" } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy" } ] }, "orchestration_mode": { "$ref": "#/components/schemas/OrchestrationMode" }, "organization_id": { "type": "string", "format": "uuid" }, "publisher_only": { "type": "boolean" }, "requirements": {}, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "skill_slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "description": "Visibility mode: \"open\" (default) or \"opaque\" (redacts selected details from non-owners)." } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudEvalCase": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Reusable eval baseline captured from a run or created manually later.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "source_kind", "name", "invocation_payload", "expected_eval_capture", "expected_replay_events", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output": { "type": [ "string", "null" ] }, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "id": { "type": "string", "format": "uuid" }, "invocation_payload": {}, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "source_kind": { "type": "string" }, "source_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudEvalCaseResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Per-case result row captured when running an eval set.", "required": [ "id", "eval_run_id", "eval_set_id", "eval_case_id", "organization_id", "status", "expected_eval_capture", "actual_eval_capture", "expected_replay_events", "actual_replay_events", "comparison", "metadata", "created_at", "updated_at" ], "properties": { "actual_eval_capture": {}, "actual_output_sha256": { "type": [ "string", "null" ] }, "actual_replay_events": {}, "actual_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "actual_status": { "type": [ "string", "null" ] }, "comparison": {}, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "eval_case_id": { "type": "string", "format": "uuid" }, "eval_run_id": { "type": "string", "format": "uuid" }, "eval_set_id": { "type": "string", "format": "uuid" }, "expected_eval_capture": {}, "expected_output_sha256": { "type": [ "string", "null" ] }, "expected_replay_events": {}, "expected_status": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudEvalRun": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Durable execution record for running an eval set against a deployment.", "required": [ "id", "eval_set_id", "organization_id", "created_by_user_id", "status", "total_cases", "completed_cases", "passed_cases", "failed_cases", "errored_cases", "summary", "verdict", "metadata", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_cases": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "errored_cases": { "type": "integer", "format": "int32" }, "eval_set_id": { "type": "string", "format": "uuid" }, "failed_cases": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "passed_cases": { "type": "integer", "format": "int32" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/CloudEvalRunSummary" }, "total_cases": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" }, "verdict": { "$ref": "#/components/schemas/CloudEvalRunVerdict" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudEvalSet": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Durable grouping for reusable seren-cloud eval cases.", "required": [ "id", "organization_id", "created_by_user_id", "name", "criteria", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudEvalSetSchedule" } ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudInteractiveSessionDetailResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "session", "messages", "message_pagination" ], "properties": { "message_pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CloudInteractiveSessionHistoryMessage" } }, "session": { "$ref": "#/components/schemas/CloudInteractiveSessionResponse" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudPendingApprovalRun": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Awaiting-approval run entry returned by the approval inbox endpoints.", "required": [ "run_id", "deployment_id", "execution_id", "compute_backend", "source", "status", "started_at", "updated_at" ], "properties": { "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "deployment_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string" }, "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRunPendingApproval" } }, "run_id": { "type": "string", "format": "uuid" }, "run_name": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_CloudRunOutputEventEnvelope": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CloudRunOutputEvent" }, { "type": "object", "properties": { "content_index": { "type": [ "integer", "null" ], "format": "int64" }, "event_type": { "type": [ "string", "null" ] }, "item_id": { "type": [ "string", "null" ] }, "kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudRunOutputEventKind" } ] }, "output_index": { "type": [ "integer", "null" ], "format": "int64" }, "sequence_number": { "type": [ "integer", "null" ], "format": "int64" } } } ], "description": "Envelope carrying structured output event metadata." } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_ManagedStorageBucket": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "slug" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "slug": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_VerificationResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Result of verifying the audit chain integrity.", "required": [ "verified", "entries_checked" ], "properties": { "entries_checked": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "first_invalid_sequence": { "type": [ "integer", "null" ], "format": "int64" }, "verified": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_VerifyConnectorCredentialsResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Result of a live connector credential verification.", "required": [ "connector_ref", "ok" ], "properties": { "connector_ref": { "type": "string" }, "failure_reason": { "type": [ "string", "null" ], "description": "Provider-reported reason when verification fails." }, "identity": { "type": [ "string", "null" ], "description": "Human-readable identity the provider resolved on success, such as\nthe bot and workspace name." }, "ok": { "type": "boolean", "description": "Whether the provider accepted the credentials." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DeploymentSpendSummary": { "type": "object", "description": "Aggregated spend summary for a single cloud deployment.", "required": [ "compute_cost_usd", "inference_cost_usd", "total_cost_usd", "run_count" ], "properties": { "compute_cost_usd": { "type": "string" }, "first_event_at": { "type": [ "string", "null" ], "format": "date-time" }, "inference_cost_usd": { "type": "string" }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_count": { "type": "integer", "format": "int64" }, "total_cost_usd": { "type": "string" } } }, "EvalGate": { "type": "object", "description": "Eval gate configuration that must pass with a fresh verdict before runs proceed.\n\n`block_on_failure` controls what happens at update or rollback apply time:\nwhen `Some(true)`, the control plane rejects the apply if the latest eval\nverdict has failed or has expired beyond `max_age_seconds`. The default\n(`None`/`false`) preserves the original freshness-only behavior for\nback-compat.\n\n`schedule` is an operator-supplied cron expression that asks the control\nplane to run the gated eval set on a fixed cadence so freshness stays\ncurrent without manual triggering. The actual scheduling-loop dispatch is\nowned by the eval-set scheduler today (see `CloudEvalSetSchedule`); this\nfield records the operator intent on the deployment side.\n\n`drift_baseline` is captured by the apply path when an update or rollback\ncommits with a passing gate. Subsequent eval runs compare against the\nbaseline so operators see regressions explicitly.", "required": [ "set_id", "max_age_seconds" ], "properties": { "block_on_failure": { "type": [ "boolean", "null" ] }, "drift_baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGateDriftBaseline", "description": "Eval-set verdict captured at the most recent successful apply. Set by\nthe control plane; clients may submit this field but the control plane\nwill overwrite it on every successful apply." } ] }, "max_age_seconds": { "type": "integer", "format": "int32" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGateSchedule", "description": "Optional cron-driven cadence for re-running the gated eval set." } ] }, "set_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "EvalGateDriftBaseline": { "type": "object", "description": "Snapshot of an eval-set verdict captured at the last successful apply.\nSubsequent eval runs (manual or scheduled) compare against this snapshot\nto surface drift; the apply path overwrites this value on every commit.", "required": [ "baseline_set_id", "baseline_run_id", "baseline_passed", "baseline_failed", "baseline_captured_at" ], "properties": { "baseline_captured_at": { "type": "string", "format": "date-time" }, "baseline_failed": { "type": "integer", "format": "int32", "minimum": 0 }, "baseline_passed": { "type": "integer", "format": "int32", "minimum": 0 }, "baseline_run_id": { "type": "string", "format": "uuid" }, "baseline_set_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "EvalGateSchedule": { "type": "object", "description": "Cron-driven cadence requested by the operator for an eval gate. The\ntimezone is an IANA name (e.g. `UTC`, `America/New_York`); when omitted the\ncontrol plane defaults to UTC.", "required": [ "cron" ], "properties": { "cron": { "type": "string", "description": "Standard 5-field cron expression. Validated against the same parser\nthat backs deployment cron schedules." }, "timezone": { "type": [ "string", "null" ], "description": "Optional IANA timezone. Defaults to `UTC` when absent." } }, "additionalProperties": false }, "InvocationOrigin": { "oneOf": [ { "type": "object", "description": "Invocation not received through a governed collaboration surface.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "direct" ] } } }, { "type": "object", "description": "Invocation received through the current organization channel binding.", "required": [ "binding", "kind" ], "properties": { "binding": { "$ref": "#/components/schemas/ChannelBindingRef" }, "kind": { "type": "string", "enum": [ "channel" ] } } } ], "description": "Trusted source that initiated an organization-authorized invocation.\n\nThis is provenance rather than resource ownership. A channel-originated\ninvocation can read a provider-owned knowledge selection and can have an\nindependently authorized output audience." }, "KnowledgeCaptureTarget": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "none" ] } } }, { "type": "object", "description": "Capture into the organization collection named by `knowledge_selection`.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "organization_selection" ] } } }, { "type": "object", "description": "Capture into personal knowledge owned by the authenticated user.", "required": [ "provider", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "personal" ] }, "provider": { "$ref": "#/components/schemas/KnowledgeProvider" } } } ], "description": "Single knowledge destination permitted to receive captured interaction data.\n\nPersonal capture is relative to the authenticated user bound by the\nenclosing context. It is an explicit cross-boundary write and does not\nfollow automatically from invocation origin or output audience.\n\nEmployee identity is deliberately absent because it identifies the actor,\nwhile Memory has no agent-owned capture boundary." }, "KnowledgeProvider": { "type": "string", "description": "Service that owns and revalidates a knowledge selection or capture target.", "enum": [ "memory" ] }, "KnowledgeSelection": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "none" ] } } }, { "type": "object", "required": [ "provider", "selection_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "provider": { "$ref": "#/components/schemas/KnowledgeProvider" }, "selection_id": { "type": "string", "format": "uuid" } } } ], "description": "Organization knowledge requested for one invocation.\n\nSeren Core transports the selection opaquely, and the named provider retains\nfinal authorization over the stable selection and its current materialized\nsources." }, "ManagedAgentApprovalPolicy": { "type": "string", "enum": [ "read_only", "allow_mutations" ] }, "ManagedAgentLlmConnection": { "oneOf": [ { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "seren_private_models" ] } } } ] }, "ManagedAgentModelPolicy": { "type": "string", "enum": [ "fast", "balanced", "deep" ] }, "ManagedAgentRuntimeAdapter": { "type": "string", "enum": [ "seren_agent" ] }, "ManagedAgentSummary": { "type": "object", "required": [ "publisher", "template", "target_framework", "runtime_adapter", "build_target", "tool_presets", "allowed_publisher_operations", "resolved_tools", "approval_policy", "model_policy", "routing_reason" ], "properties": { "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "allowed_remote_agent_origins": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "build_target": { "type": "string" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "publisher": { "type": "string" }, "resolved_tools": { "type": "array", "items": { "type": "string" } }, "routing_reason": { "type": "string" }, "runtime_adapter": { "type": "string" }, "target_framework": { "type": "string" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" } } } }, "ManagedAgentTemplate": { "type": "string", "enum": [ "research_monitor", "workflow_agent" ] }, "ManagedAgentToolPreset": { "type": "string", "enum": [ "live_data", "publisher_actions", "database" ] }, "ManagedEmployeeSecretRefsPreview": { "type": "object", "required": [ "deployment_id", "secret_refs" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "secret_refs": { "type": "array", "items": { "type": "string" }, "description": "Complete reference set the client must cover with the next user-signed delegation." } } }, "ManagedExternalDatabaseAccess": { "type": "string", "enum": [ "read_only", "read_write" ] }, "ManagedExternalDatabaseAttachment": { "type": "object", "required": [ "project_id", "branch_id", "database" ], "properties": { "access": { "$ref": "#/components/schemas/ManagedExternalDatabaseAccess" }, "branch_id": { "type": "string", "format": "uuid" }, "database": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "ManagedStorageAttachment": { "type": "object", "required": [ "deployment_id", "agent_identity_id", "bucket_slug", "permission" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "deployment_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/ManagedStoragePermission" }, "workspace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedStorageWorkspaceRequest" } ] } } }, "ManagedStorageBucket": { "type": "object", "required": [ "slug" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "slug": { "type": "string" } } }, "ManagedStoragePermission": { "type": "string", "enum": [ "reader", "writer" ] }, "ManagedStorageWorkspaceRequest": { "type": "object", "properties": { "restore_on_start": { "type": "boolean" }, "retention_count": { "type": "integer", "format": "int32" }, "snapshot_interval_seconds": { "type": "integer", "format": "int64", "minimum": 0 }, "snapshot_on_stop": { "type": "boolean" } }, "additionalProperties": false }, "OrchestrationMode": { "type": "string", "description": "Cloud deployment orchestration mode.\n\n`Script` (default): container runs user code directly (existing behavior).\n`Llm`: container runs the seren-orchestrator LLM tool-calling loop.", "enum": [ "script", "llm" ] }, "OutputAudience": { "oneOf": [ { "type": "object", "description": "The organization identified by the enclosing context.\n\nDeclared as a zero-field struct variant rather than a unit variant on\npurpose. On an internally tagged enum, `deny_unknown_fields` does not\napply to a unit variant: `{\"kind\": \"organization\", \"readable_by\": [..]}`\ndeserializes successfully into a unit `Organization` and the extra key\nis discarded. A narrowing audience constraint added by a later Core\nrelease would then be silently dropped by an older consumer, which is\nthe failure this crate exists to prevent. `rejects_unknown_variant_constraints`\nfails if this is simplified back to a unit variant.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "organization" ] } } }, { "type": "object", "description": "External channel represented by a current organization binding.", "required": [ "binding", "kind" ], "properties": { "binding": { "$ref": "#/components/schemas/ChannelBindingRef" }, "kind": { "type": "string", "enum": [ "channel" ] } } } ], "description": "Audience permitted to receive output or protected side effects." }, "PreviewManagedEmployeeSecretRefsRequest": { "type": "object", "required": [ "additional_refs" ], "properties": { "additional_refs": { "type": "array", "items": { "type": "string" }, "description": "Opaque references proposed for the next employee configuration." } }, "additionalProperties": false }, "PromoteRunToCloudEvalCaseRequest": { "type": "object", "description": "Request body for promoting a run into a reusable eval case.", "properties": { "metadata": {}, "name": { "type": [ "string", "null" ] } } }, "RequirementSource": { "type": "string", "description": "Where a deployment requirement should be satisfied from.", "enum": [ "env", "secret", "config" ] }, "RequirementSpec": { "type": "object", "description": "A declared requirement for a cloud deployment (validated at deploy time).", "required": [ "key", "source" ], "properties": { "description": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "source": { "$ref": "#/components/schemas/RequirementSource" } } }, "SideEffectPolicy": { "type": "object", "description": "Deployment-level safety controls for mutating built-in publisher calls.", "properties": { "max_mutating_calls_per_run": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_seconds_between_mutating_calls": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "require_idempotency_key": { "type": "boolean" } } }, "TaskLabel": { "type": "string", "description": "Organization-defined policy selector in canonical form.\n\nThe syntax is enforced during deserialization rather than by convention, so\nevery producer and consumer of an [`OrganizationWorkContext`] agrees on which labels\nexist without each one repeating the check.", "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$" }, "ToolApprovalCondition": { "oneOf": [ { "type": "object", "required": [ "path", "type" ], "properties": { "gte": { "type": [ "number", "null" ], "format": "double" }, "lte": { "type": [ "number", "null" ], "format": "double" }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "numeric_threshold" ] } } }, { "type": "object", "required": [ "path", "value", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "string_equals" ] }, "value": { "type": "string" } } }, { "type": "object", "required": [ "path", "values", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "string_in" ] }, "values": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "path", "values", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "string_not_in" ] }, "values": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "path", "value", "type" ], "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean_equals" ] }, "value": { "type": "boolean" } } }, { "type": "object", "required": [ "start_hour", "end_hour", "type" ], "properties": { "end_hour": { "type": "integer", "format": "int32", "minimum": 0 }, "start_hour": { "type": "integer", "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "outside_hours_utc" ] } } } ], "description": "Condition for a conditional approval rule." }, "ToolApprovalRule": { "type": "object", "description": "Conditional approval rule for an orchestration tool.", "properties": { "approval_reason": { "type": [ "string", "null" ] }, "approval_type": { "$ref": "#/components/schemas/ToolApprovalType" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalCondition" } } } }, "ToolApprovalType": { "type": "string", "description": "Approval policy for an LLM orchestration tool.", "enum": [ "none", "required", "audit" ] }, "ToolDefinition": { "type": "object", "description": "A single tool definition for LLM orchestration.", "required": [ "name", "description" ], "properties": { "approval_reason": { "type": [ "string", "null" ] }, "approval_rules": { "type": "array", "items": { "$ref": "#/components/schemas/ToolApprovalRule" } }, "approval_type": { "$ref": "#/components/schemas/ToolApprovalType" }, "description": { "type": "string" }, "input_schema": {}, "max_output_bytes": { "type": [ "integer", "null" ], "description": "Maximum output size in bytes for this tool. Output exceeding this limit is truncated.", "minimum": 0 }, "name": { "type": "string" }, "side_effecting": { "type": [ "boolean", "null" ], "description": "Whether this tool can perform non-read work. Side-effecting tools are\nprotected so an interrupted run never silently re-runs them; set `false`\nonly for deterministic, side-effect-free reads." }, "timeout_override_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-tool timeout override in seconds. Overrides the deployment-level tool timeout.", "minimum": 0 } } }, "UpdateCloudDeploymentEnvironmentRequest": { "type": "object", "description": "Request body for updating a reusable execution environment.", "properties": { "description": { "type": [ "string", "null" ] }, "docker_image": { "type": [ "string", "null" ] }, "is_default": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "setup_commands": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "UpdateCloudDeploymentRequest": { "type": "object", "description": "Partial update request for an existing cloud deployment.\n\nMirrors the deployment envelope as `Option<...>` for partial update. Runtime\nworkload changes use deployment-specific replacement/update endpoints.", "properties": { "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy", "description": "Updated alert webhook policy." } ] }, "clear_alert_policy": { "type": "boolean", "description": "Clear any existing alert policy." }, "clear_dashboard_config": { "type": "boolean", "description": "Clear any existing dashboard config." }, "clear_eval_gate": { "type": "boolean", "description": "Clear any existing eval gate configuration." }, "dashboard_config": { "description": "Updated dashboard rendering config." }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Updated eval gate configuration." } ] }, "visibility": { "type": [ "string", "null" ], "description": "Updated visibility mode." } }, "additionalProperties": false }, "UpdateCloudEvalSetRequest": { "type": "object", "description": "Request body for replacing a seren-cloud eval set.", "required": [ "name" ], "properties": { "criteria": { "$ref": "#/components/schemas/CloudEvalCriteria" }, "deployment_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "metadata": {}, "name": { "type": "string" }, "schedule": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudEvalSetScheduleRequest" } ] } } }, "VerificationResult": { "type": "object", "description": "Result of verifying the audit chain integrity.", "required": [ "verified", "entries_checked" ], "properties": { "entries_checked": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "first_invalid_sequence": { "type": [ "integer", "null" ], "format": "int64" }, "verified": { "type": "boolean" } } }, "VerifyConnectorCredentialsRequest": { "type": "object", "description": "Request to verify connector credentials against the provider before\nstoring them. Values are used for the live check only and are never\nstored or logged.", "required": [ "credentials" ], "properties": { "credentials": { "type": "object", "description": "Credential values keyed by the catalog field names.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "VerifyConnectorCredentialsResponse": { "type": "object", "description": "Result of a live connector credential verification.", "required": [ "connector_ref", "ok" ], "properties": { "connector_ref": { "type": "string" }, "failure_reason": { "type": [ "string", "null" ], "description": "Provider-reported reason when verification fails." }, "identity": { "type": [ "string", "null" ], "description": "Human-readable identity the provider resolved on success, such as\nthe bot and workspace name." }, "ok": { "type": "boolean", "description": "Whether the provider accepted the credentials." } } }, "WorkloadExecution": { "oneOf": [ { "type": "object", "description": "LLM-orchestrated agent with optional tool definitions and model config.", "required": [ "bundle", "type" ], "properties": { "adapter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentRuntimeAdapter", "description": "Runtime adapter used to run the agent loop." } ] }, "bundle": { "$ref": "#/components/schemas/AgentBundle", "description": "Authored instruction and asset files for the LLM agent." }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Ordered list of fallback model identifiers tried on primary failure." }, "llm_connection": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentLlmConnection", "description": "LLM connection override for private-model routing." } ] }, "model_config": { "description": "Arbitrary model parameters forwarded to the provider." }, "model_id": { "type": [ "string", "null" ], "description": "Model identifier override (e.g. `\"anthropic/claude-sonnet-4.6\"`)." }, "tool_definitions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tool definitions available to the LLM during execution." }, "type": { "type": "string", "enum": [ "llm" ] } } }, { "type": "object", "description": "Code workload deployed from a content-addressed deployment bundle.", "required": [ "deployment_bundle_id", "type" ], "properties": { "deployment_bundle_id": { "type": "string", "format": "uuid", "description": "Uploaded deployment bundle identifier returned by `seren_cloud_create_deployment_bundle`." }, "requirements_txt": { "type": [ "string", "null" ], "description": "Python requirements.txt contents injected at build time." }, "runtime_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind", "description": "Runtime kind (language/format) for the deployment bundle." } ] }, "type": { "type": "string", "enum": [ "code" ] } } } ], "description": "Execution strategy for a workload.\n\nTagged on the `type` field so the wire shape is `{\"type\":\"llm\",...}` or\n`{\"type\":\"code\",...}`." }, "WorkloadLimits": { "type": "object", "description": "Resource and iteration limits applied to a workload run.\n\nAll fields default to `None` (no limit).", "properties": { "context_budget_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum context window budget in tokens.", "minimum": 0 }, "max_iterations": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of agent loop iterations before the run is terminated.", "minimum": 0 }, "max_timeout_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Wall-clock timeout in seconds for the entire run.", "minimum": 0 }, "max_tool_calls_per_run": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of tool calls across the entire run.", "minimum": 0 }, "max_tool_output_chars": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of characters kept from any single tool output.", "minimum": 0 } }, "additionalProperties": false }, "WorkloadSpec": { "type": "object", "description": "Full runtime specification for a cloud workload.\n\nCaptures compute backend, network policy, side-effect controls, and the\nexecution discriminator. The `execution` field is required; all other\nfields default to `None` or their zero value.", "required": [ "execution" ], "properties": { "compute_backend": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentComputeBackend", "description": "Compute backend override. Uses the deployment default when absent." } ] }, "config": { "description": "Non-secret operator-supplied configuration passed to the workload runtime." }, "execution": { "$ref": "#/components/schemas/WorkloadExecution", "description": "Execution strategy -- either LLM-orchestrated or artifact-bundle backed." }, "external_databases": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedExternalDatabaseAttachment" }, "description": "Explicit existing SerenDB targets attached to this workload. Skill-declared\norganization and user databases do not require physical target configuration." }, "limits": { "$ref": "#/components/schemas/WorkloadLimits", "description": "Resource and iteration limits for the workload." }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy", "description": "Outbound network restrictions for sandboxed backends." } ] }, "publisher_only": { "type": "boolean", "description": "When true, the workload is exposed only through publisher-managed entry points." }, "requirements": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RequirementSpec" }, "description": "Declared requirements validated at deploy time." }, "secrets": { "description": "Secret references available to the runtime." }, "side_effect_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SideEffectPolicy", "description": "Controls for mutating built-in publisher calls." } ] } }, "additionalProperties": false }, "ActionLease": { "type": "object", "description": "Lease for a single action on a tool. Borrows the OpenFang/IronClaw\npattern: permission is granted per-action, not per-process, with optional\nexpiry, use budget, and a parent lease ref for sub-agent inheritance.\n\n`capability` distinguishes blanket grants (all sub-actions of `action`)\nfrom a closed `Specific` set. Sub-agents that fork from a parent must\nhold leases whose capability is a subset of the parent's — runtime\nenforcement (when implemented) lives outside this DTO; here we validate\nshape only.", "required": [ "action", "capability" ], "properties": { "action": { "type": "string", "description": "Action name being leased. Free-form per tool; e.g. `read`, `send`,\n`execute`, `delete`, `list`." }, "capability": { "$ref": "#/components/schemas/GrantedActions" }, "expiry": { "type": [ "string", "null" ], "description": "Lease expiry as RFC 3339; `None` means no time bound." }, "parent_lease_ref": { "type": [ "string", "null" ], "description": "Identifier of the parent lease this one inherits from. Shape-only\nvalidation here checks that the value is non-empty when set; the\nreferenced lease is not looked up. Inheritance resolution (parent must\nhold a capability superset) happens at runtime." }, "use_budget": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of invocations before the lease must be re-issued.\n`None` means unlimited.", "minimum": 0 } }, "additionalProperties": false }, "AgentAudioCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "speech_to_text": { "type": "boolean" }, "text_to_speech": { "type": "boolean" }, "tts_voice": { "type": [ "string", "null" ], "description": "Voice used by the text-to-speech tool when `text_to_speech` is enabled.\nDefaults to the runtime provider's standard voice when omitted." }, "voice_activity_detection": { "type": "boolean" } }, "additionalProperties": false }, "AgentBrowserCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/AgentBrowserProfile" } }, "additionalProperties": false }, "AgentBrowserProfile": { "type": "string", "enum": [ "minimal", "form_filling", "scraping", "full" ] }, "AgentBundlePatch": { "type": "object", "description": "Partial agent-bundle update for an existing managed deployment.", "properties": { "remove_assets": { "type": "array", "items": { "type": "string" }, "description": "Asset paths to remove before applying upserts." }, "remove_instructions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstructionFileSelector" }, "description": "Instruction files to remove before applying upserts." }, "upsert_assets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAssetFile" }, "description": "Asset files to insert or replace. Identity is `path`." }, "upsert_instructions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstructionFile" }, "description": "Instruction files to insert or replace. Identity is `(kind, path)`." } }, "additionalProperties": false }, "AgentCapabilitiesResponse": { "type": "object", "required": [ "publisher", "orchestration_plane", "runtime_provider", "supports_direct_skill_deploy", "supports_orchestrated_deploy", "deployment_targets", "deployment_runtime_api", "supported_templates", "supported_tool_presets", "supported_model_policies" ], "properties": { "deployment_runtime_api": { "type": "string" }, "deployment_targets": { "type": "array", "items": { "type": "string" } }, "orchestration_plane": { "type": "boolean" }, "publisher": { "type": "string" }, "runtime_provider": { "type": "string" }, "supported_model_policies": { "type": "array", "items": { "type": "string" } }, "supported_templates": { "type": "array", "items": { "type": "string" } }, "supported_tool_presets": { "type": "array", "items": { "type": "string" } }, "supports_direct_skill_deploy": { "type": "boolean" }, "supports_orchestrated_deploy": { "type": "boolean" } } }, "AgentCapabilityPolicy": { "type": "object", "description": "Optional runtime capabilities declared by a managed agent.\n\nThis is distinct from `tool_refs`: capability policy controls bundled\nruntime behavior such as tool-call error recovery and optional tool\nfamilies that require runtime prerequisites.", "properties": { "audio": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentAudioCapabilityPolicy" } ] }, "browser": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentBrowserCapabilityPolicy" } ] }, "code_execution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCodeExecutionCapabilityPolicy" } ] }, "eval_harness": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentSimpleCapabilityPolicy" } ] }, "realtime_sessions": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRealtimeSessionsCapabilityPolicy" } ] }, "skills": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentSkillsCapabilityPolicy" } ] }, "tool_error_recovery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentToolErrorRecoveryPolicy" } ] }, "workflows": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentSimpleCapabilityPolicy" } ] } }, "additionalProperties": false }, "AgentCodeExecutionCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "sandbox": { "$ref": "#/components/schemas/AgentCodeExecutionSandbox", "description": "Managed code execution requires a runtime image and host environment\nwith OS sandboxing support. Linux deployments use Bubblewrap and need\nunprivileged user namespaces enabled on the node." } }, "additionalProperties": false }, "AgentCodeExecutionSandbox": { "type": "string", "enum": [ "disabled", "managed", "external" ] }, "AgentCredentialBinding": { "type": "string", "enum": [ "env", "reference_env", "header", "body", "proxy_inject" ] }, "AgentCredentialKind": { "type": "string", "enum": [ "api_key", "oauth2_token", "basic", "mtls", "aws_sig_v4", "gcp_service_account" ] }, "AgentCredentialRef": { "type": "object", "description": "Reference to a credential held by Seren's control plane or by the\norganization credential-secret API, injected at the declared binding point.", "required": [ "name", "ref_uri", "kind", "binding" ], "properties": { "binding": { "$ref": "#/components/schemas/AgentCredentialBinding", "description": "How the credential is delivered. `proxy_inject` is declarative: the\ngateway resolves and injects the reference at egress rather than this\nprocess materializing plaintext." }, "binding_target": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/AgentCredentialKind" }, "name": { "type": "string", "description": "Name the workload uses to address the credential." }, "ref_uri": { "type": "string", "description": "URI of the credential record. Supported schemes:\n`control-plane://providers/{id}`, `org-secret://{key}`,\n`user-secret://{key}`, `seren-secrets://{vault}/{item}/{field}`.\nCreate `org-secret` and `user-secret` records with\n`/organizations/{organization_id}/agent-credential-secrets`." }, "rotation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCredentialRotationPolicy" } ] } }, "additionalProperties": false }, "AgentCredentialRotationPolicy": { "type": "object", "required": [ "allow_rotate" ], "properties": { "allow_rotate": { "type": "boolean" }, "max_age_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "AgentFilesystemEnforcement": { "type": "string", "enum": [ "best_effort", "hard_requirement" ] }, "AgentFilesystemPolicy": { "type": "object", "properties": { "enforcement": { "$ref": "#/components/schemas/AgentFilesystemEnforcement", "description": "How strictly the runtime should enforce these paths." }, "read_only_paths": { "type": "array", "items": { "type": "string" }, "description": "Absolute paths the workload may read but not write." }, "read_write_paths": { "type": "array", "items": { "type": "string" }, "description": "Absolute paths the workload may read and write." } }, "additionalProperties": false }, "AgentGraphMemoryPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "read_policy": { "$ref": "#/components/schemas/AgentGraphMemoryReadPolicy" }, "store": { "$ref": "#/components/schemas/AgentGraphMemoryStore" }, "write_policy": { "$ref": "#/components/schemas/AgentGraphMemoryWritePolicy" } }, "additionalProperties": false }, "AgentGraphMemoryReadPolicy": { "type": "string", "enum": [ "explicit_tool", "always_on" ] }, "AgentGraphMemoryStore": { "type": "string", "enum": [ "seren_managed", "external" ] }, "AgentGraphMemoryWritePolicy": { "type": "string", "enum": [ "explicit_tool", "on_observation", "none" ] }, "AgentGuardrailOnFail": { "type": "string", "enum": [ "retry", "block", "fix", "human" ] }, "AgentGuardrailPolicy": { "type": "object", "description": "Typed guardrail policy attached to a managed agent.", "required": [ "name", "target", "validator" ], "properties": { "description": { "type": [ "string", "null" ] }, "human_inbox": { "type": "boolean", "description": "When true, fail events route into the unified approval inbox for human review." }, "max_retries": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "name": { "type": "string", "description": "Unique within the deployment; used in `guardrail_pass`/`guardrail_fail`\nevents." }, "on_fail": { "$ref": "#/components/schemas/AgentGuardrailOnFail" }, "target": { "$ref": "#/components/schemas/AgentGuardrailTarget" }, "tool": { "type": [ "string", "null" ], "description": "Optional tool name; when present, the guardrail only fires on that tool." }, "validator": { "$ref": "#/components/schemas/AgentGuardrailValidator" } }, "additionalProperties": false }, "AgentGuardrailTarget": { "type": "string", "enum": [ "input", "output", "tool_input", "tool_output" ] }, "AgentGuardrailValidator": { "oneOf": [ { "type": "object", "required": [ "pattern", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "regex" ] }, "pattern": { "type": "string" } } }, { "type": "object", "required": [ "prompt", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "llm_judge" ] }, "model": { "type": [ "string", "null" ] }, "prompt": { "type": "string" } } }, { "type": "object", "required": [ "function_ref", "kind" ], "properties": { "function_ref": { "type": "string" }, "kind": { "type": "string", "enum": [ "custom_fn" ] } } } ] }, "AgentInstructionFileSelector": { "type": "object", "description": "Selects instruction files to remove from a managed deployment bundle.", "required": [ "kind" ], "properties": { "kind": { "$ref": "#/components/schemas/AgentInstructionKind" }, "path": { "type": [ "string", "null" ], "description": "Original or packaged path. When omitted, every instruction with this kind is selected." } }, "additionalProperties": false }, "AgentKnowledgeIndexPolicy": { "type": "string", "enum": [ "encrypted_scan", "plaintext_embeddings" ] }, "AgentKnowledgePolicy": { "type": "object", "required": [ "enabled" ], "properties": { "chunk_overlap": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "chunk_size": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "enabled": { "type": "boolean" }, "index_policy": { "$ref": "#/components/schemas/AgentKnowledgeIndexPolicy" }, "read_policy": { "$ref": "#/components/schemas/AgentKnowledgeReadPolicy" }, "source": { "$ref": "#/components/schemas/AgentKnowledgeSource" }, "store": { "$ref": "#/components/schemas/AgentKnowledgeStore" }, "top_k": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "AgentKnowledgeReadPolicy": { "type": "string", "enum": [ "explicit_tool", "none" ] }, "AgentKnowledgeSource": { "type": "string", "enum": [ "agent_instructions" ] }, "AgentKnowledgeStore": { "type": "string", "enum": [ "seren_managed", "external" ] }, "AgentMemoryCompactionPolicy": { "type": "object", "required": [ "token_threshold", "event_retention_count", "overlap_tokens" ], "properties": { "event_retention_count": { "type": "integer", "format": "int32", "minimum": 0 }, "overlap_tokens": { "type": "integer", "format": "int32", "minimum": 0 }, "summarizer_model": { "type": [ "string", "null" ] }, "token_threshold": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "AgentMemoryPolicy": { "type": "object", "description": "Typed memory policy declared by a managed agent.", "properties": { "compaction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMemoryCompactionPolicy", "description": "Optional context-window compaction policy." } ] }, "graph_memory": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentGraphMemoryPolicy", "description": "Structured graph memory policy." } ] }, "knowledge": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentKnowledgePolicy", "description": "Encrypted knowledge retrieval policy for agent-authored instructions." } ] }, "semantic_memory": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentSemanticMemoryPolicy", "description": "Semantic / long-term memory policy." } ] }, "transcript_retention_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional retention for raw run transcripts (days).", "minimum": 0 } }, "additionalProperties": false }, "AgentNetworkAccessPreset": { "type": "string", "enum": [ "read_only", "read_write", "full" ] }, "AgentNetworkDefault": { "type": "string", "enum": [ "deny", "allow" ] }, "AgentNetworkEgressRule": { "type": "object", "required": [ "host", "port", "protocol" ], "properties": { "access_preset": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentNetworkAccessPreset", "description": "Optional convenience preset that expands to a method set when set." } ] }, "binaries": { "type": "array", "items": { "type": "string" }, "description": "Optional per-binary glob list restricting which processes may use the rule." }, "enforcement": { "$ref": "#/components/schemas/AgentNetworkEnforcement", "description": "Whether matches enforce or just audit." }, "host": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" }, "description": "Optional HTTP methods this rule applies to (rest/sse protocols only)." }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Optional path globs this rule applies to (rest/sse protocols only)." }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "protocol": { "$ref": "#/components/schemas/AgentNetworkProtocol" } }, "additionalProperties": false }, "AgentNetworkEnforcement": { "type": "string", "enum": [ "enforce", "audit" ] }, "AgentNetworkPolicy": { "type": "object", "properties": { "blocked_request_inbox": { "type": "boolean", "description": "When true, blocked egress requests are queued for operator approval\n(shares an inbox with tool approvals)." }, "blocked_request_max_wait_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Wall-clock cap (in seconds) on how long the runtime will hold a\nsingle blocked-egress request waiting for an operator decision before\nsurfacing it as `Expired`. When `None`, the runtime applies its\nbuilt-in default (30 minutes).", "minimum": 0 }, "default": { "$ref": "#/components/schemas/AgentNetworkDefault", "description": "Default disposition when no rule matches a request." }, "egress_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AgentNetworkEgressRule" }, "description": "Ordered egress rules. The first matching rule decides the request." } }, "additionalProperties": false }, "AgentNetworkProtocol": { "type": "string", "enum": [ "tcp", "rest", "sse", "websocket" ] }, "AgentProcessPolicy": { "type": "object", "properties": { "capability_drop": { "type": "array", "items": { "type": "string" }, "description": "Linux capabilities to drop. Defaults to `[\"ALL\"]` at the controller." }, "no_new_privileges": { "type": "boolean" }, "run_as_user": { "type": [ "string", "null" ], "description": "Optional uid:gid pair (e.g. `1000:1000`) the workload runs under." }, "seccomp_profile": { "type": [ "string", "null" ], "description": "Seccomp profile name; defaults to the runtime default." } }, "additionalProperties": false }, "AgentRealtimeSessionsCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "input_transcription": { "type": "boolean" }, "model_id": { "type": [ "string", "null" ] }, "persist_transcripts": { "type": "boolean" }, "provider": { "$ref": "#/components/schemas/AgentRealtimeSessionsProvider" }, "store_to_memory": { "type": "boolean" }, "voice": { "type": [ "string", "null" ] }, "voice_activity_detection": { "type": "boolean" } }, "additionalProperties": false }, "AgentRealtimeSessionsProvider": { "type": "string", "enum": [ "open_ai" ] }, "AgentRemoteAgentAuth": { "type": "string", "enum": [ "none", "bearer", "mtls" ] }, "AgentRemoteAgentTransport": { "type": "string", "enum": [ "https", "sse", "websocket" ] }, "AgentRemoteHttpAuth": { "type": "string", "enum": [ "none", "bearer", "api_key", "basic", "mtls" ] }, "AgentRemoteHttpMethod": { "type": "string", "enum": [ "get", "post", "put", "patch", "delete" ] }, "AgentResourcePolicy": { "type": "object", "properties": { "cpu_limit": { "type": [ "string", "null" ] }, "cpu_request": { "type": [ "string", "null" ] }, "ephemeral_storage_limit": { "type": [ "string", "null" ] }, "max_artifact_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "max_output_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "max_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_calls": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "memory_limit": { "type": [ "string", "null" ] }, "memory_request": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "AgentRuntimeClass": { "type": "string", "enum": [ "default", "gvisor", "kata" ] }, "AgentRuntimePolicy": { "type": "object", "description": "Typed runtime policy that a managed agent declares as part of its `AgentSpec`.\n\nThe control plane validates this object on create/update; the runtime\ncontroller renders it into Kubernetes objects (security context, resource\nlimits, NetworkPolicy). Today the controller renders a subset; fields it\ndoes not yet honor remain part of the declared contract so revisions and\nrollbacks stay consistent.", "properties": { "filesystem": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentFilesystemPolicy" } ] }, "network": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentNetworkPolicy" } ] }, "process": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentProcessPolicy" } ] }, "resources": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentResourcePolicy" } ] }, "runtime_class": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimeClass", "description": "Optional sandbox runtime class (for example `gvisor` or `kata`).\nWhen omitted, the platform default applies." } ] } }, "additionalProperties": false }, "AgentSemanticMemoryPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "embedding_model_ref": { "type": [ "string", "null" ], "description": "Optional embedding model reference." }, "enabled": { "type": "boolean" }, "read_policy": { "$ref": "#/components/schemas/AgentSemanticMemoryReadPolicy" }, "retention_days": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "store": { "$ref": "#/components/schemas/AgentSemanticMemoryStore" }, "write_policy": { "$ref": "#/components/schemas/AgentSemanticMemoryWritePolicy" } }, "additionalProperties": false }, "AgentSemanticMemoryReadPolicy": { "type": "string", "enum": [ "explicit_tool", "always_on" ] }, "AgentSemanticMemoryStore": { "type": "string", "enum": [ "seren_managed", "external" ] }, "AgentSemanticMemoryWritePolicy": { "type": "string", "enum": [ "explicit_tool", "on_observation", "none" ] }, "AgentSimpleCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "AgentSkillSelectionMode": { "type": "string", "enum": [ "auto" ] }, "AgentSkillSelectionPolicy": { "type": "object", "properties": { "exclude_tags": { "type": "array", "items": { "type": "string" } }, "include_tags": { "type": "array", "items": { "type": "string" } }, "max_selected": { "type": "integer", "format": "int32", "minimum": 0 }, "mode": { "$ref": "#/components/schemas/AgentSkillSelectionMode" } }, "additionalProperties": false }, "AgentSkillsCapabilityPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "execute_scripts": { "type": "boolean", "description": "Allow the runtime to execute scripts attached to the agent bundle." }, "max_injected_chars": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "selection": { "$ref": "#/components/schemas/AgentSkillSelectionPolicy" } }, "additionalProperties": false }, "AgentSpec": { "type": "object", "description": "Managed deploy request for the `seren-agent` first-class publisher.", "required": [ "mode", "workload" ], "properties": { "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Seren Secrets agent identity this managed agent acts as when\nresolving `seren-secrets://` references." }, "agent_slug": { "type": [ "string", "null" ], "description": "Optional stable slug for the agent. If omitted, derived from `name`." }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy", "description": "Optional alert webhook policy." } ] }, "allowed_remote_agent_origins": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Optional allowlist for remote A2A delegation targets.\n\nEntries may be either hostnames (for example `agents.example.com`) or\nfull origins (for example `https://agents.example.com`)." }, "approval_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy", "description": "Safety policy for publisher operations. Defaults to `read_only`." } ] }, "capability_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCapabilityPolicy", "description": "Optional runtime capability policy." } ] }, "credentials": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentCredentialRef" }, "description": "Optional credential references resolved by the control plane at runtime.\nAccepts `seren-secrets://{vault_id}/{item_id}/{field}` for vault-held\ncredentials, `control-plane://providers/{id-or-slug}` for control-plane\nprovider credentials, and `org-secret://{key}` / `user-secret://{key}`\nfor reusable credential-secret records managed through\n`/organizations/{organization_id}/agent-credential-secrets`.\n`seren-secrets://` references additionally require\n`secret_resolution_delegation`, which is signed client-side in the\nEmployees UI and cannot be produced by an API key." }, "cron_schedule": { "type": [ "string", "null" ], "description": "Cron schedule expression, required when `mode` is `cron`." }, "cron_timezone": { "type": [ "string", "null" ], "description": "Timezone for cron schedules. Defaults to `UTC` when omitted." }, "dashboard_config": { "description": "Optional dashboard rendering config." }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Optional eval gate that must pass before runs proceed." } ] }, "guardrails": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentGuardrailPolicy" }, "description": "Optional guardrail policies applied at input/output/tool boundaries." }, "memory_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMemoryPolicy", "description": "Optional memory policy (semantic memory, transcripts, compaction)." } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode", "description": "Deployment mode." }, "model_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentModelPolicy", "description": "Runtime/model execution profile. Defaults to `balanced`." } ] }, "name": { "type": [ "string", "null" ], "description": "Human-readable agent name. Auto-generated when omitted." }, "private_output_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy", "description": "Output persistence policy for model/tool traces." } ] }, "runtime_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimePolicy", "description": "Optional typed runtime policy (filesystem, network, process, resources).\nToday the controller renders the network section as a NetworkPolicy and\nthe resources section as Pod resources; other sections are reserved." } ] }, "secret_resolution_delegation": { "type": [ "string", "null" ], "description": "User-authorized Seren Secrets delegation used by the runtime to renew\ndeployment-scoped secret grants." }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase", "description": "Optional external session database configuration for durable agent state." } ] }, "template": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentTemplate", "description": "Opinionated managed template. Defaults to `research_monitor`." } ] }, "tool_presets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Managed tool preset configuration. Defaults to `live_data`. Presets are\ncompact config inputs, not resolved display groups." }, "tool_refs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentToolRef" }, "description": "Optional typed tool references. Coexists with `tool_presets` so the\nruntime can resolve from typed refs and preset configuration together." }, "visibility": { "type": [ "string", "null" ], "description": "Visibility mode (`open` or `opaque`)." }, "workload": { "$ref": "#/components/schemas/WorkloadSpec", "description": "Runtime workload specification (execution strategy, compute, limits, ...)." } }, "additionalProperties": false }, "AgentSpecUpdate": { "type": "object", "description": "Partial update request for an existing managed `seren-agent` deployment.\n\nMirrors the agent-level fields of `AgentSpec` as `Option<...>` for partial\nupdate. `workload_limits` patches only run limits while preserving the\nauthoritative server-side workload, including encrypted secrets. The\n`workload` field remains a full replacement for callers changing other\nworkload fields.", "properties": { "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Updated Seren Secrets agent identity this managed agent acts as." }, "agent_slug": { "type": [ "string", "null" ], "description": "Updated stable slug for the agent." }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy", "description": "Updated alert webhook policy." } ] }, "allowed_remote_agent_origins": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Updated allowlist for remote A2A delegation targets." }, "approval_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy", "description": "Updated approval policy." } ] }, "capability_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCapabilityPolicy", "description": "Updated capability policy. Replaces the entire previous policy when present." } ] }, "clear_alert_policy": { "type": "boolean", "description": "Clear any existing alert policy." }, "clear_capability_policy": { "type": "boolean", "description": "Clear any existing capability policy." }, "clear_credentials": { "type": "boolean", "description": "Clear any existing credential references." }, "clear_dashboard_config": { "type": "boolean", "description": "Clear any existing dashboard config." }, "clear_eval_gate": { "type": "boolean", "description": "Clear any existing eval gate configuration." }, "clear_guardrails": { "type": "boolean", "description": "Clear any existing guardrail list." }, "clear_memory_policy": { "type": "boolean", "description": "Clear any existing memory policy." }, "clear_runtime_policy": { "type": "boolean", "description": "Clear any existing runtime policy." }, "clear_secret_resolution_delegation": { "type": "boolean", "description": "Clear any existing Seren Secrets delegation." }, "clear_session_database": { "type": "boolean", "description": "Clear any existing external session database configuration." }, "clear_tool_refs": { "type": "boolean", "description": "Clear any existing typed tool refs and omit `tool_refs` from the\nresolved runtime config. Cannot be combined with `tool_refs`." }, "credentials": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentCredentialRef" }, "description": "Updated credential references. Replaces the entire previous list when\npresent. Accepts `seren-secrets://{vault_id}/{item_id}/{field}`,\n`control-plane://providers/{id-or-slug}`, `org-secret://{key}`, and\n`user-secret://{key}`. `seren-secrets://` references require a client-signed\n`secret_resolution_delegation` created in the Employees UI." }, "cron_schedule": { "type": [ "string", "null" ], "description": "Updated cron schedule. Only valid for cron deployments." }, "cron_timezone": { "type": [ "string", "null" ], "description": "Updated cron timezone. Only valid for cron deployments." }, "dashboard_config": { "description": "Updated dashboard rendering config." }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Updated eval gate configuration." } ] }, "guardrails": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentGuardrailPolicy" }, "description": "Updated guardrail list. Replaces the entire previous list when present." }, "memory_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMemoryPolicy", "description": "Updated memory policy. Replaces the entire previous policy when present." } ] }, "model_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentModelPolicy", "description": "Updated model/runtime profile." } ] }, "name": { "type": [ "string", "null" ], "description": "Updated human-readable agent name." }, "private_output_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy", "description": "Updated output persistence policy for model/tool traces." } ] }, "runtime_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimePolicy", "description": "Updated runtime policy. Replaces the entire previous policy when present." } ] }, "secret_resolution_delegation": { "type": [ "string", "null" ], "description": "Updated user-authorized Seren Secrets delegation." }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase", "description": "Updated external session database configuration." } ] }, "template": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentTemplate", "description": "Updated managed template." } ] }, "tool_presets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Updated managed tool preset configuration. Presets are compact config\ninputs, not resolved display groups." }, "tool_refs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentToolRef" }, "description": "Updated typed tool refs. Replaces the entire previous list when present.\n\nAn empty list is an explicit empty replacement and will serialize as\n`tool_refs: []` in runtime config. Use `clear_tool_refs` when the\ncaller wants to remove the stored typed-tool field entirely." }, "visibility": { "type": [ "string", "null" ], "description": "Updated visibility mode (`open` or `opaque`)." }, "workload": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkloadSpec", "description": "Replaces the entire workload when present. Use the managed files endpoint\nfor targeted bundle file changes." } ] }, "workload_limits": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkloadLimitsPatch", "description": "Partially update workload limits without replacing or round-tripping\nthe full workload. Cannot be combined with `workload`." } ] } }, "additionalProperties": false }, "AgentToolErrorRecoveryBackoffKind": { "type": "string", "enum": [ "none", "fixed", "exponential" ] }, "AgentToolErrorRecoveryBackoffPolicy": { "type": "object", "properties": { "base_delay_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "kind": { "$ref": "#/components/schemas/AgentToolErrorRecoveryBackoffKind" }, "max_delay_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "AgentToolErrorRecoveryPolicy": { "type": "object", "required": [ "enabled" ], "properties": { "allow_tools": { "type": "array", "items": { "type": "string" } }, "backoff": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentToolErrorRecoveryBackoffPolicy" } ] }, "deny_tools": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "global_limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_attempts": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "AgentToolRef": { "oneOf": [ { "type": "object", "description": "Reference to a first-class publisher operation.", "required": [ "publisher_slug", "operation_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "publisher" ] }, "oauth_connection_id": { "type": [ "string", "null" ], "format": "uuid", "description": "OAuth connection fixed to this publisher for the deployment." }, "operation_id": { "type": "string" }, "permitted_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionLease" } }, "publisher_slug": { "type": "string" }, "require_approval": { "type": "boolean" } } }, { "type": "object", "description": "Reference to a tool exposed by an MCP server registered with Seren.", "required": [ "server_ref", "tool_name", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "mcp" ] }, "permitted_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionLease" } }, "require_approval": { "type": "boolean" }, "server_ref": { "type": "string" }, "tool_name": { "type": "string" } } }, { "type": "object", "description": "Reference to a capability on an organization connector (Gmail, Slack, ...).\n\n`capability == \"messaging\"` is the generic convention for connectors\nthat adapt user conversations through a channel such as Telegram, Slack,\nSMS, Discord, email, or a publisher-provided messaging surface. Seren\ndoes not route channel traffic from this field. The `connector_ref`\nidentifies the concrete integration, and `scopes` stays\nprovider-defined so connector manifests and publisher ecosystems can\nevolve without a Seren API enum update.", "required": [ "connector_ref", "capability", "kind" ], "properties": { "capability": { "type": "string" }, "connector_ref": { "type": "string" }, "kind": { "type": "string", "enum": [ "connector" ] }, "permitted_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionLease" } }, "require_approval": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "description": "Reference to a remote agent reachable via A2A.", "required": [ "origin", "transport", "auth_mode", "kind" ], "properties": { "auth_mode": { "$ref": "#/components/schemas/AgentRemoteAgentAuth" }, "expected_card_digest": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "remote_agent" ] }, "origin": { "type": "string" }, "permitted_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionLease" } }, "require_approval": { "type": "boolean" }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "transport": { "$ref": "#/components/schemas/AgentRemoteAgentTransport" } } }, { "type": "object", "description": "Reference to a remote HTTP endpoint exposed as a managed tool.", "required": [ "name", "endpoint", "method", "auth_mode", "kind" ], "properties": { "auth_mode": { "$ref": "#/components/schemas/AgentRemoteHttpAuth" }, "endpoint": { "type": "string" }, "kind": { "type": "string", "enum": [ "remote_http" ] }, "method": { "$ref": "#/components/schemas/AgentRemoteHttpMethod" }, "name": { "type": "string" }, "permitted_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionLease" } }, "require_approval": { "type": "boolean" }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, { "type": "object", "description": "Back-compat shim for the coarse `tool_presets` collections. Presets\nare bulk grants and intentionally do not carry action leases.", "required": [ "preset", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "preset_group" ] }, "preset": { "$ref": "#/components/schemas/ManagedAgentToolPreset" } } } ], "description": "Typed tool reference attached to an agent. Lives alongside the coarser\n`tool_presets` field; future managed-agent flows resolve from typed refs and\npresets together. Each non-preset variant carries an optional\n`permitted_actions` collection of `ActionLease`s — the per-action gate\nborrowed from OpenFang/IronClaw that lets the spec say \"this Connector may\nperform `read` but not `send`\" without inventing a separate ACL surface." }, "DataResponse_AgentCapabilitiesResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "publisher", "orchestration_plane", "runtime_provider", "supports_direct_skill_deploy", "supports_orchestrated_deploy", "deployment_targets", "deployment_runtime_api", "supported_templates", "supported_tool_presets", "supported_model_policies" ], "properties": { "deployment_runtime_api": { "type": "string" }, "deployment_targets": { "type": "array", "items": { "type": "string" } }, "orchestration_plane": { "type": "boolean" }, "publisher": { "type": "string" }, "runtime_provider": { "type": "string" }, "supported_model_policies": { "type": "array", "items": { "type": "string" } }, "supported_templates": { "type": "array", "items": { "type": "string" } }, "supported_tool_presets": { "type": "array", "items": { "type": "string" } }, "supports_direct_skill_deploy": { "type": "boolean" }, "supports_orchestrated_deploy": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentActivityReport": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "deployment_id", "generated_at", "deployment", "summary", "runs" ], "properties": { "deployment": { "$ref": "#/components/schemas/ManagedAgentActivityDeploymentSummary" }, "deployment_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRunActivity" } }, "summary": { "$ref": "#/components/schemas/ManagedAgentActivitySummary" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentDetail": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "name", "agent_slug", "mode", "compute_backend", "runtime_kind", "status", "bundle", "model_id", "model_config", "template", "tool_presets", "allowed_publisher_operations", "resolved_tools", "approval_policy", "model_policy", "runtime_adapter", "private_output_policy", "secret_keys", "requirements", "visibility", "routing_reason" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current managed-agent revision for this deployment." }, "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Seren Secrets agent identity this managed agent acts as when\nresolving `seren-secrets://` references." }, "agent_slug": { "type": "string" }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy" } ] }, "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "allowed_remote_agent_origins": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "bundle": { "$ref": "#/components/schemas/AgentBundle" }, "capability_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCapabilityPolicy", "description": "Optional runtime capability policy." } ] }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedDeploymentCondition" }, "description": "Structured status conditions for the managed deployment. Today this is\nsynthesized from the flat lifecycle `status` and the last persisted\n`error_message`; future work will let the runtime controller report\nconditions directly." }, "config": {}, "connector_webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConnectorWebhookRoute" }, "description": "Public provider webhook routes for connector-backed messaging channels." }, "context_budget_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCredentialRef" }, "description": "Credential references attached to this deployment, when any. Reusable\n`org-secret://` and `user-secret://` records are managed through the\norganization credential-secret API." }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "dashboard_config": {}, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Eval gate that must pass with a fresh verdict before runs proceed.\n`set_id` and `max_age_seconds` always travel together; either both are\nset or the gate is absent." } ] }, "external_databases": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedExternalDatabaseAttachment" } }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "$ref": "#/components/schemas/AgentGuardrailPolicy" }, "description": "Guardrails attached to this deployment, when any." }, "llm_connection": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentLlmConnection" } ] }, "max_iterations": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_timeout_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_calls_per_run": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_output_chars": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "memory_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMemoryPolicy", "description": "Memory policy declared by the deployment, when set." } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_config": {}, "model_id": { "type": "string" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "name": { "type": "string" }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy" } ] }, "private_output_policy": { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/RequirementSpec" } }, "resolved_tools": { "type": "array", "items": { "type": "string" } }, "routing_reason": { "type": "string" }, "runtime_adapter": { "$ref": "#/components/schemas/ManagedAgentRuntimeAdapter" }, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "runtime_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimePolicy", "description": "Typed runtime policy (filesystem/network/process/resources), when set." } ] }, "secret_keys": { "type": "array", "items": { "type": "string" } }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase" } ] }, "side_effect_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SideEffectPolicy" } ] }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Preset configuration enabled on the deployment. Presets are compact\nconfig inputs; use the tool-groups endpoint for the resolved display\nmodel with labels, descriptions, and tool membership." }, "tool_refs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentToolRef" }, "description": "Typed tool refs declared on the deployment, when any." }, "visibility": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentHealthReport": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "generated_at", "status", "summary", "deployment", "findings" ], "properties": { "deployment": { "$ref": "#/components/schemas/ManagedAgentDeploymentHealth" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentHealthFinding" } }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ManagedAgentHealthStatus" }, "summary": { "$ref": "#/components/schemas/ManagedAgentHealthSummary" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentResources": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "deployment_id", "generated_at", "deployment", "runtime", "connectors", "schedule", "tools", "memory", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ManagedAgentCapabilityResources" }, "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConnectorResource" } }, "deployment": { "$ref": "#/components/schemas/ManagedAgentDeploymentResourceSummary" }, "deployment_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "memory": { "$ref": "#/components/schemas/ManagedAgentMemoryResources" }, "organization_id": { "type": "string", "format": "uuid" }, "runtime": { "$ref": "#/components/schemas/ManagedAgentRuntimeResources" }, "schedule": { "$ref": "#/components/schemas/ManagedAgentScheduleResources" }, "tools": { "$ref": "#/components/schemas/ManagedAgentToolResources" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentRollbackPreview": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "target_revision", "current", "proposed", "changed_fields" ], "properties": { "changed_fields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentFieldChange" } }, "current": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus", "description": "Current eval gate status; when `block_on_failure` is set on the\nproposed gate and `blocking` is true here, applying this rollback will\nbe rejected by the control plane." } ] }, "proposed": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "target_revision": { "$ref": "#/components/schemas/ManagedAgentDeploymentRevisionSummary" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentDeploymentUpdatePreview": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "current", "proposed", "changed_fields" ], "properties": { "changed_fields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentFieldChange" } }, "current": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus", "description": "Current eval gate status for the proposed gate. When the proposed gate\nsets `block_on_failure` and `blocking` is true here, the apply will be\nrejected by the control plane." } ] }, "proposed": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentHealthReport": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "generated_at", "status", "summary", "deployments", "findings" ], "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentDeploymentHealth" } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentHealthFinding" } }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ManagedAgentHealthStatus" }, "summary": { "$ref": "#/components/schemas/ManagedAgentHealthSummary" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentRuntimePolicyReconciliationPreview": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Preview for safely reconciling a deployment created before runtime-policy\ndeadline resolution became canonical.", "required": [ "deployment_id", "status", "reason", "apply_authorized", "required_api_key_scope" ], "properties": { "apply_authorized": { "type": "boolean" }, "current_effective_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "declared_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "deployment_id": { "type": "string", "format": "uuid" }, "proposed_effective_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "reason": { "type": "string" }, "required_api_key_scope": { "type": "string" }, "status": { "$ref": "#/components/schemas/ManagedAgentRuntimePolicyReconciliationStatus" }, "update_preview": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentDeploymentUpdatePreview" } ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentRuntimePolicyReconciliationResult": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "applied", "preview" ], "properties": { "applied": { "type": "boolean" }, "preview": { "$ref": "#/components/schemas/ManagedAgentRuntimePolicyReconciliationPreview" }, "revision_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentToolCatalogEntry": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "description", "source", "approval_type", "approval_rule_count", "effective_policy", "side_effecting", "checkpoint_required" ], "properties": { "approval_reason": { "type": [ "string", "null" ] }, "approval_rule_count": { "type": "integer", "format": "int32", "minimum": 0 }, "approval_type": { "$ref": "#/components/schemas/ToolApprovalType" }, "checkpoint_required": { "type": "boolean", "description": "Whether this tool is included in the durable tool-call checkpoint used\nfor conservative resume. Today this mirrors `side_effecting`; it is\nseparate so future deployment policy can narrow checkpointing without\nchanging the response shape." }, "data_labels": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "effective_policy": { "$ref": "#/components/schemas/ManagedAgentToolEffectivePolicy" }, "input_schema": {}, "name": { "type": "string" }, "preset": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentToolPreset" } ] }, "side_effecting": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/ManagedAgentToolSource" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentToolCatalogResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "tool_presets", "allowed_publisher_operations", "approval_policy", "tools" ], "properties": { "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "deployment_id": { "type": "string", "format": "uuid" }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Preset configuration enabled on the deployment. The catalog expands\nthese presets into concrete tool descriptors." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolCatalogEntry" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_ManagedAgentToolGroupResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deployment_id", "implicit", "tool_groups" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "implicit": { "type": "boolean", "description": "True when the response is derived from preset configuration instead of\nexplicit persisted tool-group assignments." }, "tool_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolGroupEntry" }, "description": "Resolved display/read model for the deployment's named tool groups.\nToday these are derived from `tool_presets`; future custom groups use\nthe same shape with `preset` omitted." } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PrivateModelCatalogResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "default_model_id", "models", "supports_custom_model_id", "catalog_source" ], "properties": { "catalog_source": { "$ref": "#/components/schemas/PrivateModelCatalogSource" }, "default_model_id": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateModelCatalogEntry" } }, "notice": { "type": [ "string", "null" ] }, "supports_custom_model_id": { "type": "boolean" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_TestSerenAgentDraftRunResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "runtime_adapter", "usage", "iterations", "tool_calls", "output_events" ], "properties": { "error": { "type": [ "string", "null" ] }, "error_info": {}, "iterations": { "type": "integer", "format": "int32", "minimum": 0 }, "output_events": { "type": "array", "items": {} }, "partial_response": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "runtime_adapter": { "type": "string" }, "status": { "$ref": "#/components/schemas/ManagedAgentDraftTestRunStatus" }, "tool_calls": { "type": "array", "items": {} }, "usage": {}, "warnings": { "type": "array", "items": { "type": "string" } }, "workflow": {} } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_Vec_ManagedAgentDeploymentRevisionSummary": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "revision_id", "deployment_id", "version", "change_kind", "created_by_user_id", "name", "agent_slug", "model_id", "template", "approval_policy", "model_policy", "changed_fields", "change_summary", "created_at" ], "properties": { "agent_slug": { "type": "string" }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "change_kind": { "$ref": "#/components/schemas/ManagedAgentRevisionChangeKind" }, "change_summary": { "type": "array", "items": { "type": "string" } }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "model_id": { "type": "string" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "name": { "type": "string" }, "restored_from_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "revision_id": { "type": "string", "format": "uuid" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "version": { "type": "integer", "format": "int32" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "GrantedActions": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "all" ] } } }, { "type": "object", "required": [ "actions", "kind" ], "properties": { "actions": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "specific" ] } } } ], "description": "Capability granted by an `ActionLease`. `All` grants every sub-action of\nthe named action; `Specific` enumerates a closed set." }, "ManagedAgentActivityDeploymentSummary": { "type": "object", "required": [ "name", "agent_slug", "status", "mode", "compute_backend", "runtime_kind" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_slug": { "type": "string" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "name": { "type": "string" }, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" } } }, "ManagedAgentActivitySummary": { "type": "object", "required": [ "total_run_count", "completed_run_count", "failed_run_count", "running_run_count", "awaiting_approval_run_count", "cancelled_run_count", "blocked_run_count", "artifact_count", "inference_input_tokens", "inference_output_tokens", "compute_cost_usd", "inference_cost_usd" ], "properties": { "artifact_count": { "type": "integer", "format": "int64" }, "awaiting_approval_run_count": { "type": "integer", "format": "int64" }, "blocked_run_count": { "type": "integer", "format": "int64" }, "cancelled_run_count": { "type": "integer", "format": "int64" }, "completed_run_count": { "type": "integer", "format": "int64" }, "compute_cost_usd": { "type": "string" }, "failed_run_count": { "type": "integer", "format": "int64" }, "inference_cost_usd": { "type": "string" }, "inference_input_tokens": { "type": "integer", "format": "int64" }, "inference_output_tokens": { "type": "integer", "format": "int64" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "running_run_count": { "type": "integer", "format": "int64" }, "total_run_count": { "type": "integer", "format": "int64" } } }, "ManagedAgentCapabilityResources": { "type": "object", "required": [ "policy_configured", "skills_enabled", "browser_enabled", "audio_enabled", "realtime_sessions_enabled", "code_execution_enabled", "workflows_enabled", "eval_harness_enabled", "tool_error_recovery_enabled" ], "properties": { "audio_enabled": { "type": "boolean" }, "browser_enabled": { "type": "boolean" }, "code_execution_enabled": { "type": "boolean" }, "eval_harness_enabled": { "type": "boolean" }, "policy_configured": { "type": "boolean" }, "realtime_sessions_enabled": { "type": "boolean" }, "skills_enabled": { "type": "boolean" }, "tool_error_recovery_enabled": { "type": "boolean" }, "workflows_enabled": { "type": "boolean" } } }, "ManagedAgentConnectorResource": { "type": "object", "required": [ "connector_ref", "connection_name", "webhook_routes" ], "properties": { "connection_name": { "type": "string" }, "connector_ref": { "type": "string" }, "webhook_routes": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConnectorWebhookResource" } } } }, "ManagedAgentConnectorWebhookResource": { "type": "object", "required": [ "route_id", "url" ], "properties": { "route_id": { "type": "string" }, "seren_verification_header_name": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "ManagedAgentConnectorWebhookRoute": { "type": "object", "required": [ "connector_ref", "connection_name", "route_id", "url" ], "properties": { "connection_name": { "type": "string" }, "connector_ref": { "type": "string" }, "route_id": { "type": "string" }, "url": { "type": "string" }, "verification_header_name": { "type": [ "string", "null" ] }, "verification_token": { "type": [ "string", "null" ] } } }, "ManagedAgentDeploymentActivityReport": { "type": "object", "required": [ "organization_id", "deployment_id", "generated_at", "deployment", "summary", "runs" ], "properties": { "deployment": { "$ref": "#/components/schemas/ManagedAgentActivityDeploymentSummary" }, "deployment_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRunActivity" } }, "summary": { "$ref": "#/components/schemas/ManagedAgentActivitySummary" } } }, "ManagedAgentDeploymentDetail": { "type": "object", "required": [ "deployment_id", "name", "agent_slug", "mode", "compute_backend", "runtime_kind", "status", "bundle", "model_id", "model_config", "template", "tool_presets", "allowed_publisher_operations", "resolved_tools", "approval_policy", "model_policy", "runtime_adapter", "private_output_policy", "secret_keys", "requirements", "visibility", "routing_reason" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Current managed-agent revision for this deployment." }, "agent_identity_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Seren Secrets agent identity this managed agent acts as when\nresolving `seren-secrets://` references." }, "agent_slug": { "type": "string" }, "alert_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentAlertPolicy" } ] }, "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "allowed_remote_agent_origins": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "bundle": { "$ref": "#/components/schemas/AgentBundle" }, "capability_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentCapabilityPolicy", "description": "Optional runtime capability policy." } ] }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedDeploymentCondition" }, "description": "Structured status conditions for the managed deployment. Today this is\nsynthesized from the flat lifecycle `status` and the last persisted\n`error_message`; future work will let the runtime controller report\nconditions directly." }, "config": {}, "connector_webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConnectorWebhookRoute" }, "description": "Public provider webhook routes for connector-backed messaging channels." }, "context_budget_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCredentialRef" }, "description": "Credential references attached to this deployment, when any. Reusable\n`org-secret://` and `user-secret://` records are managed through the\norganization credential-secret API." }, "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "dashboard_config": {}, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvalGate", "description": "Eval gate that must pass with a fresh verdict before runs proceed.\n`set_id` and `max_age_seconds` always travel together; either both are\nset or the gate is absent." } ] }, "external_databases": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedExternalDatabaseAttachment" } }, "fallback_models": { "type": [ "array", "null" ], "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "$ref": "#/components/schemas/AgentGuardrailPolicy" }, "description": "Guardrails attached to this deployment, when any." }, "llm_connection": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentLlmConnection" } ] }, "max_iterations": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_timeout_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_calls_per_run": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_output_chars": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "memory_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMemoryPolicy", "description": "Memory policy declared by the deployment, when set." } ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_config": {}, "model_id": { "type": "string" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "name": { "type": "string" }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentNetworkPolicy" } ] }, "private_output_policy": { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/RequirementSpec" } }, "resolved_tools": { "type": "array", "items": { "type": "string" } }, "routing_reason": { "type": "string" }, "runtime_adapter": { "$ref": "#/components/schemas/ManagedAgentRuntimeAdapter" }, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "runtime_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimePolicy", "description": "Typed runtime policy (filesystem/network/process/resources), when set." } ] }, "secret_keys": { "type": "array", "items": { "type": "string" } }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabase" } ] }, "side_effect_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SideEffectPolicy" } ] }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Preset configuration enabled on the deployment. Presets are compact\nconfig inputs; use the tool-groups endpoint for the resolved display\nmodel with labels, descriptions, and tool membership." }, "tool_refs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentToolRef" }, "description": "Typed tool refs declared on the deployment, when any." }, "visibility": { "type": "string" } } }, "ManagedAgentDeploymentHealth": { "type": "object", "required": [ "deployment_id", "name", "agent_slug", "status", "mode", "compute_backend", "runtime_kind", "created_at", "updated_at" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_slug": { "type": "string" }, "approval_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" } ] }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "created_at": { "type": "string", "format": "date-time" }, "deployment_id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_id": { "type": [ "string", "null" ] }, "model_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentModelPolicy" } ] }, "name": { "type": "string" }, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "template": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentTemplate" } ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "ManagedAgentDeploymentHealthReport": { "type": "object", "required": [ "organization_id", "generated_at", "status", "summary", "deployment", "findings" ], "properties": { "deployment": { "$ref": "#/components/schemas/ManagedAgentDeploymentHealth" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentHealthFinding" } }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ManagedAgentHealthStatus" }, "summary": { "$ref": "#/components/schemas/ManagedAgentHealthSummary" } } }, "ManagedAgentDeploymentResourceSummary": { "type": "object", "required": [ "name", "agent_slug", "status", "mode", "visibility", "template", "approval_policy", "model_policy" ], "properties": { "active_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_slug": { "type": "string" }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/CloudDeploymentStatus" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "visibility": { "type": "string" } } }, "ManagedAgentDeploymentResources": { "type": "object", "required": [ "organization_id", "deployment_id", "generated_at", "deployment", "runtime", "connectors", "schedule", "tools", "memory", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ManagedAgentCapabilityResources" }, "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConnectorResource" } }, "deployment": { "$ref": "#/components/schemas/ManagedAgentDeploymentResourceSummary" }, "deployment_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "memory": { "$ref": "#/components/schemas/ManagedAgentMemoryResources" }, "organization_id": { "type": "string", "format": "uuid" }, "runtime": { "$ref": "#/components/schemas/ManagedAgentRuntimeResources" }, "schedule": { "$ref": "#/components/schemas/ManagedAgentScheduleResources" }, "tools": { "$ref": "#/components/schemas/ManagedAgentToolResources" } } }, "ManagedAgentDeploymentRevisionSummary": { "type": "object", "required": [ "revision_id", "deployment_id", "version", "change_kind", "created_by_user_id", "name", "agent_slug", "model_id", "template", "approval_policy", "model_policy", "changed_fields", "change_summary", "created_at" ], "properties": { "agent_slug": { "type": "string" }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "change_kind": { "$ref": "#/components/schemas/ManagedAgentRevisionChangeKind" }, "change_summary": { "type": "array", "items": { "type": "string" } }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "model_id": { "type": "string" }, "model_policy": { "$ref": "#/components/schemas/ManagedAgentModelPolicy" }, "name": { "type": "string" }, "restored_from_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "revision_id": { "type": "string", "format": "uuid" }, "template": { "$ref": "#/components/schemas/ManagedAgentTemplate" }, "version": { "type": "integer", "format": "int32" } } }, "ManagedAgentDeploymentRollbackPreview": { "type": "object", "required": [ "deployment_id", "target_revision", "current", "proposed", "changed_fields" ], "properties": { "changed_fields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentFieldChange" } }, "current": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus", "description": "Current eval gate status; when `block_on_failure` is set on the\nproposed gate and `blocking` is true here, applying this rollback will\nbe rejected by the control plane." } ] }, "proposed": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "target_revision": { "$ref": "#/components/schemas/ManagedAgentDeploymentRevisionSummary" } } }, "ManagedAgentDeploymentUpdatePreview": { "type": "object", "required": [ "deployment_id", "current", "proposed", "changed_fields" ], "properties": { "changed_fields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentFieldChange" } }, "current": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" }, "deployment_id": { "type": "string", "format": "uuid" }, "eval_gate_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudDeploymentEvalGateStatus", "description": "Current eval gate status for the proposed gate. When the proposed gate\nsets `block_on_failure` and `blocking` is true here, the apply will be\nrejected by the control plane." } ] }, "proposed": { "$ref": "#/components/schemas/ManagedAgentDeploymentDetail" } } }, "ManagedAgentDraftTestRunStatus": { "type": "string", "enum": [ "completed", "awaiting_approval", "failed" ] }, "ManagedAgentFieldChange": { "type": "object", "required": [ "field", "label", "current_value", "proposed_value" ], "properties": { "current_value": {}, "field": { "type": "string" }, "label": { "type": "string" }, "proposed_value": {} } }, "ManagedAgentHealthFinding": { "type": "object", "required": [ "id", "severity", "category", "title", "detail", "recommendation", "source" ], "properties": { "category": { "type": "string" }, "detail": { "type": "string" }, "id": { "type": "string" }, "recommendation": { "type": "string" }, "severity": { "$ref": "#/components/schemas/ManagedAgentHealthSeverity" }, "source": { "type": "string" }, "title": { "type": "string" } } }, "ManagedAgentHealthReport": { "type": "object", "required": [ "organization_id", "generated_at", "status", "summary", "deployments", "findings" ], "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentDeploymentHealth" } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentHealthFinding" } }, "generated_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ManagedAgentHealthStatus" }, "summary": { "$ref": "#/components/schemas/ManagedAgentHealthSummary" } } }, "ManagedAgentHealthSeverity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "ManagedAgentHealthStatus": { "type": "string", "enum": [ "ok", "attention", "critical" ] }, "ManagedAgentHealthSummary": { "type": "object", "required": [ "critical_count", "warning_count", "info_count", "deployment_count", "running_deployment_count", "failed_deployment_count", "stopped_deployment_count", "pending_deployment_count", "building_deployment_count" ], "properties": { "building_deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "critical_count": { "type": "integer", "format": "int64", "minimum": 0 }, "deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "failed_deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "info_count": { "type": "integer", "format": "int64", "minimum": 0 }, "pending_deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "running_deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "stopped_deployment_count": { "type": "integer", "format": "int64", "minimum": 0 }, "warning_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ManagedAgentMemoryResources": { "type": "object", "required": [ "policy_configured", "semantic_memory_enabled", "graph_memory_enabled", "knowledge_enabled", "compaction_configured" ], "properties": { "compaction_configured": { "type": "boolean" }, "graph_memory_enabled": { "type": "boolean" }, "knowledge_enabled": { "type": "boolean" }, "policy_configured": { "type": "boolean" }, "semantic_memory_enabled": { "type": "boolean" }, "transcript_retention_days": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "ManagedAgentRevisionChangeKind": { "type": "string", "enum": [ "create", "update", "rollback" ] }, "ManagedAgentRunActivity": { "type": "object", "required": [ "run_id", "execution_id", "source", "status", "compute_backend", "execution_time_ms", "billed_duration_ms", "inference_input_tokens", "inference_output_tokens", "compute_cost_usd", "inference_cost_usd", "artifact_count", "started_at", "updated_at" ], "properties": { "artifact_count": { "type": "integer", "format": "int64" }, "billed_duration_ms": { "type": "integer", "format": "int32" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "compute_cost_usd": { "type": "string" }, "execution_id": { "type": "string" }, "execution_time_ms": { "type": "integer", "format": "int32" }, "inference_cost_usd": { "type": "string" }, "inference_input_tokens": { "type": "integer", "format": "int64" }, "inference_output_tokens": { "type": "integer", "format": "int64" }, "run_id": { "type": "string", "format": "uuid" }, "run_name": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "stop_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "ManagedAgentRuntimePolicyReconciliationPreview": { "type": "object", "description": "Preview for safely reconciling a deployment created before runtime-policy\ndeadline resolution became canonical.", "required": [ "deployment_id", "status", "reason", "apply_authorized", "required_api_key_scope" ], "properties": { "apply_authorized": { "type": "boolean" }, "current_effective_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "declared_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "deployment_id": { "type": "string", "format": "uuid" }, "proposed_effective_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "reason": { "type": "string" }, "required_api_key_scope": { "type": "string" }, "status": { "$ref": "#/components/schemas/ManagedAgentRuntimePolicyReconciliationStatus" }, "update_preview": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentDeploymentUpdatePreview" } ] } } }, "ManagedAgentRuntimePolicyReconciliationResult": { "type": "object", "required": [ "applied", "preview" ], "properties": { "applied": { "type": "boolean" }, "preview": { "$ref": "#/components/schemas/ManagedAgentRuntimePolicyReconciliationPreview" }, "revision_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ManagedAgentRuntimePolicyReconciliationStatus": { "type": "string", "enum": [ "eligible", "already_reconciled", "not_applicable", "conflict" ] }, "ManagedAgentRuntimeResources": { "type": "object", "required": [ "compute_backend", "runtime_kind", "runtime_adapter", "private_output_policy", "runtime_policy_configured", "filesystem_policy_configured", "network_policy_configured", "process_policy_configured", "effective_cpu_request_millicores", "effective_memory_request_mib", "deployment_network_policy_configured", "alert_policy_configured" ], "properties": { "alert_policy_configured": { "type": "boolean" }, "compute_backend": { "$ref": "#/components/schemas/CloudDeploymentComputeBackend" }, "configured_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Declared runtime bound from `runtime_policy.resources`, when present.", "minimum": 0 }, "deployment_network_policy_configured": { "type": "boolean" }, "effective_cpu_request_millicores": { "type": "integer", "format": "int32" }, "effective_memory_request_mib": { "type": "integer", "format": "int32" }, "effective_runtime_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Canonical executor runtime bound after defaults and policy resolution.", "minimum": 0 }, "filesystem_policy_configured": { "type": "boolean" }, "infrastructure_deadline_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Kubernetes Job deadline, including startup grace.", "minimum": 0 }, "llm_connection": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentLlmConnection" } ] }, "model_id": { "type": [ "string", "null" ] }, "network_policy_configured": { "type": "boolean" }, "observed_cpu_request_millicores": { "type": [ "integer", "null" ], "format": "int32", "description": "Reserved for controller-observed values once the controller reports them." }, "observed_memory_request_mib": { "type": [ "integer", "null" ], "format": "int32" }, "private_output_policy": { "$ref": "#/components/schemas/ManagedAgentPrivateOutputPolicy" }, "process_policy_configured": { "type": "boolean" }, "runtime_adapter": { "$ref": "#/components/schemas/ManagedAgentRuntimeAdapter" }, "runtime_class": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRuntimeClass" } ] }, "runtime_kind": { "$ref": "#/components/schemas/CloudDeploymentRuntimeKind" }, "runtime_policy_configured": { "type": "boolean" }, "runtime_resources": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentResourcePolicy" } ] }, "session_database": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentSessionDatabaseResource" } ] }, "startup_grace_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Infrastructure-only allowance for pod/bootstrap initialization.", "minimum": 0 }, "timeout_scope": { "type": [ "string", "null" ], "description": "Boundary covered by `effective_runtime_seconds`." } } }, "ManagedAgentScheduleResources": { "type": "object", "required": [ "mode", "eval_gate_configured", "eval_gate_schedule_configured" ], "properties": { "cron_schedule": { "type": [ "string", "null" ] }, "cron_timezone": { "type": [ "string", "null" ] }, "eval_gate_configured": { "type": "boolean" }, "eval_gate_schedule_configured": { "type": "boolean" }, "mode": { "$ref": "#/components/schemas/CloudDeploymentMode" } } }, "ManagedAgentSessionDatabaseResource": { "type": "object", "required": [ "provider", "engine", "url_secret_key_configured" ], "properties": { "database_name": { "type": [ "string", "null" ] }, "engine": { "$ref": "#/components/schemas/ManagedAgentSessionDatabaseEngine" }, "provider": { "$ref": "#/components/schemas/ManagedAgentSessionDatabaseProvider" }, "url_secret_key_configured": { "type": "boolean" } } }, "ManagedAgentToolCatalogEntry": { "type": "object", "required": [ "name", "description", "source", "approval_type", "approval_rule_count", "effective_policy", "side_effecting", "checkpoint_required" ], "properties": { "approval_reason": { "type": [ "string", "null" ] }, "approval_rule_count": { "type": "integer", "format": "int32", "minimum": 0 }, "approval_type": { "$ref": "#/components/schemas/ToolApprovalType" }, "checkpoint_required": { "type": "boolean", "description": "Whether this tool is included in the durable tool-call checkpoint used\nfor conservative resume. Today this mirrors `side_effecting`; it is\nseparate so future deployment policy can narrow checkpointing without\nchanging the response shape." }, "data_labels": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "effective_policy": { "$ref": "#/components/schemas/ManagedAgentToolEffectivePolicy" }, "input_schema": {}, "name": { "type": "string" }, "preset": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentToolPreset" } ] }, "side_effecting": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/ManagedAgentToolSource" } } }, "ManagedAgentToolCatalogResponse": { "type": "object", "required": [ "deployment_id", "tool_presets", "allowed_publisher_operations", "approval_policy", "tools" ], "properties": { "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ManagedAgentApprovalPolicy" }, "deployment_id": { "type": "string", "format": "uuid" }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Preset configuration enabled on the deployment. The catalog expands\nthese presets into concrete tool descriptors." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolCatalogEntry" } } } }, "ManagedAgentToolEffectivePolicy": { "type": "object", "required": [ "status", "source" ], "properties": { "conditional_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentToolPolicyStatus", "description": "Most restrictive conditional status that may apply for matching\narguments. The runtime resolves conditional rules per call with actual\narguments; the catalog only reports that stricter rules exist." } ] }, "reason": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/ManagedAgentToolPolicySource" }, "status": { "$ref": "#/components/schemas/ManagedAgentToolPolicyStatus" } } }, "ManagedAgentToolGroupEntry": { "type": "object", "required": [ "id", "label", "description", "tool_count", "tool_names", "side_effecting", "checkpoint_required", "approval_type", "effective_policy" ], "properties": { "approval_type": { "$ref": "#/components/schemas/ToolApprovalType" }, "checkpoint_required": { "type": "boolean", "description": "Whether any tool in this group is included in the durable tool-call\ncheckpoint used for conservative resume." }, "data_labels": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "effective_policy": { "$ref": "#/components/schemas/ManagedAgentToolEffectivePolicy" }, "id": { "type": "string" }, "label": { "type": "string" }, "preset": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ManagedAgentToolPreset", "description": "Source preset when this group is derived from preset configuration.\nFuture explicit/custom groups may omit this field." } ] }, "side_effecting": { "type": "boolean" }, "tool_count": { "type": "integer", "format": "int32", "minimum": 0 }, "tool_names": { "type": "array", "items": { "type": "string" } } } }, "ManagedAgentToolGroupResponse": { "type": "object", "required": [ "deployment_id", "implicit", "tool_groups" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "implicit": { "type": "boolean", "description": "True when the response is derived from preset configuration instead of\nexplicit persisted tool-group assignments." }, "tool_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolGroupEntry" }, "description": "Resolved display/read model for the deployment's named tool groups.\nToday these are derived from `tool_presets`; future custom groups use\nthe same shape with `preset` omitted." } } }, "ManagedAgentToolPolicySource": { "type": "string", "enum": [ "deployment_approval_policy", "tool_definition" ] }, "ManagedAgentToolPolicyStatus": { "type": "string", "enum": [ "allowed", "audited", "requires_approval", "blocked" ] }, "ManagedAgentToolResources": { "type": "object", "required": [ "tool_presets", "resolved_tools", "allowed_publisher_operations", "allowed_remote_agent_origins", "tool_ref_count", "credential_count", "guardrail_count" ], "properties": { "allowed_publisher_operations": { "type": "array", "items": { "type": "string" } }, "allowed_remote_agent_origins": { "type": "array", "items": { "type": "string" } }, "credential_count": { "type": "integer", "format": "int64", "minimum": 0 }, "guardrail_count": { "type": "integer", "format": "int64", "minimum": 0 }, "resolved_tools": { "type": "array", "items": { "type": "string" } }, "tool_presets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentToolPreset" }, "description": "Preset configuration enabled on the deployment. Presets are compact\nconfig inputs; use the tool-groups endpoint for the resolved display\nmodel." }, "tool_ref_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ManagedAgentToolSource": { "type": "string", "enum": [ "publisher", "mcp", "database", "custom" ] }, "ManagedDeploymentCondition": { "type": "object", "description": "Structured condition reported on a managed deployment's status. Mirrors the\nshape of `metav1.Condition` (Kubernetes) in our own DTOs without importing\nthe Kubernetes types into the public API. Each condition has a typed\n`type`, a tri-state `status`, and human-readable `reason`/`message` fields.", "required": [ "type", "status" ], "properties": { "last_transition_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent transition into the current `status`." }, "message": { "type": [ "string", "null" ], "description": "Human-readable explanation; safe to surface in operator UI." }, "reason": { "type": [ "string", "null" ], "description": "Short token describing why the condition has its current status." }, "status": { "$ref": "#/components/schemas/ManagedDeploymentConditionState" }, "type": { "$ref": "#/components/schemas/ManagedDeploymentConditionType" } } }, "ManagedDeploymentConditionState": { "type": "string", "description": "Tri-state condition value. Mirrors Kubernetes condition status.", "enum": [ "True", "False", "Unknown" ] }, "ManagedDeploymentConditionType": { "type": "string", "description": "Closed set of managed-deployment condition types. New types should be added\nhere only when there is a clear semantic, not for ad-hoc operator messages.", "enum": [ "Accepted", "Ready", "AwaitingApproval", "PolicyDenied", "ImagePullFailed", "ConfigFetchFailed", "ReadinessProbeFailed", "Suspended", "Expired", "Failed" ] }, "PrivateModelCatalogEntry": { "type": "object", "required": [ "model_id", "label", "recommended" ], "properties": { "label": { "type": "string" }, "model_id": { "type": "string" }, "recommended": { "type": "boolean" } } }, "PrivateModelCatalogResponse": { "type": "object", "required": [ "default_model_id", "models", "supports_custom_model_id", "catalog_source" ], "properties": { "catalog_source": { "$ref": "#/components/schemas/PrivateModelCatalogSource" }, "default_model_id": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateModelCatalogEntry" } }, "notice": { "type": [ "string", "null" ] }, "supports_custom_model_id": { "type": "boolean" } } }, "PrivateModelCatalogSource": { "type": "string", "enum": [ "live_discovery", "fallback_registry", "unsupported_provider" ] }, "RollbackSerenAgentDeploymentRequest": { "type": "object", "required": [ "revision_id" ], "properties": { "revision_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "TestSerenAgentDraftRunRequest": { "type": "object", "required": [ "deployment" ], "properties": { "deployment": { "$ref": "#/components/schemas/AgentSpec", "description": "Draft managed-agent deployment spec to test." }, "message": { "type": [ "string", "null" ], "description": "Optional test message. When omitted, the server uses a generic first-run prompt." } }, "additionalProperties": false }, "TestSerenAgentDraftRunResponse": { "type": "object", "required": [ "status", "runtime_adapter", "usage", "iterations", "tool_calls", "output_events" ], "properties": { "error": { "type": [ "string", "null" ] }, "error_info": {}, "iterations": { "type": "integer", "format": "int32", "minimum": 0 }, "output_events": { "type": "array", "items": {} }, "partial_response": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "runtime_adapter": { "type": "string" }, "status": { "$ref": "#/components/schemas/ManagedAgentDraftTestRunStatus" }, "tool_calls": { "type": "array", "items": {} }, "usage": {}, "warnings": { "type": "array", "items": { "type": "string" } }, "workflow": {} } }, "WorkloadLimitsPatch": { "type": "object", "description": "Partial update for workload run limits.\n\nEach value field preserves the current value when omitted. Its matching\n`clear_*` flag explicitly removes the current limit and cannot be combined\nwith a replacement value.", "properties": { "clear_context_budget_tokens": { "type": "boolean" }, "clear_max_iterations": { "type": "boolean" }, "clear_max_timeout_seconds": { "type": "boolean" }, "clear_max_tool_calls_per_run": { "type": "boolean" }, "clear_max_tool_output_chars": { "type": "boolean" }, "context_budget_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_iterations": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_timeout_seconds": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_calls_per_run": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "max_tool_output_chars": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "ApiResultResponse": { "type": "object", "description": "API result response", "required": [ "status", "body", "response_bytes", "execution_time_ms", "cost", "asset_symbol", "payment_source" ], "properties": { "asset_symbol": { "type": "string", "description": "Asset symbol (e.g., USDC, USDT)" }, "body": { "description": "Response body (JSON if available, raw text for textual upstreams, or null\nwhen body_base64 is set)" }, "body_base64": { "type": [ "string", "null" ], "description": "Raw binary response body, base64-encoded. Present only when the upstream\nreturned a non-JSON, non-text payload. When set, `body` is null." }, "content_type": { "type": [ "string", "null" ], "description": "Upstream Content-Type for a base64-encoded binary response body." }, "cost": { "type": "string", "description": "Actual cost charged in configured asset" }, "cost_breakdown": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CostBreakdown", "description": "Optional cost breakdown (target + service fee) when a service fee is charged." } ] }, "execution_time_ms": { "type": "integer", "format": "int32", "description": "Execution time in milliseconds" }, "payment_source": { "type": "string", "description": "Payment source used" }, "response_bytes": { "type": "integer", "format": "int64", "description": "Size of the publisher response body in bytes (raw, before JSON parsing).", "minimum": 0 }, "status": { "type": "integer", "format": "int32", "description": "HTTP status from publisher", "minimum": 0 } } }, "CostBreakdown": { "type": "object", "description": "Cost breakdown when a service fee is charged (e.g., pre-authorization or geo-proxy routing).", "required": [ "target", "service_fee", "total" ], "properties": { "service_fee": { "type": "string", "description": "Service fee charged" }, "target": { "type": "string", "description": "Cost charged for the target API" }, "total": { "type": "string", "description": "Total cost (target + service_fee)" } } }, "DataResponse_ApiResultResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "API result response", "required": [ "status", "body", "response_bytes", "execution_time_ms", "cost", "asset_symbol", "payment_source" ], "properties": { "asset_symbol": { "type": "string", "description": "Asset symbol (e.g., USDC, USDT)" }, "body": { "description": "Response body (JSON if available, raw text for textual upstreams, or null\nwhen body_base64 is set)" }, "body_base64": { "type": [ "string", "null" ], "description": "Raw binary response body, base64-encoded. Present only when the upstream\nreturned a non-JSON, non-text payload. When set, `body` is null." }, "content_type": { "type": [ "string", "null" ], "description": "Upstream Content-Type for a base64-encoded binary response body." }, "cost": { "type": "string", "description": "Actual cost charged in configured asset" }, "cost_breakdown": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CostBreakdown", "description": "Optional cost breakdown (target + service fee) when a service fee is charged." } ] }, "execution_time_ms": { "type": "integer", "format": "int32", "description": "Execution time in milliseconds" }, "payment_source": { "type": "string", "description": "Payment source used" }, "response_bytes": { "type": "integer", "format": "int64", "description": "Size of the publisher response body in bytes (raw, before JSON parsing).", "minimum": 0 }, "status": { "type": "integer", "format": "int32", "description": "HTTP status from publisher", "minimum": 0 } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "DataResponse_PrivateModelsListResponse": { "type": "object", "description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "object", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateModelsModelInfo" } }, "object": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta", "description": "Optional pagination metadata" } ] } } }, "PrivateModelsChatCompletionsRequest": { "type": "object", "required": [ "messages" ], "properties": { "max_tokens": { "type": [ "integer", "null" ], "format": "int32" }, "messages": { "type": "array", "items": { "type": "object" } }, "model": { "type": [ "string", "null" ] }, "response_schema": { "type": [ "object", "null" ] }, "stream": { "type": "boolean" }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "tools": { "type": [ "array", "null" ], "items": { "type": "object" } }, "top_k": { "type": [ "integer", "null" ], "format": "int32" }, "top_p": { "type": [ "number", "null" ], "format": "float" } } }, "PrivateModelsListResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateModelsModelInfo" } }, "object": { "type": "string" } } }, "PrivateModelsModelInfo": { "type": "object", "required": [ "id", "object", "created", "owned_by" ], "properties": { "created": { "type": "integer", "format": "int64" }, "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "object": { "type": "string" }, "owned_by": { "type": "string" }, "recommended": { "type": [ "boolean", "null" ] } } }, "AccessLevel": { "type": "string", "enum": [ "read", "write", "admin" ] }, "AccountSecretsRecord": { "type": "object", "description": "Opaque account_secrets blob returned by `GET /account/secrets`.", "required": [ "user_id", "kdf_params", "recovery_kdf_params", "account_key_wrap", "account_kem_private_wrap", "account_signing_private_wrap", "recovery_key_wrap" ], "properties": { "account_kem_private_wrap": { "type": "string" }, "account_key_wrap": { "type": "string" }, "account_signing_private_wrap": { "type": "string" }, "kdf_params": {}, "recovery_kdf_params": {}, "recovery_key_wrap": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "AccountSecretsUpdateRequest": { "type": "object", "description": "Body for `PUT /account/secrets`.\n\nRotates the existing account_secrets blob under a freshly-derived\nmaster-password key or recovery key. The update proof binds the new blob\ndigest to the existing account signing key so a stolen Seren session cannot\noverwrite the user's encrypted private material.", "required": [ "kdf_params", "recovery_kdf_params", "account_key_wrap", "account_kem_private_wrap", "account_signing_private_wrap", "recovery_key_wrap", "issued_at", "update_proof_signature" ], "properties": { "account_kem_private_wrap": { "type": "string" }, "account_key_wrap": { "type": "string" }, "account_signing_private_wrap": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp the client signed. Server rejects outside the\nUPDATE_PROOF_WINDOW to bound replay." }, "kdf_params": {}, "recovery_kdf_params": {}, "recovery_key_wrap": { "type": "string" }, "update_proof_signature": { "type": "string", "description": "Ed25519 signature over the canonical proof bytes (user_id, issued_at,\nblob_digest) produced by the existing account signing key." } } }, "AccountSetupRequest": { "type": "object", "description": "Body for `PUT /account`.\n\nFirst-time setup creates the user's E2EE identity, stores the opaque\naccount_secrets blob, and provisions the default Personal vault in one\ntransaction. The server receives only public identity material, ciphertext\nwraps, and the client's signed vault-membership grant.", "required": [ "kdf_params", "recovery_kdf_params", "account_key_wrap", "account_kem_private_wrap", "account_signing_private_wrap", "recovery_key_wrap", "display_name", "kem_public_key", "signing_public_key", "personal_vault_wrapped_key", "personal_vault_id", "personal_vault_name_ciphertext", "personal_vault_granted_signature" ], "properties": { "account_kem_private_wrap": { "type": "string" }, "account_key_wrap": { "type": "string" }, "account_signing_private_wrap": { "type": "string" }, "display_name": { "type": "string", "description": "Display name for the new user identity." }, "kdf_params": {}, "kem_public_key": { "type": "string", "description": "Identity KEM public key." }, "personal_vault_description_ciphertext": { "type": "string" }, "personal_vault_granted_signature": { "type": "string", "description": "Ed25519 signature granting the new identity admin membership in the\nPersonal vault." }, "personal_vault_id": { "type": "string", "format": "uuid", "description": "Client-generated Personal vault id. The id is bound into the\nencrypted vault label AAD, so the client must know it before setup." }, "personal_vault_name_ciphertext": { "type": "string" }, "personal_vault_wrapped_key": { "type": "string", "description": "Wrapped Personal vault key under the new identity's KEM public key." }, "recovery_kdf_params": {}, "recovery_key_wrap": { "type": "string" }, "signing_public_key": { "type": "string", "description": "Identity signing public key." } } }, "AccountSetupResponse": { "type": "object", "description": "Response from `PUT /account`.", "required": [ "identity", "secrets", "personal_vault_id" ], "properties": { "identity": { "$ref": "#/components/schemas/IdentityRecord", "description": "The caller's active user identity in this org." }, "personal_vault_id": { "type": "string", "format": "uuid", "description": "The caller's Personal vault." }, "secrets": { "$ref": "#/components/schemas/AccountSecretsRecord" } } }, "AgentFreezeResponse": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AgentSummary": { "type": "object", "description": "An owned agent identity plus the vaults it currently has access to.\nReturned by `GET /identities/agents` to power `seren passwords agent list`.", "required": [ "identity", "granted_vaults" ], "properties": { "granted_vaults": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVaultGrant" } }, "identity": { "$ref": "#/components/schemas/IdentityRecord" } } }, "AgentVaultGrant": { "type": "object", "description": "A single vault grant held by an agent identity, returned by\n`GET /identities/agents`. Carries only public metadata: the vault id, the\naccess level, and when the grant was made. No wrapped key material.", "required": [ "vault_id", "access_level", "granted_at" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_at": { "type": "string", "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" } } }, "ApprovalDecisionRequest": { "type": "object", "required": [ "one_shot_wrapped_key" ], "properties": { "one_shot_wrapped_key": { "type": "string" } } }, "ApprovalRecord": { "type": "object", "required": [ "request_id", "requesting_identity_id", "target_kind", "target_id", "status", "expires_at", "created_at" ], "properties": { "approver_identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "one_shot_wrapped_key": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "requesting_identity_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ApprovalStatus" }, "target_id": { "type": "string", "format": "uuid" }, "target_kind": { "$ref": "#/components/schemas/ApprovalTargetKind" } } }, "ApprovalStatus": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ] }, "ApprovalTargetKind": { "type": "string", "enum": [ "vault", "item" ] }, "ApproveContext": { "type": "object", "description": "Material an approver needs to construct the `one_shot_wrapped_key`\nfor `POST /approvals/{id}/approve`. The wrap is built client-side:\nthe approver seals the per-item content key (item targets) or the\nvault key (vault targets) under the requester's identity KEM public\nkey.\n\nFor item targets the server returns the item's `content_key_wrap` so\nthe approver can unwrap the content key with their vault key and\nthen re-seal it for the requester. For vault targets only the\nrequester KEM pub and vault id are returned, since the approver\nalready has the vault key in memory.", "required": [ "target_kind", "vault_id", "requester_kem_public_key", "approver_wrapped_vault_key" ], "properties": { "approver_wrapped_vault_key": { "type": "string", "description": "Base64. The approver's own wrapped vault key for the target\nvault, so the approver can unwrap the vault key on the client\nwithout a second round-trip." }, "content_key_wrap": { "type": [ "string", "null" ], "description": "Base64. Only set for item-kind approvals." }, "item_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Only set for item-kind approvals. The item id is required by the\napprover because the per-item content-key wrap AAD binds to it;\nreturning it here lets the client unwrap without consulting any\nseparately-loaded approval listing." }, "requester_kem_public_key": { "type": "string", "description": "Base64. The requester identity's KEM public key. The approver\nuses this to KEM-seal the wrapped material." }, "target_kind": { "$ref": "#/components/schemas/ApprovalTargetKind" }, "vault_id": { "type": "string", "format": "uuid" } } }, "ApproveDelegationConsentRequest": { "type": "object", "required": [ "consent_capability", "access_level", "grants" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "consent_capability": { "type": "string" }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationVaultGrant" } } } }, "ApproveDelegationRequest": { "type": "object", "required": [ "identity_id", "granted_vault_ids" ], "properties": { "granted_vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "identity_id": { "type": "string", "format": "uuid" } } }, "AttachmentView": { "type": "object", "required": [ "attachment_id", "item_id", "filename_ciphertext", "content_type_ciphertext", "size_bytes", "wrapped_content_key", "created_at" ], "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "content_type_ciphertext": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "filename_ciphertext": { "type": "string" }, "item_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64" }, "wrapped_content_key": { "type": "string" } } }, "AttachmentWithBlobView": { "allOf": [ { "$ref": "#/components/schemas/AttachmentView" }, { "type": "object", "required": [ "blob" ], "properties": { "blob": { "type": "string", "description": "Base64-encoded encrypted blob bytes the client must decrypt with the\nunwrapped attachment key and the (item_id, attachment_id) AAD." } } } ] }, "AuditChainVerifyResult": { "type": "object", "required": [ "verified", "entries", "checked_at" ], "properties": { "checked_at": { "type": "string", "format": "date-time" }, "entries": { "type": "integer", "format": "int64" }, "first_broken_log_id": { "type": [ "string", "null" ], "format": "uuid" }, "verified": { "type": "boolean" } } }, "AuditLogEntry": { "type": "object", "required": [ "log_id", "actor_identity_id", "action", "metadata", "created_at" ], "properties": { "action": { "type": "string" }, "actor_identity_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "log_id": { "type": "string", "format": "uuid" }, "metadata": {}, "target_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_kind": { "type": [ "string", "null" ] } } }, "BatchEntryResult": { "oneOf": [ { "type": "object", "required": [ "vault_id", "item_id", "field_name", "content_ciphertext", "content_key_wrap", "wrapped_vault_key", "status" ], "properties": { "content_ciphertext": { "type": "string" }, "content_key_wrap": { "type": "string" }, "field_name": { "type": "string" }, "item_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ok" ] }, "vault_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string" } } }, { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approval_required" ] } } }, { "type": "object", "required": [ "code", "message", "status" ], "properties": { "code": { "type": "integer", "format": "int32", "minimum": 0 }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "error" ] } } } ], "description": "One entry in a batch resolve response, position-aligned with the\ncorresponding request. `Ok` carries the wrapped material; the other\nvariants surface the error so an investigator and the calling runtime\ncan see exactly which URIs failed and why without parsing free-form\nstrings." }, "BatchResolveRequest": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/ResolveRequest" } } } }, "BatchResolveResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchEntryResult" } } } }, "ClaimLiveShareRequest": { "type": "object", "required": [ "share_token", "recipient_identity_id" ], "properties": { "recipient_email": { "type": [ "string", "null" ], "description": "Required when the share was restricted to an email address." }, "recipient_identity_id": { "type": "string", "format": "uuid" }, "recipient_wrapped_item_key": { "type": [ "string", "null" ] }, "share_token": { "type": "string" } } }, "CompleteInvitationRequest": { "type": "object", "required": [ "wrapped_vault_key" ], "properties": { "granted_signature": { "type": "string" }, "wrapped_vault_key": { "type": "string" } } }, "CompleteLiveShareRequest": { "type": "object", "required": [ "recipient_wrapped_item_key" ], "properties": { "recipient_wrapped_item_key": { "type": "string" } } }, "CreateAgentIdentityRequest": { "type": "object", "description": "Body for creating an agent identity.", "required": [ "display_name", "kem_public_key", "signing_public_key", "key_provenance", "issued_at", "nonce", "signature" ], "properties": { "display_name": { "type": "string" }, "issued_at": { "type": "integer", "format": "int64", "description": "Unix seconds when the owner signed this request. The server bounds the\nallowed skew so a captured signature cannot be replayed indefinitely." }, "kem_public_key": { "type": "string" }, "key_provenance": {}, "kms_key_id": { "type": [ "string", "null" ] }, "nonce": { "type": "string", "description": "Single-use nonce bound into the signed canonical bytes." }, "signature": { "type": "string", "description": "Ed25519 signature by the owning user over the canonical request bytes." }, "signing_public_key": { "type": "string" } } }, "CreateApprovalRequest": { "type": "object", "required": [ "target_kind", "target_id" ], "properties": { "target_id": { "type": "string", "format": "uuid" }, "target_kind": { "$ref": "#/components/schemas/ApprovalTargetKind" }, "timeout_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Seconds to keep the request pending; defaults to 300.", "minimum": 0 } } }, "CreateAttachmentRequest": { "type": "object", "required": [ "attachment_id", "blob", "filename_ciphertext", "content_type_ciphertext", "wrapped_content_key" ], "properties": { "attachment_id": { "type": "string", "format": "uuid", "description": "Client-generated attachment id used in the AEAD associated data for\nthe blob, metadata, and wrapped attachment key." }, "blob": { "type": "string", "description": "The encrypted attachment blob (XChaCha20-Poly1305 envelope under the\nper-attachment content key, AAD-bound to (item_id, attachment_id))." }, "content_type_ciphertext": { "type": "string", "description": "AEAD envelope of the content-type under the vault key." }, "filename_ciphertext": { "type": "string", "description": "AEAD envelope of the filename under the vault key." }, "wrapped_content_key": { "type": "string", "description": "The per-attachment content key wrapped under the vault key." } } }, "CreateDelegationRequest": { "type": "object", "required": [ "agent_kem_public", "agent_signing_public", "display_name" ], "properties": { "agent_kem_public": { "type": "string" }, "agent_signing_public": { "type": "string" }, "display_name": { "type": "string" }, "request_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreateHostedAgentIdentityRequest": { "type": "object", "description": "Body for creating a hosted agent identity whose private keys are generated\nserver-side and stored only as KMS-wrapped envelopes.", "required": [ "display_name", "key_provenance", "issued_at", "nonce", "signature" ], "properties": { "display_name": { "type": "string" }, "issued_at": { "type": "integer", "format": "int64", "description": "Unix seconds when the owner signed this hosted identity request." }, "key_provenance": {}, "nonce": { "type": "string", "description": "Single-use nonce bound into the signed canonical bytes." }, "signature": { "type": "string", "description": "Ed25519 signature by the owning user over the canonical hosted identity\nrequest bytes." } } }, "CreateInvitationRequest": { "type": "object", "required": [ "invitation_id", "invitee_email", "invitee_email_ciphertext", "access_level" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "expires_in_hours": { "type": [ "integer", "null" ], "format": "int64", "description": "Omit for the default 14 days, send null for no expiration, or\nsend hours clamped to 1 hour through 1 year." }, "invitation_id": { "type": "string", "format": "uuid" }, "invitee_email": { "type": "string" }, "invitee_email_ciphertext": { "type": "string" } } }, "CreateItemRequest": { "type": "object", "required": [ "item_id", "title_ciphertext", "content_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext" ], "properties": { "content_ciphertext": { "type": "string" }, "content_key_wrap": { "type": "string", "description": "Per-item content key sealed under the vault key (see\ncrypto::protocol::item::wrap_item_content_key). The body ciphertext\nis sealed under that content key, never directly under the vault\nkey; the server enforces presence with a NOT NULL column." }, "item_id": { "type": "string", "format": "uuid" }, "metadata_ciphertext": { "type": "string" }, "sensitive": { "type": "boolean" }, "tags_ciphertext": { "type": "string" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "wrapping_key_version": { "type": [ "integer", "null" ], "format": "int32", "description": "The `vault_key_version` the client believed it was sealing under\nwhen it produced these ciphertexts. The server rejects the write\nwith 409 Conflict if it does not match the vault's current\nversion, so a client that raced a key rotation must re-fetch its\nwrapped vault key and re-encrypt before retrying." } } }, "CreateShareKind": { "type": "string", "enum": [ "live" ] }, "CreateShareRequest": { "type": "object", "required": [ "kind", "share_id", "vault_id", "item_id" ], "properties": { "expires_in_hours": { "type": [ "integer", "null" ], "format": "int64", "description": "Omit for the default 14 days, send null for no expiration, or\nsend hours clamped to 1 hour through 1 year." }, "item_id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/CreateShareKind" }, "recipient_email": { "type": [ "string", "null" ], "description": "Plaintext email is used transiently for invite delivery and claim\nauthorization. It is never persisted." }, "recipient_email_ciphertext": { "type": [ "string", "null" ] }, "recipient_identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_kem_public_key": { "type": [ "string", "null" ] }, "recipient_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_wrapped_item_key": { "type": "string" }, "share_id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" } } }, "CreateVaultRequest": { "type": "object", "required": [ "vault_id", "name_ciphertext", "owner_kind", "initial_wrapped_vault_key", "access_level", "granted_signature" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "description_ciphertext": { "type": "string" }, "granted_signature": { "type": "string", "description": "Ed25519 signature over (vault_id, identity_id, access_level)." }, "initial_wrapped_vault_key": { "type": "string" }, "name_ciphertext": { "type": "string" }, "owner_kind": { "$ref": "#/components/schemas/VaultOwnerKind" }, "requires_approval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VaultApprovalMode" } ] }, "vault_id": { "type": "string", "format": "uuid" } } }, "DataResponseAccountSecretsRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountSecretsRecord" } } }, "DataResponseAccountSetup": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccountSetupResponse" } } }, "DataResponseAgentFreeze": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentFreezeResponse" } } }, "DataResponseAgentSummaryList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } } } }, "DataResponseApprovalRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRecord" } } }, "DataResponseApprovalRecordList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRecord" } } } }, "DataResponseApproveContext": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApproveContext" } } }, "DataResponseAttachmentView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttachmentView" } } }, "DataResponseAttachmentViewList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentView" } } } }, "DataResponseAttachmentWithBlobView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttachmentWithBlobView" } } }, "DataResponseAuditChainVerifyResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuditChainVerifyResult" } } }, "DataResponseAuditLogEntryList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } } } }, "DataResponseBatchResolve": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BatchResolveResponse" } } }, "DataResponseDelegationConsentView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DelegationConsentView" } } }, "DataResponseDelegationRequestCreated": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DelegationRequestCreatedResponse" } } }, "DataResponseDelegationRequestRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DelegationRequestRecord" } } }, "DataResponseHistoryEntryList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryEntry" } } } }, "DataResponseIdentityRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IdentityRecord" } } }, "DataResponseIdentityRecordList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRecord" } } } }, "DataResponseInvitationCreated": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvitationCreatedResponse" } } }, "DataResponseInvitationView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InvitationView" } } }, "DataResponseInvitationViewList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationView" } } } }, "DataResponseItemRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ItemRecord" } } }, "DataResponseItemSummaryList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummary" } } } }, "DataResponseJsonValue": { "type": "object", "description": "`data: serde_json::Value` envelopes used by endpoints that return ad-hoc\nJSON payloads (e.g. `{ \"revoked\": true }`, `{ \"completed\": true }`).\nThe schema is intentionally open: utoipa renders `Value` as the generic\nJSON Object type.", "required": [ "data" ], "properties": { "data": { "type": "object" } } }, "DataResponseLiveShareCreated": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LiveShareCreatedResponse" } } }, "DataResponseLiveShareView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LiveShareView" } } }, "DataResponseLiveShareViewList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LiveShareView" } } } }, "DataResponseMembershipRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MembershipRecord" } } }, "DataResponseMembershipRecordList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipRecord" } } } }, "DataResponseReceivedShareViewList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedShareView" } } } }, "DataResponseRecoveryInitiate": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecoveryInitiateResponse" } } }, "DataResponseResolve": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ResolveResponse" } } }, "DataResponseRotationInitiate": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RotationInitiateResponse" } } }, "DataResponseSecretsGatewayDelegationConfig": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SecretsGatewayDelegationConfigResponse" } } }, "DataResponseShareRecipientLookup": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ShareRecipientLookupResponse" } } }, "DataResponseSharedItemView": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SharedItemView" } } }, "DataResponseSync": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SyncResponse" } } }, "DataResponseVaultRecord": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VaultRecord" } } }, "DataResponseVaultRecordList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VaultRecord" } } } }, "DelegationConsentCapabilityRequest": { "type": "object", "required": [ "consent_capability" ], "properties": { "consent_capability": { "type": "string" } } }, "DelegationConsentView": { "type": "object", "required": [ "display_name", "agent_kem_public", "agent_signing_public", "target_identity_id", "status", "granted_vault_ids", "expires_at" ], "properties": { "agent_kem_public": { "type": "string" }, "agent_signing_public": { "type": "string" }, "approval_access_level": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessLevel" } ] }, "display_name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "granted_vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "status": { "$ref": "#/components/schemas/DelegationStatus" }, "target_identity_id": { "type": "string", "format": "uuid" } } }, "DelegationRequestCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/DelegationRequestRecord" }, { "type": "object", "required": [ "consent_capability" ], "properties": { "consent_capability": { "type": "string", "description": "One-time bearer capability for the browser consent flow. This value is\nreturned only when the requester creates the delegation." } } } ] }, "DelegationRequestRecord": { "type": "object", "required": [ "request_id", "user_id", "agent_kem_public", "agent_signing_public", "display_name", "status", "granted_vault_ids", "created_at", "expires_at" ], "properties": { "agent_kem_public": { "type": "string" }, "agent_signing_public": { "type": "string" }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "credential_kind": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "display_name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "granted_vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/DelegationStatus" }, "user_id": { "type": "string", "format": "uuid" } } }, "DelegationStatus": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ] }, "DelegationVaultGrant": { "type": "object", "required": [ "vault_id", "wrapped_vault_key", "granted_signature" ], "properties": { "granted_signature": { "type": "string" }, "vault_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string" } } }, "DuplicateItemAttachmentRequest": { "type": "object", "required": [ "source_attachment_id", "attachment_id", "blob", "filename_ciphertext", "content_type_ciphertext", "wrapped_content_key" ], "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "blob": { "type": "string" }, "content_type_ciphertext": { "type": "string" }, "filename_ciphertext": { "type": "string" }, "source_attachment_id": { "type": "string", "format": "uuid" }, "wrapped_content_key": { "type": "string" } } }, "DuplicateItemRequest": { "type": "object", "required": [ "item_id", "title_ciphertext", "content_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateItemAttachmentRequest" }, "description": "Re-encrypted attachments for the duplicated item. Each source\nattachment must be represented exactly once because attachment blobs are\nAAD-bound to both item id and attachment id." }, "content_ciphertext": { "type": "string" }, "content_key_wrap": { "type": "string", "description": "Per-item content key sealed under the destination vault key and bound\nto the new item id." }, "item_id": { "type": "string", "format": "uuid", "description": "New item id. Item ciphertext AAD is item-id-bound, so clients must\nencrypt the duplicate payload for this id." }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "target_vault_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Destination vault. Defaults to the source vault." }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "wrapping_key_version": { "type": [ "integer", "null" ], "format": "int32", "description": "Destination vault key version used for every vault-key-scoped\nciphertext in this payload." } } }, "ForeignVaultMembershipRecord": { "type": "object", "required": [ "vault_id", "recipient_organization_id", "recipient_user_id", "recipient_identity_id", "recipient_kem_public_key", "access_level", "granted_by_identity", "granted_at" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_at": { "type": "string", "format": "date-time" }, "granted_by_identity": { "type": "string", "format": "uuid" }, "recipient_identity_id": { "type": "string", "format": "uuid" }, "recipient_kem_public_key": { "type": "string" }, "recipient_organization_id": { "type": "string", "format": "uuid" }, "recipient_user_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" } } }, "HistoryEntry": { "type": "object", "required": [ "history_id", "content_ciphertext", "archived_at" ], "properties": { "archived_at": { "type": "string" }, "content_ciphertext": { "type": "string" }, "history_id": { "type": "string", "format": "uuid" } } }, "IdentityRecord": { "type": "object", "description": "Identity record returned by `/identities/me` and `/identities/{id}`.", "required": [ "identity_id", "kind", "owner_user_id", "display_name", "kem_public_key", "signing_public_key", "key_provenance", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": "string" }, "identity_id": { "type": "string", "format": "uuid" }, "kem_public_key": { "type": "string" }, "key_provenance": {}, "kind": { "type": "string" }, "kms_key_id": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "signing_public_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InvitationCreatedResponse": { "type": "object", "required": [ "invitation_id", "vault_id", "invitee_email_ciphertext", "access_level", "invitation_token" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "invitation_id": { "type": "string", "format": "uuid" }, "invitation_token": { "type": "string", "description": "One-shot token. Treat as a secret; never echoed by other endpoints." }, "invitee_email_ciphertext": { "type": "string" }, "vault_id": { "type": "string", "format": "uuid" } } }, "InvitationView": { "type": "object", "required": [ "invitation_id", "vault_id", "inviter_identity_id", "invitee_email_ciphertext", "access_level", "created_at" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "invitation_id": { "type": "string", "format": "uuid" }, "invitee_email_ciphertext": { "type": "string" }, "inviter_identity_id": { "type": "string", "format": "uuid" }, "recipient_identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_kem_public_key": { "type": [ "string", "null" ] }, "recipient_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_by_identity": { "type": [ "string", "null" ], "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" } } }, "ItemKind": { "type": "string", "enum": [ "login", "secure_note", "api_credential", "identity", "card", "ssh_key", "document", "bank_account", "passport", "driver_license", "crypto_wallet", "server", "database" ] }, "ItemRecord": { "type": "object", "required": [ "item_id", "vault_id", "title_ciphertext", "content_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "content_ciphertext": { "type": "string" }, "content_key_wrap": { "type": "string", "description": "Per-item content key sealed under the vault key. Always present;\nclients decrypt the body by unwrapping this with the vault key,\nthen opening the body ciphertext under the recovered content key." }, "created_at": { "type": "string", "format": "date-time" }, "item_id": { "type": "string", "format": "uuid" }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "trashed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set when the item is in the trash. Distinct from `archived_at`.\nA second DELETE on a trashed item hard-deletes the row entirely." }, "updated_at": { "type": "string", "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" }, "vault_key_version": { "type": "integer", "format": "int32", "description": "Vault key version under which this row's ciphertexts were sealed.\nClients echo it back on PATCH via `wrapping_key_version` to guard\nagainst rotation races; the server rejects with 409 on mismatch." } } }, "ItemSummary": { "type": "object", "required": [ "item_id", "vault_id", "title_ciphertext", "title_blind_index", "metadata_ciphertext", "updated_at" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" } } }, "ListStateParam": { "type": "string", "enum": [ "active", "trashed", "archived" ] }, "LiveShareCreatedResponse": { "type": "object", "required": [ "share", "share_token" ], "properties": { "share": { "$ref": "#/components/schemas/LiveShareView" }, "share_token": { "type": "string", "description": "Signed routing token. Send it only through the intended invite path." } } }, "LiveShareView": { "type": "object", "required": [ "share_id", "owner_organization_id", "owner_user_id", "owner_vault_id", "owner_item_id", "sender_identity_id", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_item_id": { "type": "string", "format": "uuid" }, "owner_organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" }, "owner_vault_id": { "type": "string", "format": "uuid" }, "recipient_email_ciphertext": { "type": [ "string", "null" ] }, "recipient_identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_kem_public_key": { "type": [ "string", "null" ] }, "recipient_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "sender_identity_id": { "type": "string", "format": "uuid" }, "share_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MembershipGrantRequest": { "type": "object", "required": [ "identity_id", "wrapped_vault_key", "access_level", "granted_signature" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_signature": { "type": "string" }, "identity_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string" } } }, "MembershipRecord": { "type": "object", "required": [ "vault_id", "identity_id", "access_level", "granted_by_identity", "granted_at" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_at": { "type": "string", "format": "date-time" }, "granted_by_identity": { "type": "string", "format": "uuid" }, "identity_id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" } } }, "MoveItemAttachmentRequest": { "type": "object", "required": [ "attachment_id", "filename_ciphertext", "content_type_ciphertext", "wrapped_content_key" ], "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "content_type_ciphertext": { "type": "string" }, "filename_ciphertext": { "type": "string" }, "wrapped_content_key": { "type": "string" } } }, "MoveItemRequest": { "type": "object", "required": [ "target_vault_id", "title_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MoveItemAttachmentRequest" }, "description": "Re-wrapped attachment metadata for the moved item. Blob ciphertext is\nunchanged on move because item id and attachment ids stay stable." }, "content_key_wrap": { "type": "string", "description": "Per-item content key re-wrapped under the destination vault key and\nstill bound to the existing item id." }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "target_vault_id": { "type": "string", "format": "uuid" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "wrapping_key_version": { "type": [ "integer", "null" ], "format": "int32", "description": "Destination vault key version used for every vault-key-scoped\nciphertext in this payload." } } }, "ReceivedShareView": { "type": "object", "required": [ "received_share_id", "share_id", "owner_organization_id", "owner_user_id", "owner_vault_id", "owner_item_id", "recipient_identity_id", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "owner_item_id": { "type": "string", "format": "uuid" }, "owner_organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" }, "owner_vault_id": { "type": "string", "format": "uuid" }, "received_share_id": { "type": "string", "format": "uuid" }, "recipient_identity_id": { "type": "string", "format": "uuid" }, "sender_display_name_ciphertext": { "type": [ "string", "null" ] }, "share_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RecoveryCompleteRequest": { "type": "object", "required": [ "recovery_request_id", "recovery_proof_signature", "new_account_secrets" ], "properties": { "new_account_secrets": { "$ref": "#/components/schemas/RecoveryNewAccountSecrets", "description": "New AccountSecrets blob the client built by re-wrapping the existing\naccount_key under a new master-password-derived key. Recovery does not\nrotate identity public keys; clients must keep both public halves equal\nto the existing active identity." }, "recovery_proof_signature": { "type": "string" }, "recovery_request_id": { "type": "string", "format": "uuid" } } }, "RecoveryInitiateResponse": { "type": "object", "required": [ "recovery_request_id", "challenge", "expires_at" ], "properties": { "challenge": { "type": "string", "description": "32 random bytes base64-encoded. Bind this into the proof on /complete." }, "expires_at": { "type": "string", "format": "date-time" }, "recovery_request_id": { "type": "string", "format": "uuid" } } }, "RecoveryNewAccountSecrets": { "type": "object", "description": "New account-secrets blob submitted alongside a recovery completion.\n\nRecovery rewraps the existing account key under a new master-password-\nderived key and rotates the recovery key; the identity public keys are\nre-asserted (server checks they did not change) but no personal-vault or\ndisplay-name material is involved. This is a strict subset of the\nfirst-time setup request body in `routes::account`.", "required": [ "kdf_params", "recovery_kdf_params", "account_key_wrap", "account_kem_private_wrap", "account_signing_private_wrap", "recovery_key_wrap", "kem_public_key", "signing_public_key" ], "properties": { "account_kem_private_wrap": { "type": "string" }, "account_key_wrap": { "type": "string" }, "account_signing_private_wrap": { "type": "string" }, "kdf_params": {}, "kem_public_key": { "type": "string" }, "recovery_kdf_params": {}, "recovery_key_wrap": { "type": "string" }, "signing_public_key": { "type": "string" } } }, "RedeemRequest": { "type": "object", "required": [ "invitation_token" ], "properties": { "invitation_token": { "type": "string" }, "recipient_email": { "type": [ "string", "null" ] } } }, "ResolveRequest": { "type": "object", "required": [ "uri", "issued_at", "nonce", "request_signature" ], "properties": { "issued_at": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp the client signed. Server rejects if outside the\nSIGNATURE_WINDOW around its own clock." }, "nonce": { "type": "string", "format": "uuid", "description": "Single-use nonce bound into the signature and consumed by the service." }, "request_signature": { "type": "string", "description": "Ed25519 signature over the canonical request, produced by the caller's\nidentity signing key (the user's or the agent's). Wire encoding from\nthe crypto crate (versioned)." }, "uri": { "type": "string", "description": "e.g. `seren-secrets:////`" } } }, "ResolveResponse": { "type": "object", "required": [ "vault_id", "item_id", "field_name", "content_ciphertext", "content_key_wrap", "wrapped_vault_key" ], "properties": { "content_ciphertext": { "type": "string", "description": "Base64 - the item body, sealed under the per-item content key." }, "content_key_wrap": { "type": "string", "description": "Base64 - the per-item content key sealed under the vault key.\nAgent unwraps the vault key first, then opens this to recover the\ncontent key, then opens `content_ciphertext` with it." }, "field_name": { "type": "string" }, "item_id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string", "description": "Base64 - the caller's wrapped vault key." } } }, "RotationAttachmentDto": { "type": "object", "required": [ "attachment_id", "filename_ciphertext", "content_type_ciphertext", "wrapped_content_key" ], "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "content_type_ciphertext": { "type": "string" }, "filename_ciphertext": { "type": "string" }, "wrapped_content_key": { "type": "string" } } }, "RotationCancelRequest": { "type": "object", "required": [ "rotation_token" ], "properties": { "rotation_token": { "type": "string", "format": "uuid" } } }, "RotationCompleteRequest": { "type": "object", "required": [ "rotation_token", "vault_name_ciphertext", "memberships", "items" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/RotationAttachmentDto" } }, "foreign_memberships": { "type": "array", "items": { "$ref": "#/components/schemas/RotationForeignMembershipDto" } }, "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/RotationInvitationDto" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RotationItemDto" } }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/RotationMembershipDto" } }, "rotation_token": { "type": "string", "format": "uuid" }, "vault_description_ciphertext": { "type": "string" }, "vault_name_ciphertext": { "type": "string" } } }, "RotationForeignMembershipDto": { "type": "object", "required": [ "recipient_organization_id", "recipient_user_id", "recipient_identity_id", "wrapped_vault_key", "access_level", "granted_signature" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_signature": { "type": "string" }, "recipient_identity_id": { "type": "string", "format": "uuid" }, "recipient_organization_id": { "type": "string", "format": "uuid" }, "recipient_user_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string" } } }, "RotationInitiateResponse": { "type": "object", "required": [ "vault_id", "rotation_token" ], "properties": { "rotation_token": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" } } }, "RotationInvitationDto": { "type": "object", "required": [ "invitation_id", "invitee_email_ciphertext" ], "properties": { "invitation_id": { "type": "string", "format": "uuid" }, "invitee_email_ciphertext": { "type": "string" } } }, "RotationItemDto": { "type": "object", "description": "Per-item payload for a rotation commit. The body ciphertext is sealed\nunder the per-item content key and does not change across rotations;\nthe client only re-wraps the content key under the new vault key.\nThe title, tags, and blind index keying material are still vault-key\nscoped, so those are re-derived and shipped alongside.", "required": [ "item_id", "title_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext" ], "properties": { "content_key_wrap": { "type": "string", "description": "Per-item content key re-wrapped under the new vault key." }, "item_id": { "type": "string", "format": "uuid" }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" } } }, "RotationMembershipDto": { "type": "object", "required": [ "identity_id", "wrapped_vault_key", "access_level", "granted_signature" ], "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel" }, "granted_signature": { "type": "string" }, "identity_id": { "type": "string", "format": "uuid" }, "wrapped_vault_key": { "type": "string" } } }, "SecretsGatewayDelegationConfigResponse": { "type": "object", "required": [ "grant_delegate_signer_key_id", "grant_delegate_public_key_b64", "default_max_grant_ttl_seconds", "delegation_epoch_unix_milliseconds" ], "properties": { "default_max_grant_ttl_seconds": { "type": "integer", "format": "int64", "minimum": 0 }, "delegation_epoch_unix_milliseconds": { "type": "integer", "format": "int64", "minimum": 0 }, "grant_delegate_public_key_b64": { "type": "string" }, "grant_delegate_signer_key_id": { "type": "string" } } }, "ShareRecipientLookupRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } }, "ShareRecipientLookupResponse": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "recipient_identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_kem_public_key": { "type": [ "string", "null" ] }, "recipient_organization_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "SharedItemRecord": { "type": "object", "description": "The owner item as seen by a live-share recipient. Omits `content_key_wrap`\n(sealed under the owner's vault key, so opaque and useless to the recipient,\nwho opens the body via `recipient_wrapped_item_key`) and `title_blind_index`\n(an owner-scoped keyed index over the plaintext title).", "required": [ "item_id", "vault_id", "title_ciphertext", "content_ciphertext", "metadata_ciphertext", "vault_key_version", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "content_ciphertext": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "item_id": { "type": "string", "format": "uuid" }, "metadata_ciphertext": { "type": "string" }, "tags_ciphertext": { "type": "string" }, "title_ciphertext": { "type": "string" }, "trashed_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" }, "vault_key_version": { "type": "integer", "format": "int32" } } }, "SharedItemView": { "type": "object", "required": [ "share", "recipient_wrapped_item_key", "item" ], "properties": { "item": { "$ref": "#/components/schemas/SharedItemRecord" }, "recipient_wrapped_item_key": { "type": "string" }, "share": { "$ref": "#/components/schemas/LiveShareView" } } }, "SyncResponse": { "type": "object", "required": [ "identities", "vaults", "memberships", "foreign_memberships", "item_overviews", "server_time" ], "properties": { "foreign_memberships": { "type": "array", "items": { "$ref": "#/components/schemas/ForeignVaultMembershipRecord" }, "description": "Active cross-organization memberships for local vaults the caller can\nsee. Used by rotation to re-wrap foreign recipients without requiring\nlocal identity rows." }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRecord" }, "description": "Active identities visible to this caller (org-scoped). Useful for\nthe desktop client to populate the \"share with\" picker without a\nseparate `/identities` fetch." }, "item_overviews": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummary" }, "description": "Active item overviews across every vault returned above. Bodies\nare not included (the client fetches `/items/{id}` on demand)." }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipRecord" }, "description": "Active memberships across every vault returned above. The client\nuses these to render the per-vault member list without one\n`/vaults/{v}/memberships` round-trip per vault." }, "server_time": { "type": "string", "format": "date-time", "description": "RFC3339 UTC timestamp from the server's clock. Clients use this to\ncalibrate their resolve-signature `issued_at` window." }, "vaults": { "type": "array", "items": { "$ref": "#/components/schemas/VaultRecord" }, "description": "Vaults the caller is a member of, each with the caller's wrapped\nvault key inlined so the client can immediately decrypt content." } } }, "UpdateItemRequest": { "type": "object", "required": [ "title_ciphertext", "content_ciphertext", "title_blind_index", "content_key_wrap", "metadata_ciphertext", "sensitive" ], "properties": { "content_ciphertext": { "type": "string" }, "content_key_wrap": { "type": "string", "description": "Per-item content key sealed under the vault key. Required on every\nupdate; the body ciphertext is sealed under it." }, "metadata_ciphertext": { "type": "string" }, "sensitive": { "type": "boolean" }, "tags_ciphertext": { "type": "string" }, "title_blind_index": { "type": "string" }, "title_ciphertext": { "type": "string" }, "wrapping_key_version": { "type": [ "integer", "null" ], "format": "int32", "description": "The `vault_key_version` the client believed it was sealing under.\nSee `CreateItemRequest::wrapping_key_version`." } } }, "VaultApprovalMode": { "type": "string", "enum": [ "never", "sensitive_only", "always" ] }, "VaultOwnerKind": { "type": "string", "enum": [ "user", "organization" ] }, "VaultPatchRequest": { "type": "object", "description": "Documentary schema for `PATCH /vaults/{vault_id}`. The runtime body\nis a free-form JSON object; at least one of `name_ciphertext` or `description_ciphertext`\nmust be present.\n\n`description_ciphertext` uses a double `Option` so the route can distinguish\nthe three caller intents the column allows: omit the field to leave\nit alone, send `null` to clear it, or send ciphertext to set it.\n`name_ciphertext` is `NOT NULL` in the schema so the single-`Option` shape\ncovers its two intents (omit vs set).", "properties": { "description_ciphertext": { "type": [ "string", "null" ] }, "name_ciphertext": { "type": "string" } } }, "VaultRecord": { "type": "object", "required": [ "vault_id", "name_ciphertext", "owner_kind", "created_by_user_id", "key_rotation_state", "requires_approval", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "description_ciphertext": { "type": "string" }, "key_rotation_state": { "type": "string" }, "name_ciphertext": { "type": "string" }, "owner_kind": { "$ref": "#/components/schemas/VaultOwnerKind" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "requires_approval": { "$ref": "#/components/schemas/VaultApprovalMode" }, "updated_at": { "type": "string", "format": "date-time" }, "vault_id": { "type": "string", "format": "uuid" }, "vault_key_version": { "type": "integer", "format": "int32", "description": "Monotone counter incremented on every completed key rotation.\nClients echo it on item writes via `wrapping_key_version` to\nguard against rotation races." }, "wrapped_vault_key": { "type": "string", "description": "Present when listing or fetching the vault on behalf of a member." } } }, "AcceptUpdateRequestRequest": { "type": "object", "properties": { "allow_outdated_base": { "type": [ "boolean", "null" ] }, "changelog": { "type": [ "string", "null" ] }, "expected_current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "manifest": {}, "publish_version": { "type": [ "string", "null" ] } } }, "AuthorIdentity": { "type": "object", "required": [ "user_id", "display_name", "git_email", "updated_at" ], "properties": { "display_name": { "type": "string" }, "git_email": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "BundleFileInput": { "type": "object", "description": "Bundle delta entry on a `CreateVersionRequest`. Path is POSIX,\nrelative to the bundle root, never `SKILL.md` (which is the canonical\nMarkdown column). `content_b64` is base64 of the raw file bytes so\nbinary payloads survive a JSON round-trip; `mode` defaults to 0o100644\n(0o100755 for files under `scripts/`); `deleted: true` drops the\nmatching path from the new version instead of inserting bytes.", "required": [ "path" ], "properties": { "content_b64": { "type": [ "string", "null" ], "description": "Required unless `deleted` is true." }, "deleted": { "type": "boolean" }, "mode": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional file mode in Git tree mode bits. Defaults to 0o100644.", "minimum": 0 }, "path": { "type": "string" } } }, "ChatDraftResponse": { "type": "object", "required": [ "id", "skill_id", "editor_user_id", "session_id", "base_version_id", "status", "created_at", "updated_at" ], "properties": { "base_version_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "editor_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Collaborator": { "type": "object", "required": [ "skill_id", "user_id", "role", "granted_by_user_id", "granted_at" ], "properties": { "granted_at": { "type": "string", "format": "date-time" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "CreateCommentRequest": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" } } }, "CreateSkillRequest": { "type": "object", "required": [ "slug", "name", "description", "visibility" ], "properties": { "changelog": { "type": [ "string", "null" ] }, "content_doc": {}, "description": { "type": "string" }, "discoverability": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillDiscoverability" } ] }, "files": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BundleFileInput" }, "description": "Optional initial bundle files for the seed version. The first\nversion has no prior carry-over, so these are inserted as the\nentire non-SKILL.md bundle." }, "frontmatter": {}, "manifest": {}, "name": { "type": "string" }, "owner_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillOwnerKind" } ] }, "price_cents": { "type": [ "integer", "null" ], "format": "int32" }, "publish_now": { "type": [ "boolean", "null" ] }, "skill_folder_name": { "type": [ "string", "null" ] }, "skill_md": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "sponsor_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillSponsorMode" } ] }, "sponsor_static": {}, "version": { "type": [ "string", "null" ] }, "visibility": { "$ref": "#/components/schemas/SkillVisibility" } } }, "CreateUpdateRequest": { "type": "object", "required": [ "title", "body" ], "properties": { "body": { "type": "string" }, "proposed_content_doc": {}, "proposed_frontmatter": {}, "proposed_skill_md": { "type": [ "string", "null" ] }, "title": { "type": "string" } } }, "CreateVersionRequest": { "type": "object", "required": [ "version" ], "properties": { "changelog": { "type": [ "string", "null" ] }, "content_doc": {}, "expected_current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "files": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BundleFileInput" }, "description": "Optional bundle deltas. Files supplied here are added to or\nreplaced in the new version's bundle. Files from the prior\ncurrent version are otherwise carried forward unchanged. Mark\n`deleted: true` to drop a path; reserve the SKILL.md root path\nfor the canonical Markdown column. See [`BundleFileInput`]." }, "frontmatter": {}, "manifest": {}, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "skill_md": { "type": [ "string", "null" ] }, "version": { "type": "string" } } }, "CreateVersionResponse": { "type": "object", "required": [ "status" ], "properties": { "draft": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatDraftResponse" } ] }, "merge_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeStateResponse" } ] }, "status": { "type": "string" }, "version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } }, "DataResponse_AuthorIdentity": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "user_id", "display_name", "git_email", "updated_at" ], "properties": { "display_name": { "type": "string" }, "git_email": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_ChatDraftResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "skill_id", "editor_user_id", "session_id", "base_version_id", "status", "created_at", "updated_at" ], "properties": { "base_version_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "editor_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Collaborator": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "skill_id", "user_id", "role", "granted_by_user_id", "granted_at" ], "properties": { "granted_at": { "type": "string", "format": "date-time" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_CreateVersionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "draft": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatDraftResponse" } ] }, "merge_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeStateResponse" } ] }, "status": { "type": "string" }, "version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_FileEditResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Per-file edit response. `unchanged: true` means the resulting\nbundle hash matches the current version's `content_hash_bundle`\nand no new version was written; `version` then carries the\nexisting current version. On conflict, `status = \"conflict\"` and\n`draft` + `merge_state` come from the standard chat-conflict\npipeline reused from `create_version`.", "required": [ "status", "unchanged" ], "properties": { "draft": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatDraftResponse" } ] }, "merge_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeStateResponse" } ] }, "status": { "type": "string" }, "unchanged": { "type": "boolean" }, "version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_GetFileResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "`GET /skills/{slug}/files/{path...}` response: one file's bytes.", "required": [ "path", "content_b64", "mode", "is_binary", "content_hash" ], "properties": { "content_b64": { "type": "string" }, "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "version": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_MergeStateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "skill_id", "editor_user_id", "base_version_id", "incoming_version_id", "conflict_count", "merged_skill_md", "merged_content_doc", "created_at" ], "properties": { "base_version_id": { "type": "string", "format": "uuid" }, "chat_draft_id": { "type": [ "string", "null" ], "format": "uuid" }, "conflict_count": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "editor_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "incoming_version_id": { "type": "string", "format": "uuid" }, "merged_content_doc": {}, "merged_skill_md": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "skill_id": { "type": "string", "format": "uuid" }, "update_request_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_OrphanFoldersResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "head_commit_sha", "head_tree_sha", "orphan_folders" ], "properties": { "head_commit_sha": { "type": "string" }, "head_tree_sha": { "type": "string" }, "orphan_folders": { "type": "array", "items": { "$ref": "#/components/schemas/OrphanFolderEntry" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_PurchaseResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "skill_id", "access_granted", "source" ], "properties": { "access_granted": { "type": "boolean" }, "charge_id": { "type": [ "string", "null" ], "format": "uuid" }, "purchase_id": { "type": [ "string", "null" ], "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "source": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillAgentGrant": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "skill_id", "skill_version_id", "agent_identity_id", "allowed_task_labels", "grant_generation", "granted_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "grant_generation": { "type": "integer", "format": "int64" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "skill_version_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillBundle": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "skill", "version", "skill_md", "manifest", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "content_hash_bundle": { "type": "string", "description": "Full-bundle freshness token (issue #57): hex of the version's\n`content_hash_bundle`, the SHA-256 fingerprint over SKILL.md **and\nevery file's bytes** ([`crate::content::compute_content_hash_bundle`]).\nUnlike `content_hash` (SKILL.md + manifest only), this moves on any\nfile-body change, so installs must key their sync-revision compare on\nthis field — not `content_hash` — to detect code-only updates.\nEmpty only for the impossible case of a version predating migration\n010, which made the column `NOT NULL`." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillBundleFile" }, "description": "Non-SKILL.md files attached to the version. Empty for versions that\npredate bundle persistence." }, "manifest": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "skill_md": { "type": "string" }, "version": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillBundleFileDownload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Single-file body returned by `GET /skills/{slug}/download/file`.\nShares the [`SkillBundleFile`] field shape (path + base64 body +\nper-file hash + mode + is_binary) and adds the bundle `version` so a\nclient can detect a publish that landed between its manifest fetch\nand this body fetch (version mismatch -> restart from the manifest).", "required": [ "path", "content_b64", "content_hash", "mode", "is_binary", "version" ], "properties": { "content_b64": { "type": "string" }, "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "version": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillBundleManifest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Split-download manifest (issue #53): the same envelope as\n[`SkillBundle`] but every entry in `files` carries *metadata only* —\nno `content_b64` body. Clients fetch each body separately via\n`GET /skills/{slug}/download/file?path=...`, keeping every response\nunder the gateway's per-response byte cap even for bundles whose\nsingle-shot `/download` JSON would exceed it.", "required": [ "skill", "version", "skill_md", "manifest", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "content_hash_bundle": { "type": "string", "description": "Full-bundle freshness token (issue #57): hex of the version's\n`content_hash_bundle`. Identical semantics to [`SkillBundle::content_hash_bundle`]\n— the split-download client keys its sync-revision compare on this\nfield so a code-only publish (SKILL.md/manifest unchanged) is detected." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillBundleManifestFile" }, "description": "Per-file metadata with no bodies. Empty for versions that predate\nbundle persistence." }, "manifest": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "skill_md": { "type": "string" }, "version": { "type": "string" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillDetail": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/SkillSummary" }, { "type": "object", "required": [ "access" ], "properties": { "access": { "$ref": "#/components/schemas/SkillAccess" }, "latest_version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } } ] }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SkillEditDocument": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Editor-facing payload: ProseMirror document tree for the rich-text editor\nplus the parsed frontmatter as JSON. Returned by GET /skills/{slug}/edit\nand accepted by POST /skills/{slug}/versions when a client wants to write\nthe document directly instead of round-tripping through markdown.", "required": [ "skill", "frontmatter", "content_doc" ], "properties": { "content_doc": {}, "content_hash": { "type": [ "string", "null" ] }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "frontmatter": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "version": { "type": [ "string", "null" ] } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_UpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "skill_id", "proposer_user_id", "title", "body", "status", "created_at", "updated_at" ], "properties": { "base_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "proposed_content_hash": { "type": [ "string", "null" ] }, "proposer_user_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_UpdateRequestDetail": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/UpdateRequest" }, { "type": "object", "required": [ "skill" ], "properties": { "base_version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] }, "proposed_content_doc": {}, "proposed_frontmatter": {}, "proposed_skill_md": { "type": [ "string", "null" ] }, "skill": { "$ref": "#/components/schemas/SkillSummary" } } } ] }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_UpdateRequestDiff": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "request_id", "is_outdated" ], "properties": { "base_skill_md": { "type": [ "string", "null" ] }, "base_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_outdated": { "type": "boolean" }, "proposed_skill_md": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "format": "uuid" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_UsageSummaryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "month", "rows", "total_amount_atomic", "note" ], "properties": { "month": { "type": "string" }, "note": { "type": "string" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/UsageSummaryRow" } }, "total_amount_atomic": { "type": "integer", "format": "int64" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_Collaborator": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "skill_id", "user_id", "role", "granted_by_user_id", "granted_at" ], "properties": { "granted_at": { "type": "string", "format": "date-time" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_FileListing": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One row in the file listing. `preview` is the first 200 chars of the\nfile when it is text; `null` for binaries.", "required": [ "path", "mode", "is_binary", "size_bytes", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "preview": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer", "format": "int64" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_SkillAgentGrant": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "skill_id", "skill_version_id", "agent_identity_id", "allowed_task_labels", "grant_generation", "granted_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "grant_generation": { "type": "integer", "format": "int64" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "skill_version_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_SkillSummary": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "owner_kind", "slug", "skill_folder_name", "name", "description", "visibility", "discoverability", "status", "sponsor_mode", "price_cents", "install_count", "owner_organization_id", "created_by_user_id", "github_mirror_health", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "current_version": { "type": [ "string", "null" ] }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": "string" }, "discoverability": { "$ref": "#/components/schemas/SkillDiscoverability" }, "folder_slug": { "type": [ "string", "null" ], "description": "Per-skill override for the GitHub mirror folder. When set, takes\nprecedence over `skill_org_folders.folder_slug`. `None` means\nfall through to the org default. See migration 009 + issue #17." }, "github_mirror_health": { "$ref": "#/components/schemas/GithubMirrorHealth" }, "id": { "type": "string", "format": "uuid" }, "install_count": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "owner_kind": { "$ref": "#/components/schemas/SkillOwnerKind" }, "owner_organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "price_cents": { "type": "integer", "format": "int32" }, "seren_bounty_campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "skill_folder_name": { "type": "string" }, "slug": { "type": "string" }, "sponsor_mode": { "$ref": "#/components/schemas/SkillSponsorMode" }, "sponsor_referral_code": { "type": [ "string", "null" ] }, "sponsor_static": {}, "status": { "$ref": "#/components/schemas/SkillStatus" }, "tags": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" }, "visibility": { "$ref": "#/components/schemas/SkillVisibility" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_SkillVersion": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "skill_id", "version", "manifest", "content_hash", "review_status", "created_by_user_id", "created_at" ], "properties": { "changelog": { "type": [ "string", "null" ] }, "content_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "manifest": {}, "review_status": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "version": { "type": "string" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_UpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "skill_id", "proposer_user_id", "title", "body", "status", "created_at", "updated_at" ], "properties": { "base_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "proposed_content_hash": { "type": [ "string", "null" ] }, "proposer_user_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_UpdateRequestComment": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "request_id", "author_user_id", "body", "created_at" ], "properties": { "author_user_id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_UsageEvent": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "organization_id", "event_type", "units", "amount_atomic", "billing_status", "created_at" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "billing_charge_id": { "type": [ "string", "null" ], "format": "uuid" }, "billing_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": [ "string", "null" ], "format": "uuid" }, "units": { "type": "integer", "format": "int32" }, "user_id": { "type": "string", "format": "uuid" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DeleteFileRequest": { "type": "object", "description": "`DELETE /skills/{slug}/files/{path...}` body.", "required": [ "expected_current_version_id" ], "properties": { "expected_current_version_id": { "type": "string", "format": "uuid" }, "version_label": { "type": [ "string", "null" ] } } }, "FileEditResponse": { "type": "object", "description": "Per-file edit response. `unchanged: true` means the resulting\nbundle hash matches the current version's `content_hash_bundle`\nand no new version was written; `version` then carries the\nexisting current version. On conflict, `status = \"conflict\"` and\n`draft` + `merge_state` come from the standard chat-conflict\npipeline reused from `create_version`.", "required": [ "status", "unchanged" ], "properties": { "draft": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatDraftResponse" } ] }, "merge_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MergeStateResponse" } ] }, "status": { "type": "string" }, "unchanged": { "type": "boolean" }, "version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } }, "FileListing": { "type": "object", "description": "One row in the file listing. `preview` is the first 200 chars of the\nfile when it is text; `null` for binaries.", "required": [ "path", "mode", "is_binary", "size_bytes", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "preview": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer", "format": "int64" } } }, "GetFileResponse": { "type": "object", "description": "`GET /skills/{slug}/files/{path...}` response: one file's bytes.", "required": [ "path", "content_b64", "mode", "is_binary", "content_hash" ], "properties": { "content_b64": { "type": "string" }, "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "version": { "type": [ "string", "null" ] } } }, "GithubMirrorHealth": { "type": "string", "description": "Health of the GitHub mirror for a public/paid skill, as observed by\nthe forward-publish worker. Surfaced on `SkillSummary` so owners see\na broken mirror without a separate `/skills/{slug}/github` lookup.\n\n- `Pending`: row not yet attempted, or the skill is private and the\n mirror is intentionally inactive. Default for new skills.\n- `Healthy`: most recent terminal worker outcome was a successful\n push.\n- `Degraded`: reserved for partial-push or transient-failure flows;\n not currently emitted by the worker but defined so the column is\n future-proof against a finer-grained health model.\n- `Failed`: most recent terminal worker outcome exhausted retries\n without pushing. Owner action required.", "enum": [ "pending", "healthy", "degraded", "failed" ] }, "GithubPublishStatusResponse": { "type": "object", "required": [ "skill_id", "version_id", "folder_slug", "skill_folder_name", "status", "resolved_via" ], "properties": { "commit_sha": { "type": [ "string", "null" ] }, "folder_slug": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "resolved_via": { "type": "string", "description": "Source that supplied `folder_slug` at enqueue time.\n`\"skill\"` -> per-skill override (`skills.folder_slug`).\n`\"organization\"` -> org default (`skill_org_folders.folder_slug`).\nPinned at enqueue rather than recomputed on read because both\nunderlying values can drift after the publish row is written." }, "skill_folder_name": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "version_id": { "type": "string", "format": "uuid" } } }, "ListSkillsQuery": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64" }, "mine": { "type": [ "boolean", "null" ] }, "offset": { "type": [ "integer", "null" ], "format": "int64" }, "q": { "type": [ "string", "null" ] }, "sort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ListSkillsSort" } ] }, "visibility": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVisibility" } ] } } }, "ListSkillsSort": { "type": "string", "enum": [ "updated", "installs" ] }, "MergeStateResponse": { "type": "object", "required": [ "id", "skill_id", "editor_user_id", "base_version_id", "incoming_version_id", "conflict_count", "merged_skill_md", "merged_content_doc", "created_at" ], "properties": { "base_version_id": { "type": "string", "format": "uuid" }, "chat_draft_id": { "type": [ "string", "null" ], "format": "uuid" }, "conflict_count": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "editor_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "incoming_version_id": { "type": "string", "format": "uuid" }, "merged_content_doc": {}, "merged_skill_md": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "skill_id": { "type": "string", "format": "uuid" }, "update_request_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "OrphanFolderEntry": { "type": "object", "required": [ "folder_slug", "skill_folder_name", "paths" ], "properties": { "folder_slug": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Every blob path at depth ≥ 3 under `//`.\nSorted, deduped. Empty `paths` cannot occur — the entry only\nexists because at least one path matched." }, "skill_folder_name": { "type": "string" } } }, "OrphanFoldersResponse": { "type": "object", "required": [ "head_commit_sha", "head_tree_sha", "orphan_folders" ], "properties": { "head_commit_sha": { "type": "string" }, "head_tree_sha": { "type": "string" }, "orphan_folders": { "type": "array", "items": { "$ref": "#/components/schemas/OrphanFolderEntry" } } } }, "PurchaseResponse": { "type": "object", "required": [ "skill_id", "access_granted", "source" ], "properties": { "access_granted": { "type": "boolean" }, "charge_id": { "type": [ "string", "null" ], "format": "uuid" }, "purchase_id": { "type": [ "string", "null" ], "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "source": { "type": "string" } } }, "PutFileRequest": { "type": "object", "description": "`PUT /skills/{slug}/files/{path...}` body. `expected_content_hash`\nis the per-file hex SHA from `GET /files`; it is an *optional*\npre-flight check that fails fast (409) before the version write.\n`expected_current_version_id` is forwarded to `create_version`'s\nexisting conflict-draft path -- mismatch returns 409 with a chat\ndraft + merge-state pointer.", "required": [ "content_b64", "expected_current_version_id" ], "properties": { "content_b64": { "type": "string" }, "expected_content_hash": { "type": [ "string", "null" ] }, "expected_current_version_id": { "type": "string", "format": "uuid" }, "mode": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "version_label": { "type": [ "string", "null" ], "description": "Optional override for the auto-synthesised\n`file-edit-` version label." } } }, "ReconcileOrphansRequest": { "type": "object", "description": "Body of `POST /skills/{slug}/github/reconcile-orphans`.", "properties": { "confirm": { "type": "boolean", "description": "Must be `true` -- the handler 409s on `false` or missing. The\nguard exists so a misconfigured CLI/script cannot quietly\ndelete canonical-repo paths." }, "dry_run": { "type": "boolean", "description": "When true, the handler returns the planned commit shape\nwithout touching GitHub. The audit row is still recorded so\nthe operator's preview is auditable." }, "expected_orphan_paths": { "type": "array", "items": { "type": "string" }, "description": "The orphan-path set the operator computed (e.g. via the\n`reconcile_canonical_repo` binary). The handler 409s if the\nlive set against canonical HEAD has diverged." }, "reason": { "type": [ "string", "null" ], "description": "Optional free-text reason (recorded on the audit row)." } } }, "ResolveConflictRequest": { "type": "object", "required": [ "resolution_strategy" ], "properties": { "changelog": { "type": [ "string", "null" ] }, "content_doc": {}, "frontmatter": {}, "manifest": {}, "resolution_strategy": { "type": "string" }, "skill_md": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] } } }, "SkillAccess": { "type": "object", "required": [ "can_view", "can_download", "can_manage", "reason" ], "properties": { "can_download": { "type": "boolean" }, "can_manage": { "type": "boolean" }, "can_view": { "type": "boolean" }, "reason": { "type": "string" } } }, "SkillAgentGrant": { "type": "object", "required": [ "id", "organization_id", "skill_id", "skill_version_id", "agent_identity_id", "allowed_task_labels", "grant_generation", "granted_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "grant_generation": { "type": "integer", "format": "int64" }, "granted_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "skill_version_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SkillBundle": { "type": "object", "required": [ "skill", "version", "skill_md", "manifest", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "content_hash_bundle": { "type": "string", "description": "Full-bundle freshness token (issue #57): hex of the version's\n`content_hash_bundle`, the SHA-256 fingerprint over SKILL.md **and\nevery file's bytes** ([`crate::content::compute_content_hash_bundle`]).\nUnlike `content_hash` (SKILL.md + manifest only), this moves on any\nfile-body change, so installs must key their sync-revision compare on\nthis field — not `content_hash` — to detect code-only updates.\nEmpty only for the impossible case of a version predating migration\n010, which made the column `NOT NULL`." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillBundleFile" }, "description": "Non-SKILL.md files attached to the version. Empty for versions that\npredate bundle persistence." }, "manifest": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "skill_md": { "type": "string" }, "version": { "type": "string" } } }, "SkillBundleFile": { "type": "object", "required": [ "path", "content_b64", "content_hash", "mode", "is_binary" ], "properties": { "content_b64": { "type": "string" }, "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" } } }, "SkillBundleFileDownload": { "type": "object", "description": "Single-file body returned by `GET /skills/{slug}/download/file`.\nShares the [`SkillBundleFile`] field shape (path + base64 body +\nper-file hash + mode + is_binary) and adds the bundle `version` so a\nclient can detect a publish that landed between its manifest fetch\nand this body fetch (version mismatch -> restart from the manifest).", "required": [ "path", "content_b64", "content_hash", "mode", "is_binary", "version" ], "properties": { "content_b64": { "type": "string" }, "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "version": { "type": "string" } } }, "SkillBundleManifest": { "type": "object", "description": "Split-download manifest (issue #53): the same envelope as\n[`SkillBundle`] but every entry in `files` carries *metadata only* —\nno `content_b64` body. Clients fetch each body separately via\n`GET /skills/{slug}/download/file?path=...`, keeping every response\nunder the gateway's per-response byte cap even for bundles whose\nsingle-shot `/download` JSON would exceed it.", "required": [ "skill", "version", "skill_md", "manifest", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "content_hash_bundle": { "type": "string", "description": "Full-bundle freshness token (issue #57): hex of the version's\n`content_hash_bundle`. Identical semantics to [`SkillBundle::content_hash_bundle`]\n— the split-download client keys its sync-revision compare on this\nfield so a code-only publish (SKILL.md/manifest unchanged) is detected." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillBundleManifestFile" }, "description": "Per-file metadata with no bodies. Empty for versions that predate\nbundle persistence." }, "manifest": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "skill_md": { "type": "string" }, "version": { "type": "string" } } }, "SkillBundleManifestFile": { "type": "object", "description": "Body-less per-file metadata returned in a [`SkillBundleManifest`].\n`size_bytes` is the raw (pre-base64) byte length so clients can show\nprogress and pre-size buffers before fetching each body.", "required": [ "path", "content_hash", "mode", "is_binary", "size_bytes" ], "properties": { "content_hash": { "type": "string" }, "is_binary": { "type": "boolean" }, "mode": { "type": "integer", "format": "int32", "minimum": 0 }, "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "SkillContentInput": { "type": "object", "description": "One of `skill_md` (markdown body, server parses to ProseMirror) or\n`content_doc` + `frontmatter` (editor-native: server renders markdown\nfrom the doc and stores both). Exactly one branch must be provided.", "properties": { "content_doc": {}, "frontmatter": {}, "skill_md": { "type": [ "string", "null" ] } } }, "SkillDetail": { "allOf": [ { "$ref": "#/components/schemas/SkillSummary" }, { "type": "object", "required": [ "access" ], "properties": { "access": { "$ref": "#/components/schemas/SkillAccess" }, "latest_version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] } } } ] }, "SkillDiscoverability": { "type": "string", "enum": [ "listed", "unlisted" ] }, "SkillEditDocument": { "type": "object", "description": "Editor-facing payload: ProseMirror document tree for the rich-text editor\nplus the parsed frontmatter as JSON. Returned by GET /skills/{slug}/edit\nand accepted by POST /skills/{slug}/versions when a client wants to write\nthe document directly instead of round-tripping through markdown.", "required": [ "skill", "frontmatter", "content_doc" ], "properties": { "content_doc": {}, "content_hash": { "type": [ "string", "null" ] }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "frontmatter": {}, "skill": { "$ref": "#/components/schemas/SkillSummary" }, "version": { "type": [ "string", "null" ] } } }, "SkillOwnerKind": { "type": "string", "enum": [ "user", "organization" ] }, "SkillSponsorMode": { "type": "string", "enum": [ "skip", "static", "seren_bounty" ] }, "SkillStatus": { "type": "string", "enum": [ "draft", "published", "suspended", "deleted" ] }, "SkillSummary": { "type": "object", "required": [ "id", "owner_kind", "slug", "skill_folder_name", "name", "description", "visibility", "discoverability", "status", "sponsor_mode", "price_cents", "install_count", "owner_organization_id", "created_by_user_id", "github_mirror_health", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "current_version": { "type": [ "string", "null" ] }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": "string" }, "discoverability": { "$ref": "#/components/schemas/SkillDiscoverability" }, "folder_slug": { "type": [ "string", "null" ], "description": "Per-skill override for the GitHub mirror folder. When set, takes\nprecedence over `skill_org_folders.folder_slug`. `None` means\nfall through to the org default. See migration 009 + issue #17." }, "github_mirror_health": { "$ref": "#/components/schemas/GithubMirrorHealth" }, "id": { "type": "string", "format": "uuid" }, "install_count": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "owner_kind": { "$ref": "#/components/schemas/SkillOwnerKind" }, "owner_organization_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "price_cents": { "type": "integer", "format": "int32" }, "seren_bounty_campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "skill_folder_name": { "type": "string" }, "slug": { "type": "string" }, "sponsor_mode": { "$ref": "#/components/schemas/SkillSponsorMode" }, "sponsor_referral_code": { "type": [ "string", "null" ] }, "sponsor_static": {}, "status": { "$ref": "#/components/schemas/SkillStatus" }, "tags": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" }, "visibility": { "$ref": "#/components/schemas/SkillVisibility" } } }, "SkillVersion": { "type": "object", "required": [ "id", "skill_id", "version", "manifest", "content_hash", "review_status", "created_by_user_id", "created_at" ], "properties": { "changelog": { "type": [ "string", "null" ] }, "content_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "manifest": {}, "review_status": { "type": "string" }, "skill_id": { "type": "string", "format": "uuid" }, "version": { "type": "string" } } }, "SkillVisibility": { "type": "string", "enum": [ "private", "public", "paid" ] }, "TransferOrgFolderRequest": { "type": "object", "required": [ "folder_slug" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "folder_slug": { "type": "string" } } }, "UpdateRequest": { "type": "object", "required": [ "id", "skill_id", "proposer_user_id", "title", "body", "status", "created_at", "updated_at" ], "properties": { "base_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "proposed_content_hash": { "type": [ "string", "null" ] }, "proposer_user_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UpdateRequestComment": { "type": "object", "required": [ "id", "request_id", "author_user_id", "body", "created_at" ], "properties": { "author_user_id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" } } }, "UpdateRequestDetail": { "allOf": [ { "$ref": "#/components/schemas/UpdateRequest" }, { "type": "object", "required": [ "skill" ], "properties": { "base_version": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVersion" } ] }, "proposed_content_doc": {}, "proposed_frontmatter": {}, "proposed_skill_md": { "type": [ "string", "null" ] }, "skill": { "$ref": "#/components/schemas/SkillSummary" } } } ] }, "UpdateRequestDiff": { "type": "object", "required": [ "request_id", "is_outdated" ], "properties": { "base_skill_md": { "type": [ "string", "null" ] }, "base_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_outdated": { "type": "boolean" }, "proposed_skill_md": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "format": "uuid" } } }, "UpdateSkillRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "discoverability": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillDiscoverability" } ] }, "folder_slug": { "type": [ "string", "null" ], "description": "Per-skill GitHub mirror folder override. Three-state field:\nfield absent → no change; explicit `null` → clear the override\n(fall back to org default); string → set the override.\nSee issue #17." }, "name": { "type": [ "string", "null" ] }, "price_cents": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillStatus" } ] }, "visibility": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillVisibility" } ] } } }, "UpdateSponsorRequest": { "type": "object", "required": [ "sponsor_mode" ], "properties": { "sponsor_mode": { "$ref": "#/components/schemas/SkillSponsorMode" }, "sponsor_static": {} } }, "UpsertAuthorIdentityRequest": { "type": "object", "required": [ "display_name", "git_email" ], "properties": { "display_name": { "type": "string" }, "git_email": { "type": "string" } } }, "UpsertCollaboratorRequest": { "type": "object", "required": [ "user_id", "role" ], "properties": { "role": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, "UpsertOrgFolderRequest": { "type": "object", "required": [ "folder_slug" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "folder_slug": { "type": "string" } } }, "UpsertSkillAgentGrantRequest": { "type": "object", "required": [ "skill_version_id" ], "properties": { "allowed_task_labels": { "type": "array", "items": { "type": "string" } }, "expected_grant_generation": { "type": [ "integer", "null" ], "format": "int64", "description": "Generation observed by the caller when changing an existing grant.\nOmit only when creating a grant that does not yet exist." }, "skill_version_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "UsageEvent": { "type": "object", "required": [ "id", "user_id", "organization_id", "event_type", "units", "amount_atomic", "billing_status", "created_at" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "billing_charge_id": { "type": [ "string", "null" ], "format": "uuid" }, "billing_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "skill_id": { "type": [ "string", "null" ], "format": "uuid" }, "units": { "type": "integer", "format": "int32" }, "user_id": { "type": "string", "format": "uuid" } } }, "UsageSummaryResponse": { "type": "object", "required": [ "month", "rows", "total_amount_atomic", "note" ], "properties": { "month": { "type": "string" }, "note": { "type": "string" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/UsageSummaryRow" } }, "total_amount_atomic": { "type": "integer", "format": "int64" } } }, "UsageSummaryRow": { "type": "object", "required": [ "event_type", "units", "amount_atomic" ], "properties": { "amount_atomic": { "type": "integer", "format": "int64" }, "event_type": { "type": "string" }, "units": { "type": "integer", "format": "int64" } } }, "AddTagsRequest": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } } } }, "AppendToNoteRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "format": { "$ref": "#/components/schemas/NoteFormat" }, "idempotency_key": { "type": [ "string", "null" ] } } }, "Attachment": { "type": "object", "description": "An attachment record", "required": [ "id", "note_id", "filename", "content_type", "size_bytes", "content_hash", "created_at", "updated_at" ], "properties": { "alt_text": { "type": [ "string", "null" ] }, "content_hash": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "filename": { "type": "string" }, "height": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "note_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "width": { "type": [ "integer", "null" ], "format": "int32" } } }, "CreateNoteRequest": { "type": "object", "required": [ "title", "content" ], "properties": { "content": { "type": "string" }, "format": { "$ref": "#/components/schemas/NoteFormat" }, "idempotency_key": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "title": { "type": "string" } } }, "CreateShareApiRequest": { "type": "object", "description": "Request to create a share", "required": [ "note_id" ], "properties": { "allow_anonymous": { "type": [ "boolean", "null" ] }, "expires_in_days": { "type": [ "integer", "null" ], "format": "int32" }, "is_public": { "type": [ "boolean", "null" ] }, "note_id": { "type": "string", "format": "uuid" }, "permission": { "type": [ "string", "null" ] }, "shared_with_email": { "type": [ "string", "null" ] } } }, "DataResponse_Attachment": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "An attachment record", "required": [ "id", "note_id", "filename", "content_type", "size_bytes", "content_hash", "created_at", "updated_at" ], "properties": { "alt_text": { "type": [ "string", "null" ] }, "content_hash": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "filename": { "type": "string" }, "height": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "note_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "width": { "type": [ "integer", "null" ], "format": "int32" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_NoteResponse": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response type for note retrieval with converted content", "required": [ "id", "title", "content", "format", "position", "is_archived", "is_pinned", "tags", "version", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": "string", "description": "Content in the requested format (markdown, org, or JSON string)" }, "content_json": { "description": "Raw ProseMirror JSON (only included when format is Json)" }, "created_at": { "type": "string", "format": "date-time" }, "format": { "$ref": "#/components/schemas/NoteFormat" }, "id": { "type": "string", "format": "uuid" }, "is_archived": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer", "format": "int32" }, "tags": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_NoteShare": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "A share record for a note", "required": [ "id", "note_id", "permission", "is_public", "allow_anonymous", "access_count", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "allow_anonymous": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_public": { "type": "boolean" }, "last_accessed_at": { "type": [ "string", "null" ], "format": "date-time" }, "note_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenNotesPermission" }, "share_token": { "type": [ "string", "null" ] }, "shared_with_email": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_SharedNoteResponse": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Response for publicly shared note content", "required": [ "share", "note" ], "properties": { "note": { "$ref": "#/components/schemas/NoteResponse" }, "share": { "$ref": "#/components/schemas/NoteShare" } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_Attachment": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An attachment record", "required": [ "id", "note_id", "filename", "content_type", "size_bytes", "content_hash", "created_at", "updated_at" ], "properties": { "alt_text": { "type": [ "string", "null" ] }, "content_hash": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "filename": { "type": "string" }, "height": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "note_id": { "type": "string", "format": "uuid" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "width": { "type": [ "integer", "null" ], "format": "int32" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_NoteShare": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A share record for a note", "required": [ "id", "note_id", "permission", "is_public", "allow_anonymous", "access_count", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "allow_anonymous": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_public": { "type": "boolean" }, "last_accessed_at": { "type": [ "string", "null" ], "format": "date-time" }, "note_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenNotesPermission" }, "share_token": { "type": [ "string", "null" ] }, "shared_with_email": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_NoteSummary": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Note summary for list/search responses (without full content)", "required": [ "id", "title", "excerpt", "is_archived", "is_pinned", "version", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "excerpt": { "type": "string", "description": "First ~200 characters of content_text" }, "id": { "type": "string", "format": "uuid" }, "is_archived": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "DataResponse_Vec_SemanticSearchResultResponse": { "type": "object", "description": "Wrapper for API responses.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "note", "similarity" ], "properties": { "note": { "$ref": "#/components/schemas/NoteSummary" }, "similarity": { "type": "number", "format": "float" } } } }, "pagination": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaginationMeta" } ] } } }, "GetNoteQuery": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/NoteFormat" } } }, "ImportAttachmentFromUrlRequest": { "type": "object", "description": "Request body for importing an external image URL as an attachment", "required": [ "url" ], "properties": { "alt_text": { "type": [ "string", "null" ], "description": "Optional alt text for accessibility (stored on the attachment record)" }, "filename": { "type": [ "string", "null" ], "description": "Optional filename override" }, "url": { "type": "string", "description": "External URL to fetch (http/https only)" } } }, "ListNotesQuery": { "type": "object", "description": "Query parameters for listing notes", "properties": { "include_archived": { "type": [ "boolean", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "int64" }, "offset": { "type": [ "integer", "null" ], "format": "int64" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "tag": { "type": [ "string", "null" ] } } }, "NoteFormat": { "type": "string", "description": "Note format for input/output", "enum": [ "markdown", "json", "org" ] }, "NoteResponse": { "type": "object", "description": "Response type for note retrieval with converted content", "required": [ "id", "title", "content", "format", "position", "is_archived", "is_pinned", "tags", "version", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": "string", "description": "Content in the requested format (markdown, org, or JSON string)" }, "content_json": { "description": "Raw ProseMirror JSON (only included when format is Json)" }, "created_at": { "type": "string", "format": "date-time" }, "format": { "$ref": "#/components/schemas/NoteFormat" }, "id": { "type": "string", "format": "uuid" }, "is_archived": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer", "format": "int32" }, "tags": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } }, "NoteShare": { "type": "object", "description": "A share record for a note", "required": [ "id", "note_id", "permission", "is_public", "allow_anonymous", "access_count", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "allow_anonymous": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_public": { "type": "boolean" }, "last_accessed_at": { "type": [ "string", "null" ], "format": "date-time" }, "note_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenNotesPermission" }, "share_token": { "type": [ "string", "null" ] }, "shared_with_email": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "NoteSummary": { "type": "object", "description": "Note summary for list/search responses (without full content)", "required": [ "id", "title", "excerpt", "is_archived", "is_pinned", "version", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "excerpt": { "type": "string", "description": "First ~200 characters of content_text" }, "id": { "type": "string", "format": "uuid" }, "is_archived": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } }, "SerenNotesPermission": { "type": "string", "description": "Permission levels for shared notes", "enum": [ "view", "comment", "edit", "admin" ] }, "RemoveTagsRequest": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } } } }, "SearchNotesQuery": { "type": "object", "description": "Query parameters for searching notes", "required": [ "query" ], "properties": { "include_archived": { "type": [ "boolean", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "int64" }, "offset": { "type": [ "integer", "null" ], "format": "int64" }, "query": { "type": "string" } } }, "SemanticSearchQuery": { "type": "object", "description": "Query parameters for semantic search", "required": [ "embedding" ], "properties": { "embedding": { "type": "string", "description": "The embedding vector as JSON array (1536 dimensions)" }, "include_archived": { "type": "boolean" }, "limit": { "type": "integer", "format": "int32" } } }, "SemanticSearchResultResponse": { "type": "object", "required": [ "note", "similarity" ], "properties": { "note": { "$ref": "#/components/schemas/NoteSummary" }, "similarity": { "type": "number", "format": "float" } } }, "SharedNoteResponse": { "type": "object", "description": "Response for publicly shared note content", "required": [ "share", "note" ], "properties": { "note": { "$ref": "#/components/schemas/NoteResponse" }, "share": { "$ref": "#/components/schemas/NoteShare" } } }, "UpdateAttachmentRequest": { "type": "object", "description": "Request to update attachment metadata", "properties": { "alt_text": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] } } }, "UpdateEmbeddingRequest": { "type": "object", "description": "Request to update note embedding", "required": [ "embedding" ], "properties": { "embedding": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "The embedding vector (1536 dimensions)" } } }, "UpdateNoteRequest": { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "expected_version": { "type": [ "integer", "null" ], "format": "int32" }, "format": { "$ref": "#/components/schemas/NoteFormat" }, "is_archived": { "type": [ "boolean", "null" ] }, "is_pinned": { "type": [ "boolean", "null" ] }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": [ "string", "null" ] } } }, "UpdateShareApiRequest": { "type": "object", "description": "Request to update a share", "properties": { "allow_anonymous": { "type": [ "boolean", "null" ] }, "expires_in_days": { "type": [ "integer", "null" ], "format": "int32" }, "is_public": { "type": [ "boolean", "null" ] }, "permission": { "type": [ "string", "null" ] } } }, "UploadAttachmentRequest": { "type": "object", "description": "Multipart form for uploading attachments (reserved for future multipart upload support)", "required": [ "note_id", "filename", "content_type" ], "properties": { "alt_text": { "type": [ "string", "null" ] }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "height": { "type": [ "integer", "null" ], "format": "int32" }, "note_id": { "type": "string", "format": "uuid" }, "width": { "type": [ "integer", "null" ], "format": "int32" } } }, "SerenMemoryAppendMemoryRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } }, "SerenMemoryCaptureAgentTurnParams": { "type": "object", "description": "Request body for the dedicated agent-capture operation. Requires a stable\nhook-namespace source identity so lifecycle retries stay idempotent.", "required": [ "source_external_id", "agent_platform", "policy_version" ], "properties": { "agent_platform": { "type": "string" }, "assistant_response": { "type": [ "string", "null" ], "description": "Sanitized final assistant content, when organization policy permits response capture." }, "external_parent_session_id": { "type": [ "string", "null" ] }, "external_session_id": { "type": [ "string", "null" ] }, "external_turn_id": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "policy_version": { "type": "string" }, "project_context": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "retain_source": { "type": [ "boolean", "null" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": "string" }, "source_metadata": { "description": "Provenance metadata validated against its own 16,000-byte serialized\nbound. It is not counted against the organization transcript limit." }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "user_prompt": { "type": [ "string", "null" ], "description": "Sanitized user content, when organization policy permits prompt capture." }, "workspace_key": { "type": [ "string", "null" ] }, "workspace_uri": { "type": [ "string", "null" ] } }, "additionalProperties": false, "example": { "user_prompt": "Keep releases reversible.", "assistant_response": "I will add rollback steps.", "agent_platform": "claude", "source_external_id": "hook:agent-turn:claude:conv-1:turn-4", "policy_version": "baseline" } }, "SerenMemoryConflictAction": { "type": "string", "description": "Action determined by the conflict resolution pipeline.", "enum": [ "add", "update", "delete", "noop" ] }, "SerenMemoryConsolidateJobRequest": { "type": "object", "properties": { "project_id": { "type": [ "string", "null" ], "format": "uuid" } }, "example": { "project_id": "123e4567-e89b-12d3-a456-426614174000" } }, "SerenMemoryConsolidateJobResponse": { "type": "object", "required": [ "summaries_created", "memories_consolidated", "stale_deleted" ], "properties": { "memories_consolidated": { "type": "integer", "minimum": 0 }, "stale_deleted": { "type": "integer", "minimum": 0 }, "summaries_created": { "type": "integer", "minimum": 0 } } }, "SerenMemoryConversationSource": { "type": "object", "description": "Metadata envelope for a captured conversation. Raw content lives in an\noptional payload record; `content_retained` reports whether it exists.", "required": [ "id", "user_id", "source_origin", "source_external_id", "conversation_id", "source_metadata", "content_sha256", "content_retained", "created_at", "updated_at" ], "properties": { "agent_platform": { "type": [ "string", "null" ] }, "content_retained": { "type": "boolean" }, "content_sha256": { "type": "string" }, "conversation_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "duplicate_of_source_id": { "type": [ "string", "null" ], "format": "uuid" }, "external_parent_session_id": { "type": [ "string", "null" ] }, "external_session_id": { "type": [ "string", "null" ] }, "external_turn_id": { "type": [ "string", "null" ] }, "extraction_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "policy_version": { "type": [ "string", "null" ] }, "project_context": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": "string" }, "source_metadata": {}, "source_origin": { "$ref": "#/components/schemas/SerenMemorySourceOrigin" }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" }, "workspace_key": { "type": [ "string", "null" ] }, "workspace_uri": { "type": [ "string", "null" ] } } }, "SerenMemoryCreateKnowledgeDomainRequest": { "type": "object", "required": [ "slug", "name", "classification", "visibility" ], "properties": { "classification": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainVisibility" } }, "additionalProperties": false }, "SerenMemoryCreateMigrationRequest": { "type": "object", "required": [ "source_type", "source_instance_id", "plan_hash", "expected_record_count" ], "properties": { "expected_record_count": { "type": "integer", "format": "int64" }, "final_catch_up": { "type": [ "boolean", "null" ] }, "plan_hash": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "series_id": { "type": [ "string", "null" ], "format": "uuid" }, "snapshot_id": { "type": [ "string", "null" ] }, "source_instance_id": { "type": "string" }, "source_type": { "type": "string" } } }, "SerenMemoryDataResponse_ConsolidateJobResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "summaries_created", "memories_consolidated", "stale_deleted" ], "properties": { "memories_consolidated": { "type": "integer", "minimum": 0 }, "stale_deleted": { "type": "integer", "minimum": 0 }, "summaries_created": { "type": "integer", "minimum": 0 } } } } }, "SerenMemoryDataResponse_DeleteBySourceOutcome": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Audit result of erasing retained conversation sources by source identity.", "required": [ "sources_deleted", "memories_deleted" ], "properties": { "memories_deleted": { "type": "integer", "format": "int64", "description": "Derived memory rows permanently removed across the matched sources." }, "sources_deleted": { "type": "integer", "format": "int64", "description": "Retained transcript rows (`memory_conversation_sources`) permanently removed." } } } } }, "SerenMemoryDataResponse_DeleteKnowledgeDomainGrantResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_DeleteKnowledgeRecordResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_DeleteMemoryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_EmbedMigrationRecordsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "embedding_ready", "embedding_pending", "embedding_failed" ], "properties": { "embedding_failed": { "type": "integer", "format": "int64" }, "embedding_pending": { "type": "integer", "format": "int64" }, "embedding_ready": { "type": "integer", "format": "int64" } } } } }, "SerenMemoryDataResponse_ExtractionResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Structured extraction output grouped by memory type.", "properties": { "conversation_source_id": { "type": [ "string", "null" ], "format": "uuid" }, "episodic": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "error_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "preferences": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "procedural": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "semantic": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "stored_memory_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "SerenMemoryDataResponse_ForgetMemoryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "forgotten" ], "properties": { "forgotten": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_HealthResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "server" ], "properties": { "server": { "type": "string" }, "status": { "type": "string" } } } } }, "SerenMemoryDataResponse_ImportRecordsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "imported", "unchanged", "failed", "records" ], "properties": { "failed": { "type": "integer", "format": "int64" }, "imported": { "type": "integer", "format": "int64" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryImportRecordResult" } }, "unchanged": { "type": "integer", "format": "int64" } } } } }, "SerenMemoryDataResponse_IngestDocumentOutput": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "memory_id", "action", "embedding_status", "current_revision" ], "properties": { "action": { "type": "string" }, "current_revision": { "type": "integer", "format": "int64" }, "embedding_status": { "type": "string" }, "memory_id": { "type": "string", "format": "uuid" } } } } }, "SerenMemoryDataResponse_KnowledgeDomainGrantResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "domain_id", "principal_type", "principal_id", "permission" ], "properties": { "domain_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainPermission" }, "principal_id": { "type": "string", "format": "uuid" }, "principal_type": { "$ref": "#/components/schemas/SerenMemoryKnowledgePrincipalType" } } } } }, "SerenMemoryDataResponse_KnowledgeDomainGrantsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainGrantResponse" } } } } } }, "SerenMemoryDataResponse_KnowledgeDomainResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "slug", "name", "classification", "visibility", "is_default" ], "properties": { "classification": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainVisibility" } } } } }, "SerenMemoryDataResponse_KnowledgeDomainsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainResponse" } } } } } }, "SerenMemoryDataResponse_KnowledgeModelConfigurationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "domain_id", "model", "model_hash", "desired_revision", "status" ], "properties": { "applied_revision": { "type": [ "integer", "null" ], "format": "int64" }, "desired_revision": { "type": "integer", "format": "int64" }, "domain_id": { "type": "string", "format": "uuid" }, "model": { "$ref": "#/components/schemas/SerenMemoryKnowledgeModel" }, "model_hash": { "type": "string" }, "status": { "type": "string" } } } } }, "SerenMemoryDataResponse_KnowledgeOperationResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "operation", "knowledge_revision", "count", "items" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "items": {}, "knowledge_revision": { "type": "integer", "format": "int64" }, "operation": { "type": "string" } } } } }, "SerenMemoryDataResponse_KnowledgeOperationsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeOperation" } } } } } }, "SerenMemoryDataResponse_KnowledgeRecordResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "record_key", "payload", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRecord" }, "record_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "SerenMemoryDataResponse_ListKnowledgeRecordsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "records", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRecordResponse" } } } } } }, "SerenMemoryDataResponse_ListMemoriesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "memories", "total", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "total": { "type": "integer", "format": "int64" } } } } }, "SerenMemoryDataResponse_MemoryConnectionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "connected" ], "properties": { "connected": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_MemoryExportResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "schema_version", "generated_at", "memories", "memory_total", "conversation_sources", "conversation_source_total" ], "properties": { "conversation_source_total": { "type": "integer", "format": "int64" }, "conversation_sources": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryConversationSource" } }, "generated_at": { "type": "string", "format": "date-time" }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "memory_total": { "type": "integer", "format": "int64" }, "next_offset": { "type": [ "integer", "null" ], "format": "int64", "description": "Next shared offset while either exported collection has more rows." }, "schema_version": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "SerenMemoryDataResponse_MemoryMigration": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Content-free durable record of an import migration run.", "required": [ "id", "series_id", "user_id", "source_type", "source_instance_id", "plan_hash", "expected_record_count", "final_catch_up", "state", "imported_count", "unchanged_count", "failed_count", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expected_record_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "final_catch_up": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "imported_count": { "type": "integer", "format": "int64" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "plan_hash": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "series_id": { "type": "string", "format": "uuid" }, "snapshot_id": { "type": [ "string", "null" ] }, "source_instance_id": { "type": "string" }, "source_type": { "type": "string" }, "state": { "$ref": "#/components/schemas/SerenMemoryMigrationState" }, "unchanged_count": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } } }, "SerenMemoryDataResponse_MemoryOutput": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "user_id", "memory_type", "content", "metadata", "relevance_score", "access_count", "is_consolidated", "is_pinned", "lifecycle_status", "importance", "current_revision", "embedding_status", "source_kind", "source_managed", "review_status", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "current_revision": { "type": "integer", "format": "int64" }, "embedding_status": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "importance": { "type": "integer", "format": "int32" }, "is_consolidated": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "lifecycle_status": { "type": "string" }, "memory_type": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "relevance_score": { "type": "number", "format": "double" }, "review_status": { "type": "string" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": [ "string", "null" ] }, "source_kind": { "type": "string" }, "source_managed": { "type": "boolean" }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } } }, "SerenMemoryDataResponse_MigrationStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "migration", "attributed_memories", "attributed_sources", "processed_records", "embedding_ready", "embedding_pending", "embedding_failed" ], "properties": { "attributed_memories": { "type": "integer", "format": "int64" }, "attributed_sources": { "type": "integer", "format": "int64" }, "embedding_failed": { "type": "integer", "format": "int64" }, "embedding_pending": { "type": "integer", "format": "int64" }, "embedding_ready": { "type": "integer", "format": "int64" }, "migration": { "$ref": "#/components/schemas/SerenMemoryMemoryMigration" }, "processed_records": { "type": "integer", "format": "int64" } } } } }, "SerenMemoryDataResponse_Option_MemoryOutput": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "id", "user_id", "memory_type", "content", "metadata", "relevance_score", "access_count", "is_consolidated", "is_pinned", "lifecycle_status", "importance", "current_revision", "embedding_status", "source_kind", "source_managed", "review_status", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "current_revision": { "type": "integer", "format": "int64" }, "embedding_status": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "importance": { "type": "integer", "format": "int32" }, "is_consolidated": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "lifecycle_status": { "type": "string" }, "memory_type": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "relevance_score": { "type": "number", "format": "double" }, "review_status": { "type": "string" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": [ "string", "null" ] }, "source_kind": { "type": "string" }, "source_managed": { "type": "boolean" }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } } ] } } }, "SerenMemoryDataResponse_ReadinessResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "reason": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } }, "SerenMemoryDataResponse_RecallResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "memories", "signals" ], "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "signals": { "$ref": "#/components/schemas/SerenMemoryRecallSignalsResponse" } } } } }, "SerenMemoryDataResponse_RememberOutput": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Output from the `remember` operation.", "required": [ "memory_id", "action_taken", "edges_created", "enrichments_triggered" ], "properties": { "action_taken": { "$ref": "#/components/schemas/SerenMemoryConflictAction" }, "edges_created": { "type": "integer", "minimum": 0 }, "enrichments_triggered": { "type": "integer", "minimum": 0 }, "memory_id": { "type": "string", "format": "uuid" }, "reason": { "type": [ "string", "null" ] }, "superseded_memory_id": { "type": [ "string", "null" ], "format": "uuid" } } } } }, "SerenMemoryDataResponse_RollbackMigrationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "removed_memories", "removed_sources" ], "properties": { "removed_memories": { "type": "integer", "format": "int64", "minimum": 0 }, "removed_sources": { "type": "integer", "format": "int64", "minimum": 0 } } } } }, "SerenMemoryDataResponse_SessionContext": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Assembled session context for LLM system prompt injection.", "required": [ "memories_by_type", "total_memories" ], "properties": { "memories_by_type": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "total_memories": { "type": "integer", "minimum": 0 } } } } }, "SerenMemoryDataResponse_SetMemoryReviewResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } }, "SerenMemoryDataResponse_SyncStatus": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "server", "version" ], "properties": { "server": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" } } } } }, "SerenMemoryDataResponse_Vec_MemoryEdge": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Full edge row from the `memory_edges` table.", "required": [ "id", "source_id", "target_id", "edge_type", "weight", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "edge_type": { "$ref": "#/components/schemas/SerenMemoryEdgeType" }, "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "target_id": { "type": "string", "format": "uuid" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" }, "weight": { "type": "number", "format": "double" } } } } } }, "SerenMemoryDataResponse_Vec_MemoryRevision": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "revision", "change_kind", "content", "metadata", "lifecycle_status", "changed_by", "created_at" ], "properties": { "change_kind": { "type": "string" }, "changed_by": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "lifecycle_status": { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" }, "memory_id": { "type": "string", "format": "uuid" }, "metadata": {}, "revision": { "type": "integer", "format": "int64" }, "summary": { "type": [ "string", "null" ] } } } } } }, "SerenMemoryDataResponse_WorkspaceMergePreview": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source_workspace_key", "target_workspace_key", "source_count", "target_count", "shared_external_sessions", "dependent_alias_count", "plan_hash" ], "properties": { "dependent_alias_count": { "type": "integer", "format": "int64" }, "plan_hash": { "type": "string" }, "shared_external_sessions": { "type": "integer", "format": "int64" }, "source_count": { "type": "integer", "format": "int64" }, "source_workspace_key": { "type": "string" }, "target_count": { "type": "integer", "format": "int64" }, "target_workspace_key": { "type": "string" } } } } }, "SerenMemoryDataResponse_WorkspaceMergeResult": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "merge_id", "source_workspace_key", "target_workspace_key", "source_count", "target_count", "shared_external_sessions", "dependent_alias_count", "merged_source_count", "plan_hash", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "dependent_alias_count": { "type": "integer", "format": "int64" }, "merge_id": { "type": "string", "format": "uuid" }, "merged_source_count": { "type": "integer", "format": "int64" }, "plan_hash": { "type": "string" }, "shared_external_sessions": { "type": "integer", "format": "int64" }, "source_count": { "type": "integer", "format": "int64" }, "source_workspace_key": { "type": "string" }, "target_count": { "type": "integer", "format": "int64" }, "target_workspace_key": { "type": "string" } } } } }, "SerenMemoryDeleteBySourceOutcome": { "type": "object", "description": "Audit result of erasing retained conversation sources by source identity.", "required": [ "sources_deleted", "memories_deleted" ], "properties": { "memories_deleted": { "type": "integer", "format": "int64", "description": "Derived memory rows permanently removed across the matched sources." }, "sources_deleted": { "type": "integer", "format": "int64", "description": "Retained transcript rows (`memory_conversation_sources`) permanently removed." } } }, "SerenMemoryDeleteKnowledgeDomainGrantResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "SerenMemoryDeleteKnowledgeRecordResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "SerenMemoryDeleteMemoriesBySourceParams": { "type": "object", "properties": { "org_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Accepted for parity; the authenticated organization is always authoritative." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional narrowing to a single project." }, "source_external_id": { "type": [ "string", "null" ], "description": "Stable per-source identity (e.g. a desktop message URI). Matches one source." }, "source_uri": { "type": [ "string", "null" ], "description": "Source URI. Matches every source sharing it (e.g. a whole conversation)." } } }, "SerenMemoryDeleteMemoryResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "SerenMemoryEdgeType": { "type": "string", "description": "Relationship types between memories in the graph layer.", "enum": [ "relates_to", "derived_from", "contradicts", "supersedes", "enriched_by" ] }, "SerenMemoryEmbedMigrationRecordsRequest": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "maximum": 100, "minimum": 1 } } }, "SerenMemoryEmbedMigrationRecordsResponse": { "type": "object", "required": [ "embedding_ready", "embedding_pending", "embedding_failed" ], "properties": { "embedding_failed": { "type": "integer", "format": "int64" }, "embedding_pending": { "type": "integer", "format": "int64" }, "embedding_ready": { "type": "integer", "format": "int64" } } }, "SerenMemoryEmbeddingStatus": { "type": "string", "description": "State of semantic indexing for a memory.", "enum": [ "pending", "ready", "failed" ] }, "SerenMemoryErrorBody": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "SerenMemoryExecuteWorkspaceMergeRequest": { "type": "object", "required": [ "source_workspace_key", "target_workspace_key", "plan_hash" ], "properties": { "plan_hash": { "type": "string" }, "source_workspace_key": { "type": "string" }, "target_workspace_key": { "type": "string" } } }, "SerenMemoryExtractedMemory": { "type": "object", "description": "A single piece of knowledge extracted from a conversation.", "required": [ "content", "metadata" ], "properties": { "content": { "type": "string" }, "metadata": {} } }, "SerenMemoryExtractionResult": { "type": "object", "description": "Structured extraction output grouped by memory type.", "properties": { "conversation_source_id": { "type": [ "string", "null" ], "format": "uuid" }, "episodic": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "error_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "preferences": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "procedural": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "semantic": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryExtractedMemory" } }, "stored_memory_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "SerenMemoryForgetMemoryResponse": { "type": "object", "required": [ "forgotten" ], "properties": { "forgotten": { "type": "boolean" } } }, "SerenMemoryForgetParams": { "type": "object", "required": [ "memory_id" ], "properties": { "memory_id": { "type": "string", "format": "uuid" } }, "example": { "memory_id": "123e4567-e89b-12d3-a456-426614174000" } }, "SerenMemoryHealthResponse": { "type": "object", "required": [ "status", "server" ], "properties": { "server": { "type": "string" }, "status": { "type": "string" } } }, "SerenMemoryImportRecord": { "type": "object", "description": "One already-extracted record submitted through the import channel.\nImport never runs conversation extraction.", "required": [ "source_external_id", "memory_type", "content" ], "properties": { "agent_platform": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "external_parent_session_id": { "type": [ "string", "null" ] }, "external_session_id": { "type": [ "string", "null" ] }, "external_turn_id": { "type": [ "string", "null" ] }, "memory_type": { "$ref": "#/components/schemas/SerenMemoryMemoryType" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "project": { "type": [ "string", "null" ] }, "source_external_id": { "type": "string" }, "source_metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "source_record_type": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "workspace_key": { "type": [ "string", "null" ] }, "workspace_uri": { "type": [ "string", "null" ] } } }, "SerenMemoryImportRecordResult": { "type": "object", "required": [ "record_index", "source_external_id", "status" ], "properties": { "conversation_source_id": { "type": [ "string", "null" ], "format": "uuid" }, "error": { "type": [ "string", "null" ] }, "memory_id": { "type": [ "string", "null" ], "format": "uuid" }, "record_index": { "type": "integer", "minimum": 0 }, "source_external_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/SerenMemoryImportRecordStatus" } } }, "SerenMemoryImportRecordStatus": { "type": "string", "enum": [ "imported", "unchanged", "failed" ] }, "SerenMemoryImportRecordsRequest": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryImportRecord" } } } }, "SerenMemoryImportRecordsResponse": { "type": "object", "required": [ "imported", "unchanged", "failed", "records" ], "properties": { "failed": { "type": "integer", "format": "int64" }, "imported": { "type": "integer", "format": "int64" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryImportRecordResult" } }, "unchanged": { "type": "integer", "format": "int64" } } }, "SerenMemoryIngestDocumentOutput": { "type": "object", "required": [ "memory_id", "action", "embedding_status", "current_revision" ], "properties": { "action": { "type": "string" }, "current_revision": { "type": "integer", "format": "int64" }, "embedding_status": { "type": "string" }, "memory_id": { "type": "string", "format": "uuid" } } }, "SerenMemoryIngestDocumentRequest": { "type": "object", "required": [ "document", "memory_type", "source_kind", "source_external_id" ], "properties": { "document": {}, "importance": { "type": [ "integer", "null" ], "format": "int32" }, "lifecycle_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" } ] }, "memory_type": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": "string" }, "source_kind": { "type": "string" }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] } } }, "SerenMemoryInvokeKnowledgeOperationRequest": { "type": "object", "required": [ "parameters" ], "properties": { "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "parameters": {} }, "additionalProperties": false }, "SerenMemoryKnowledgeCardinality": { "type": "object", "properties": { "maximum": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "minimum": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "SerenMemoryKnowledgeDomainGrantRequest": { "type": "object", "required": [ "principal_type", "principal_id", "permission" ], "properties": { "permission": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainPermission" }, "principal_id": { "type": "string", "format": "uuid" }, "principal_type": { "$ref": "#/components/schemas/SerenMemoryKnowledgePrincipalType" } }, "additionalProperties": false }, "SerenMemoryKnowledgeDomainGrantResponse": { "type": "object", "required": [ "domain_id", "principal_type", "principal_id", "permission" ], "properties": { "domain_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainPermission" }, "principal_id": { "type": "string", "format": "uuid" }, "principal_type": { "$ref": "#/components/schemas/SerenMemoryKnowledgePrincipalType" } } }, "SerenMemoryKnowledgeDomainGrantsResponse": { "type": "object", "required": [ "grants" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainGrantResponse" } } } }, "SerenMemoryKnowledgeDomainPermission": { "type": "string", "enum": [ "reader", "editor", "owner" ] }, "SerenMemoryKnowledgeDomainResponse": { "type": "object", "required": [ "id", "slug", "name", "classification", "visibility", "is_default" ], "properties": { "classification": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainVisibility" } } }, "SerenMemoryKnowledgeDomainVisibility": { "type": "string", "enum": [ "organization", "restricted" ] }, "SerenMemoryKnowledgeDomainsResponse": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainResponse" } } } }, "SerenMemoryKnowledgeEntityType": { "type": "object", "required": [ "name", "fields" ], "properties": { "description": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeField" } }, "name": { "type": "string" } }, "additionalProperties": false }, "SerenMemoryKnowledgeField": { "type": "object", "required": [ "name", "type" ], "properties": { "allowed_values": { "type": "array", "items": { "type": "string" } }, "collection": { "type": "boolean" }, "identity": { "type": "boolean" }, "indexed": { "type": "boolean" }, "name": { "type": "string" }, "required": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/SerenMemoryKnowledgeFieldType" }, "unique": { "type": "boolean" } }, "additionalProperties": false }, "SerenMemoryKnowledgeFieldType": { "type": "string", "enum": [ "text", "boolean", "int32", "int64", "uint32", "uint64", "float32", "float64", "date", "date_time", "blob" ] }, "SerenMemoryKnowledgeModel": { "type": "object", "required": [ "entity_types" ], "properties": { "entity_types": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeEntityType" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeOperation" } }, "relationship_types": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRelationshipType" } } }, "additionalProperties": false }, "SerenMemoryKnowledgeModelConfigurationResponse": { "type": "object", "required": [ "domain_id", "model", "model_hash", "desired_revision", "status" ], "properties": { "applied_revision": { "type": [ "integer", "null" ], "format": "int64" }, "desired_revision": { "type": "integer", "format": "int64" }, "domain_id": { "type": "string", "format": "uuid" }, "model": { "$ref": "#/components/schemas/SerenMemoryKnowledgeModel" }, "model_hash": { "type": "string" }, "status": { "type": "string" } } }, "SerenMemoryKnowledgeOperation": { "allOf": [ { "$ref": "#/components/schemas/SerenMemoryKnowledgeOperationKind" }, { "type": "object", "required": [ "name", "description" ], "properties": { "description": { "type": "string" }, "instruction": { "type": [ "string", "null" ] }, "name": { "type": "string" } } } ] }, "SerenMemoryKnowledgeOperationKind": { "oneOf": [ { "type": "object", "required": [ "entity_type", "search_field", "kind" ], "properties": { "entity_type": { "type": "string" }, "kind": { "type": "string", "enum": [ "search" ] }, "return_fields": { "type": "array", "items": { "type": "string" } }, "search_field": { "type": "string" } } }, { "type": "object", "required": [ "entity_type", "kind" ], "properties": { "entity_type": { "type": "string" }, "kind": { "type": "string", "enum": [ "lookup" ] }, "return_fields": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "relationship_type", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "related" ] }, "relationship_type": { "type": "string" }, "return_fields": { "type": "array", "items": { "type": "string" } } } } ] }, "SerenMemoryKnowledgeOperationResult": { "type": "object", "required": [ "operation", "knowledge_revision", "count", "items" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "items": {}, "knowledge_revision": { "type": "integer", "format": "int64" }, "operation": { "type": "string" } } }, "SerenMemoryKnowledgeOperationsResponse": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeOperation" } } } }, "SerenMemoryKnowledgePrincipalType": { "type": "string", "enum": [ "user", "agent" ] }, "SerenMemoryKnowledgeRecord": { "oneOf": [ { "type": "object", "required": [ "entity_type", "id", "kind" ], "properties": { "entity_type": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "entity" ] }, "properties": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, { "type": "object", "required": [ "relationship_type", "from", "to", "kind" ], "properties": { "from": { "type": "string" }, "kind": { "type": "string", "enum": [ "relationship" ] }, "properties": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "relationship_type": { "type": "string" }, "to": { "type": "string" } } } ] }, "SerenMemoryKnowledgeRecordResponse": { "type": "object", "required": [ "record_key", "payload", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRecord" }, "record_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SerenMemoryKnowledgeRelationshipType": { "type": "object", "required": [ "name", "from_entity_type", "to_entity_type" ], "properties": { "cardinality": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SerenMemoryKnowledgeCardinality" } ] }, "description": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeField" } }, "from_entity_type": { "type": "string" }, "name": { "type": "string" }, "to_entity_type": { "type": "string" }, "unique_from": { "type": "boolean" }, "unique_pair": { "type": "boolean" } }, "additionalProperties": false }, "SerenMemoryLearnFromErrorParams": { "type": "object", "required": [ "error_content", "fix_content" ], "properties": { "error_content": { "type": "string" }, "fix_content": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" } }, "example": { "error_content": "Migration failed because the extension was missing", "fix_content": "Install the extension before applying the migration", "project_id": "123e4567-e89b-12d3-a456-426614174000" } }, "SerenMemoryListKnowledgeRecordsResponse": { "type": "object", "required": [ "records", "limit", "offset" ], "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRecordResponse" } } } }, "SerenMemoryListMemoriesResponse": { "type": "object", "required": [ "memories", "total", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "total": { "type": "integer", "format": "int64" } } }, "SerenMemoryMemoryConnectionRequest": { "type": "object", "required": [ "source_id", "target_id", "edge_type" ], "properties": { "edge_type": { "type": "string" }, "source_id": { "type": "string", "format": "uuid" }, "target_id": { "type": "string", "format": "uuid" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" } } }, "SerenMemoryMemoryConnectionResponse": { "type": "object", "required": [ "connected" ], "properties": { "connected": { "type": "boolean" } } }, "SerenMemoryMemoryEdge": { "type": "object", "description": "Full edge row from the `memory_edges` table.", "required": [ "id", "source_id", "target_id", "edge_type", "weight", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "edge_type": { "$ref": "#/components/schemas/SerenMemoryEdgeType" }, "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "target_id": { "type": "string", "format": "uuid" }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" }, "weight": { "type": "number", "format": "double" } } }, "SerenMemoryMemoryExportResponse": { "type": "object", "required": [ "schema_version", "generated_at", "memories", "memory_total", "conversation_sources", "conversation_source_total" ], "properties": { "conversation_source_total": { "type": "integer", "format": "int64" }, "conversation_sources": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryConversationSource" } }, "generated_at": { "type": "string", "format": "date-time" }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "memory_total": { "type": "integer", "format": "int64" }, "next_offset": { "type": [ "integer", "null" ], "format": "int64", "description": "Next shared offset while either exported collection has more rows." }, "schema_version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SerenMemoryMemoryLifecycle": { "type": "string", "description": "Product lifecycle for a private memory.", "enum": [ "active", "draft", "canonical", "deprecated" ] }, "SerenMemoryMemoryMigration": { "type": "object", "description": "Content-free durable record of an import migration run.", "required": [ "id", "series_id", "user_id", "source_type", "source_instance_id", "plan_hash", "expected_record_count", "final_catch_up", "state", "imported_count", "unchanged_count", "failed_count", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expected_record_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "final_catch_up": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "imported_count": { "type": "integer", "format": "int64" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "plan_hash": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "series_id": { "type": "string", "format": "uuid" }, "snapshot_id": { "type": [ "string", "null" ] }, "source_instance_id": { "type": "string" }, "source_type": { "type": "string" }, "state": { "$ref": "#/components/schemas/SerenMemoryMigrationState" }, "unchanged_count": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "SerenMemoryMemoryOutput": { "type": "object", "required": [ "id", "user_id", "memory_type", "content", "metadata", "relevance_score", "access_count", "is_consolidated", "is_pinned", "lifecycle_status", "importance", "current_revision", "embedding_status", "source_kind", "source_managed", "review_status", "created_at", "updated_at" ], "properties": { "access_count": { "type": "integer", "format": "int32" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "current_revision": { "type": "integer", "format": "int64" }, "embedding_status": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "importance": { "type": "integer", "format": "int32" }, "is_consolidated": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "lifecycle_status": { "type": "string" }, "memory_type": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "relevance_score": { "type": "number", "format": "double" }, "review_status": { "type": "string" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": [ "string", "null" ] }, "source_kind": { "type": "string" }, "source_managed": { "type": "boolean" }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "SerenMemoryMemoryReview": { "type": "string", "description": "Review state for a memory. No ingestion channel grants reviewed trust;\npromotion is a separate authorized transition.", "enum": [ "unreviewed", "reviewed" ] }, "SerenMemoryMemoryRevision": { "type": "object", "required": [ "memory_id", "revision", "change_kind", "content", "metadata", "lifecycle_status", "changed_by", "created_at" ], "properties": { "change_kind": { "type": "string" }, "changed_by": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "lifecycle_status": { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" }, "memory_id": { "type": "string", "format": "uuid" }, "metadata": {}, "revision": { "type": "integer", "format": "int64" }, "summary": { "type": [ "string", "null" ] } } }, "SerenMemoryMemoryType": { "type": "string", "description": "Categories of memory stored in the system.", "enum": [ "episodic", "semantic", "procedural", "code", "error_fix", "preference", "skill" ] }, "SerenMemoryMigrationState": { "type": "string", "description": "Lifecycle state of one import migration run.", "enum": [ "planned", "running", "interrupted", "completed", "verification_failed", "rolling_back", "rolled_back", "failed" ] }, "SerenMemoryMigrationStatusResponse": { "type": "object", "required": [ "migration", "attributed_memories", "attributed_sources", "processed_records", "embedding_ready", "embedding_pending", "embedding_failed" ], "properties": { "attributed_memories": { "type": "integer", "format": "int64" }, "attributed_sources": { "type": "integer", "format": "int64" }, "embedding_failed": { "type": "integer", "format": "int64" }, "embedding_pending": { "type": "integer", "format": "int64" }, "embedding_ready": { "type": "integer", "format": "int64" }, "migration": { "$ref": "#/components/schemas/SerenMemoryMemoryMigration" }, "processed_records": { "type": "integer", "format": "int64" } } }, "SerenMemoryMigrationTransitionState": { "type": "string", "enum": [ "running", "interrupted", "completed", "verification_failed", "failed" ] }, "SerenMemoryOpenKnowledgeEntityRequest": { "type": "object", "required": [ "entity_id" ], "properties": { "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "entity_id": { "type": "string" } }, "additionalProperties": false, "example": { "entity_id": "service:seren-memory" } }, "SerenMemoryPreviewWorkspaceMergeRequest": { "type": "object", "required": [ "source_workspace_key", "target_workspace_key" ], "properties": { "source_workspace_key": { "type": "string" }, "target_workspace_key": { "type": "string" } } }, "SerenMemoryProcessConversationParams": { "type": "object", "required": [ "transcript" ], "properties": { "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_context": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "retain_source": { "type": [ "boolean", "null" ] }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_external_id": { "type": [ "string", "null" ] }, "source_revision": { "type": [ "string", "null" ] }, "source_uri": { "type": [ "string", "null" ] }, "transcript": { "type": "string" } }, "example": { "transcript": "User confirmed that production migrations require explicit rollback notes.", "project_id": "123e4567-e89b-12d3-a456-426614174000" } }, "SerenMemoryReadinessResponse": { "type": "object", "required": [ "status" ], "properties": { "reason": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "SerenMemoryRecallParams": { "type": "object", "required": [ "query" ], "properties": { "created_after": { "type": [ "string", "null" ], "format": "date-time" }, "created_before": { "type": [ "string", "null" ], "format": "date-time" }, "limit": { "type": [ "integer", "null" ], "format": "int64" }, "memory_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "min_relevance": { "type": [ "number", "null" ], "format": "double" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "query": { "type": "string" }, "search_mode": { "type": [ "string", "null" ] } }, "example": { "query": "database migration conventions", "project_id": "123e4567-e89b-12d3-a456-426614174000", "limit": 10 } }, "SerenMemoryRecallResponse": { "type": "object", "required": [ "memories", "signals" ], "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/SerenMemoryMemoryOutput" } }, "signals": { "$ref": "#/components/schemas/SerenMemoryRecallSignalsResponse" } } }, "SerenMemoryRecallSignalsResponse": { "type": "object", "required": [ "vector_hits", "keyword_hits", "graph_hits", "augmenter_hits", "semantic_available" ], "properties": { "augmenter_hits": { "type": "integer", "minimum": 0 }, "graph_hits": { "type": "integer", "minimum": 0 }, "keyword_hits": { "type": "integer", "minimum": 0 }, "semantic_available": { "type": "boolean" }, "vector_hits": { "type": "integer", "minimum": 0 } } }, "SerenMemoryRememberOutput": { "type": "object", "description": "Output from the `remember` operation.", "required": [ "memory_id", "action_taken", "edges_created", "enrichments_triggered" ], "properties": { "action_taken": { "$ref": "#/components/schemas/SerenMemoryConflictAction" }, "edges_created": { "type": "integer", "minimum": 0 }, "enrichments_triggered": { "type": "integer", "minimum": 0 }, "memory_id": { "type": "string", "format": "uuid" }, "reason": { "type": [ "string", "null" ] }, "superseded_memory_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "SerenMemoryRememberParams": { "type": "object", "required": [ "content", "memory_type" ], "properties": { "content": { "type": "string" }, "importance": { "type": [ "integer", "null" ], "format": "int32" }, "lifecycle_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" } ] }, "memory_type": { "type": "string" }, "metadata": {}, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "pin": { "type": [ "boolean", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": [ "string", "null" ], "format": "uuid" }, "skip_conflict_check": { "type": [ "boolean", "null" ] }, "skip_enrichment": { "type": [ "boolean", "null" ] } }, "example": { "content": "This project uses PostgreSQL 16", "memory_type": "semantic", "project_id": "123e4567-e89b-12d3-a456-426614174000" } }, "SerenMemoryRollbackMigrationRequest": { "type": "object", "properties": { "series": { "type": [ "boolean", "null" ] } } }, "SerenMemoryRollbackMigrationResponse": { "type": "object", "required": [ "removed_memories", "removed_sources" ], "properties": { "removed_memories": { "type": "integer", "format": "int64", "minimum": 0 }, "removed_sources": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SerenMemorySearchKnowledgeRequest": { "type": "object", "required": [ "query" ], "properties": { "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "query": { "type": "string" } }, "additionalProperties": false, "example": { "query": "release approval process" } }, "SerenMemorySessionBootstrapParams": { "type": "object", "properties": { "include_git": { "type": [ "boolean", "null" ] }, "include_time": { "type": [ "boolean", "null" ] }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "reviewed_only": { "type": [ "boolean", "null" ], "description": "Restrict automatic context assembly to explicitly reviewed memories." }, "token_budget": { "type": [ "integer", "null" ], "minimum": 0 } }, "example": { "project_id": "123e4567-e89b-12d3-a456-426614174000", "token_budget": 4000 } }, "SerenMemorySessionContext": { "type": "object", "description": "Assembled session context for LLM system prompt injection.", "required": [ "memories_by_type", "total_memories" ], "properties": { "memories_by_type": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "total_memories": { "type": "integer", "minimum": 0 } } }, "SerenMemorySetMemoryReviewRequest": { "type": "object", "required": [ "review_status" ], "properties": { "review_status": { "$ref": "#/components/schemas/SerenMemoryMemoryReview" } } }, "SerenMemorySetMemoryReviewResponse": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } }, "SerenMemorySetMemoryStatusRequest": { "type": "object", "required": [ "lifecycle_status" ], "properties": { "lifecycle_status": { "$ref": "#/components/schemas/SerenMemoryMemoryLifecycle" } } }, "SerenMemorySetMigrationStateRequest": { "type": "object", "required": [ "state" ], "properties": { "state": { "$ref": "#/components/schemas/SerenMemoryMigrationTransitionState" } } }, "SerenMemorySourceOrigin": { "type": "string", "description": "Server-assigned ingestion channel for a retained conversation source.\nDescribes how the content arrived, not whether it is trusted.", "enum": [ "agent_hook", "legacy", "mcp", "manual", "migration" ] }, "SerenMemorySyncStatus": { "type": "object", "required": [ "status", "server", "version" ], "properties": { "server": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" } } }, "SerenMemoryUpdateKnowledgeDomainRequest": { "type": "object", "required": [ "name", "classification", "visibility" ], "properties": { "classification": { "type": "string" }, "name": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/SerenMemoryKnowledgeDomainVisibility" } }, "additionalProperties": false }, "SerenMemoryUpsertKnowledgeRecordRequest": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "$ref": "#/components/schemas/SerenMemoryKnowledgeRecord" } }, "additionalProperties": false }, "SerenMemoryWorkspaceMergePreview": { "type": "object", "required": [ "source_workspace_key", "target_workspace_key", "source_count", "target_count", "shared_external_sessions", "dependent_alias_count", "plan_hash" ], "properties": { "dependent_alias_count": { "type": "integer", "format": "int64" }, "plan_hash": { "type": "string" }, "shared_external_sessions": { "type": "integer", "format": "int64" }, "source_count": { "type": "integer", "format": "int64" }, "source_workspace_key": { "type": "string" }, "target_count": { "type": "integer", "format": "int64" }, "target_workspace_key": { "type": "string" } } }, "SerenMemoryWorkspaceMergeResult": { "type": "object", "required": [ "merge_id", "source_workspace_key", "target_workspace_key", "source_count", "target_count", "shared_external_sessions", "dependent_alias_count", "merged_source_count", "plan_hash", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "dependent_alias_count": { "type": "integer", "format": "int64" }, "merge_id": { "type": "string", "format": "uuid" }, "merged_source_count": { "type": "integer", "format": "int64" }, "plan_hash": { "type": "string" }, "shared_external_sessions": { "type": "integer", "format": "int64" }, "source_count": { "type": "integer", "format": "int64" }, "source_workspace_key": { "type": "string" }, "target_count": { "type": "integer", "format": "int64" }, "target_workspace_key": { "type": "string" } } }, "SerenStorageConfirmObjectStorageUploadRequest": { "type": "object", "properties": { "etag": { "type": [ "string", "null" ] } } }, "SerenStorageCopyObjectStorageObjectRequest": { "type": "object", "required": [ "destination_bucket_slug", "destination_object_key" ], "properties": { "destination_bucket_slug": { "type": "string" }, "destination_object_key": { "type": "string" }, "metadata": {} } }, "SerenStorageCreateObjectStorageMultipartPartRequest": { "type": "object", "required": [ "checksum" ], "properties": { "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" } } }, "SerenStorageCreateObjectStorageMultipartUploadRequest": { "type": "object", "required": [ "object_key", "byte_length", "checksum" ], "properties": { "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "content_type": { "type": "string" }, "metadata": {}, "object_key": { "type": "string" }, "part_size": { "type": [ "integer", "null" ], "format": "int64" } } }, "SerenStorageCreateObjectStorageUploadRequest": { "type": "object", "required": [ "object_key", "byte_length", "checksum" ], "properties": { "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "content_type": { "type": "string" }, "metadata": {}, "object_key": { "type": "string" } } }, "SerenStorageCreateObjectStorageWorkspaceSnapshotRequest": { "type": "object", "required": [ "deployment_id", "object_id", "archive_sha256", "file_count", "uncompressed_bytes" ], "properties": { "archive_sha256": { "type": "string" }, "deployment_id": { "type": "string", "format": "uuid" }, "file_count": { "type": "integer", "format": "int64" }, "object_id": { "type": "string", "format": "uuid" }, "retention_count": { "type": "integer", "format": "int32" }, "uncompressed_bytes": { "type": "integer", "format": "int64" } } }, "SerenStorageDataResponse_HealthStatus": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } } }, "SerenStorageDataResponse_ObjectStorageBucket": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "slug", "metadata", "trash_retention_days", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "expire_after_days": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "trash_retention_days": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "SerenStorageDataResponse_ObjectStorageBucketAgentGrant": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "agent_identity_id", "permission", "created_by_user_id", "updated_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenStorageObjectStorageAgentPermission" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": "string", "format": "uuid" } } } } }, "SerenStorageDataResponse_ObjectStorageDownload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "object", "download_url", "download_headers", "download_expires_at" ], "properties": { "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" } } } } }, "SerenStorageDataResponse_ObjectStorageMultipartPartUpload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "object_id", "part_number", "byte_length", "checksum", "upload_url", "upload_headers", "upload_expires_at" ], "properties": { "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "object_id": { "type": "string", "format": "uuid" }, "part_number": { "type": "integer", "format": "int32" }, "upload_expires_at": { "type": "string", "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_url": { "type": "string" } } } } }, "SerenStorageDataResponse_ObjectStorageMultipartUpload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "object", "part_size", "part_count", "upload_expires_at" ], "properties": { "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "part_count": { "type": "integer", "format": "int32" }, "part_size": { "type": "integer", "format": "int64" }, "upload_expires_at": { "type": "string", "format": "date-time" } } } } }, "SerenStorageDataResponse_ObjectStorageObject": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "object_key", "content_type", "byte_length", "checksum", "upload_mode", "status", "uri", "metadata", "created_by_user_id", "created_at", "updated_at" ], "properties": { "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "etag": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "object_key": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/SerenStorageObjectStorageObjectStatus" }, "trash_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SerenStorageObjectStorageTrashReason" } ] }, "trashed_at": { "type": [ "string", "null" ], "format": "date-time" }, "trashed_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "upload_mode": { "$ref": "#/components/schemas/SerenStorageObjectStorageUploadMode" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" }, "uploaded_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "uri": { "type": "string" } } } } }, "SerenStorageDataResponse_ObjectStorageObjectPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "objects", "common_prefixes" ], "properties": { "common_prefixes": { "type": "array", "items": { "type": "string" } }, "next_cursor": { "type": [ "string", "null" ] }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" } } } } } }, "SerenStorageDataResponse_ObjectStorageUpload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "object", "upload_url", "upload_headers", "upload_expires_at" ], "properties": { "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "upload_expires_at": { "type": "string", "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_url": { "type": "string" } } } } }, "SerenStorageDataResponse_ObjectStorageUsage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization_id", "quota_bytes", "object_limit", "pending_upload_limit", "reserved_bytes", "buckets" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SerenStorageObjectStorageBucketUsage" } }, "object_limit": { "type": "integer", "format": "int64" }, "organization_id": { "type": "string", "format": "uuid" }, "pending_upload_limit": { "type": "integer", "format": "int64" }, "quota_bytes": { "type": "integer", "format": "int64" }, "reserved_bytes": { "type": "integer", "format": "int64" } } } } }, "SerenStorageDataResponse_ObjectStorageWorkspaceSnapshot": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "deployment_id", "agent_identity_id", "object", "archive_sha256", "file_count", "uncompressed_bytes", "status", "created_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "archive_sha256": { "type": "string" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "file_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "organization_id": { "type": "string", "format": "uuid" }, "retired_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/SerenStorageObjectStorageWorkspaceSnapshotStatus" }, "uncompressed_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "SerenStorageDataResponse_ObjectStorageWorkspaceSnapshotDownload": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "snapshot", "download_url", "download_headers", "download_expires_at" ], "properties": { "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "snapshot": { "$ref": "#/components/schemas/SerenStorageObjectStorageWorkspaceSnapshot" } } } } }, "SerenStorageDataResponse_ServiceInfo": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } } } } }, "SerenStorageDataResponse_Vec_ObjectStorageBucket": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "slug", "metadata", "trash_retention_days", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "expire_after_days": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "trash_retention_days": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "SerenStorageDataResponse_Vec_ObjectStorageBucketAgentGrant": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "agent_identity_id", "permission", "created_by_user_id", "updated_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenStorageObjectStorageAgentPermission" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": "string", "format": "uuid" } } } } } }, "SerenStorageDataResponse_Vec_ObjectStorageWorkspaceSnapshot": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "deployment_id", "agent_identity_id", "object", "archive_sha256", "file_count", "uncompressed_bytes", "status", "created_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "archive_sha256": { "type": "string" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "file_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "organization_id": { "type": "string", "format": "uuid" }, "retired_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/SerenStorageObjectStorageWorkspaceSnapshotStatus" }, "uncompressed_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "SerenStorageErrorBody": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "SerenStorageHealthStatus": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "SerenStorageMoveObjectStorageObjectRequest": { "type": "object", "required": [ "destination_bucket_slug", "destination_object_key" ], "properties": { "destination_bucket_slug": { "type": "string" }, "destination_object_key": { "type": "string" } } }, "SerenStorageObjectStorageAgentPermission": { "type": "string", "enum": [ "reader", "writer" ] }, "SerenStorageObjectStorageBucket": { "type": "object", "required": [ "id", "organization_id", "slug", "metadata", "trash_retention_days", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "expire_after_days": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "organization_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "trash_retention_days": { "type": "integer", "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SerenStorageObjectStorageBucketAgentGrant": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "agent_identity_id", "permission", "created_by_user_id", "updated_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/SerenStorageObjectStorageAgentPermission" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by_user_id": { "type": "string", "format": "uuid" } } }, "SerenStorageObjectStorageBucketUsage": { "type": "object", "required": [ "bucket_id", "bucket_slug", "active_objects", "active_bytes", "pending_objects", "pending_bytes", "trashed_objects", "trashed_bytes", "deleting_objects", "deleting_bytes" ], "properties": { "active_bytes": { "type": "integer", "format": "int64" }, "active_objects": { "type": "integer", "format": "int64" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "deleting_bytes": { "type": "integer", "format": "int64" }, "deleting_objects": { "type": "integer", "format": "int64" }, "pending_bytes": { "type": "integer", "format": "int64" }, "pending_objects": { "type": "integer", "format": "int64" }, "trashed_bytes": { "type": "integer", "format": "int64" }, "trashed_objects": { "type": "integer", "format": "int64" } } }, "SerenStorageObjectStorageChecksum": { "type": "object", "required": [ "algorithm", "value" ], "properties": { "algorithm": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksumAlgorithm" }, "value": { "type": "string" } } }, "SerenStorageObjectStorageChecksumAlgorithm": { "type": "string", "enum": [ "sha256", "crc32c" ] }, "SerenStorageObjectStorageDownload": { "type": "object", "required": [ "object", "download_url", "download_headers", "download_expires_at" ], "properties": { "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" } } }, "SerenStorageObjectStorageMultipartPartUpload": { "type": "object", "required": [ "object_id", "part_number", "byte_length", "checksum", "upload_url", "upload_headers", "upload_expires_at" ], "properties": { "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "object_id": { "type": "string", "format": "uuid" }, "part_number": { "type": "integer", "format": "int32" }, "upload_expires_at": { "type": "string", "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_url": { "type": "string" } } }, "SerenStorageObjectStorageMultipartUpload": { "type": "object", "required": [ "object", "part_size", "part_count", "upload_expires_at" ], "properties": { "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "part_count": { "type": "integer", "format": "int32" }, "part_size": { "type": "integer", "format": "int64" }, "upload_expires_at": { "type": "string", "format": "date-time" } } }, "SerenStorageObjectStorageObject": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "object_key", "content_type", "byte_length", "checksum", "upload_mode", "status", "uri", "metadata", "created_by_user_id", "created_at", "updated_at" ], "properties": { "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "byte_length": { "type": "integer", "format": "int64" }, "checksum": { "$ref": "#/components/schemas/SerenStorageObjectStorageChecksum" }, "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "etag": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "object_key": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/SerenStorageObjectStorageObjectStatus" }, "trash_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SerenStorageObjectStorageTrashReason" } ] }, "trashed_at": { "type": [ "string", "null" ], "format": "date-time" }, "trashed_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "upload_mode": { "$ref": "#/components/schemas/SerenStorageObjectStorageUploadMode" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" }, "uploaded_by_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "uri": { "type": "string" } } }, "SerenStorageObjectStorageObjectPage": { "type": "object", "required": [ "objects", "common_prefixes" ], "properties": { "common_prefixes": { "type": "array", "items": { "type": "string" } }, "next_cursor": { "type": [ "string", "null" ] }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" } } } }, "SerenStorageObjectStorageObjectStatus": { "type": "string", "enum": [ "pending", "uploaded", "trashed", "delete_pending", "delete_failed", "deleted" ] }, "SerenStorageObjectStorageTrashReason": { "type": "string", "enum": [ "user_deleted", "expired", "workspace_retention" ] }, "SerenStorageObjectStorageUpload": { "type": "object", "required": [ "object", "upload_url", "upload_headers", "upload_expires_at" ], "properties": { "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "upload_expires_at": { "type": "string", "format": "date-time" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "upload_url": { "type": "string" } } }, "SerenStorageObjectStorageUploadMode": { "type": "string", "enum": [ "single", "multipart" ] }, "SerenStorageObjectStorageUsage": { "type": "object", "required": [ "organization_id", "quota_bytes", "object_limit", "pending_upload_limit", "reserved_bytes", "buckets" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SerenStorageObjectStorageBucketUsage" } }, "object_limit": { "type": "integer", "format": "int64" }, "organization_id": { "type": "string", "format": "uuid" }, "pending_upload_limit": { "type": "integer", "format": "int64" }, "quota_bytes": { "type": "integer", "format": "int64" }, "reserved_bytes": { "type": "integer", "format": "int64" } } }, "SerenStorageObjectStorageWorkspaceSnapshot": { "type": "object", "required": [ "id", "organization_id", "bucket_id", "bucket_slug", "deployment_id", "agent_identity_id", "object", "archive_sha256", "file_count", "uncompressed_bytes", "status", "created_by_user_id", "created_at", "updated_at" ], "properties": { "agent_identity_id": { "type": "string", "format": "uuid" }, "archive_sha256": { "type": "string" }, "bucket_id": { "type": "string", "format": "uuid" }, "bucket_slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "file_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "object": { "$ref": "#/components/schemas/SerenStorageObjectStorageObject" }, "organization_id": { "type": "string", "format": "uuid" }, "retired_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/SerenStorageObjectStorageWorkspaceSnapshotStatus" }, "uncompressed_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SerenStorageObjectStorageWorkspaceSnapshotDownload": { "type": "object", "required": [ "snapshot", "download_url", "download_headers", "download_expires_at" ], "properties": { "download_expires_at": { "type": "string", "format": "date-time" }, "download_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "download_url": { "type": "string" }, "snapshot": { "$ref": "#/components/schemas/SerenStorageObjectStorageWorkspaceSnapshot" } } }, "SerenStorageObjectStorageWorkspaceSnapshotStatus": { "type": "string", "enum": [ "active", "retired" ] }, "SerenStoragePutObjectStorageBucketAgentGrantRequest": { "type": "object", "required": [ "permission" ], "properties": { "permission": { "$ref": "#/components/schemas/SerenStorageObjectStorageAgentPermission" } } }, "SerenStoragePutObjectStorageBucketLifecycleRequest": { "type": "object", "required": [ "trash_retention_days" ], "properties": { "expire_after_days": { "type": [ "integer", "null" ], "format": "int32" }, "trash_retention_days": { "type": "integer", "format": "int32" } } }, "SerenStorageServiceInfo": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Databases", "description": "Database management endpoints" }, { "name": "Geographic Routing", "description": "User opt-in for geographic proxy routing" }, { "name": "Auth", "description": "Authentication and user management endpoints" }, { "name": "OAuth", "description": "OAuth connections for BYOC integrations" }, { "name": "oauth-providers", "description": "Organization OAuth provider configuration (BYOC)" }, { "name": "Organizations", "description": "Organization management endpoints" }, { "name": "VPC", "description": "VPC endpoint management" }, { "name": "billing", "description": "Billing and metering endpoints (x402 token cache)" }, { "name": "payments", "description": "Stripe payments and payment methods" }, { "name": "Plans", "description": "Subscription plans and quota management" }, { "name": "Audit Logs", "description": "Audit trail and activity logging" }, { "name": "RBAC", "description": "Role-based access control and permissions" }, { "name": "Webhooks", "description": "Webhook configuration and delivery management" }, { "name": "Sessions", "description": "User session management" }, { "name": "agent", "description": "Agent commerce and paid query execution" }, { "name": "agent-wallet", "description": "Wallet (funded + promotional)" }, { "name": "notifications", "description": "User notifications" }, { "name": "publisher-payments", "description": "Publisher payment APIs for first-class services" }, { "name": "publishers", "description": "Unified publisher proxy API" }, { "name": "mcp", "description": "MCP (Model Context Protocol) publisher integration" }, { "name": "skill", "description": "Endpoints included in skill.md for AI agent discovery" }, { "name": "Eval", "description": "Eval signal ingestion and routing matrix" }, { "name": "federation", "description": "Cross-publisher resource discovery and federation" } ] }