{ "openapi": "3.0.3", "info": { "title": "Brain Dump API", "version": "1.0.0", "summary": "Account-scoped todo API for Brain Dump.", "description": "Brain Dump lets users capture todos with voice and AI, then read and update those account-owned todos through API keys.\n\nUse JWT auth for account, billing, and API-key management. Use a Brain Dump API key for /api/v1/todos and the MCP server at /api/v1/mcp.\n\nTodo API access requires an active API subscription, currently $5/month, or lifetime beta access." }, "servers": [ { "url": "https://braindump.latentedge.io", "description": "Current API host" } ], "externalDocs": { "description": "Human-readable API docs", "url": "https://braindump.latentedge.io/docs/api" }, "tags": [ { "name": "Status", "description": "Health and contract discovery." }, { "name": "Auth", "description": "User signup, login, token refresh, logout, and password flows." }, { "name": "Sessions", "description": "Browser session visibility and revocation." }, { "name": "Billing", "description": "Stripe subscription and beta lifetime entitlement management." }, { "name": "API Keys", "description": "Self-serve API key management for authenticated users." }, { "name": "Todos", "description": "Account-scoped todo CRUD using API-key authentication." }, { "name": "MCP", "description": "Model Context Protocol server for AI agents, using API-key authentication." }, { "name": "Account", "description": "Account export and deletion." }, { "name": "Realtime", "description": "Server-sent events for the first-party web app." } ], "components": { "securitySchemes": { "jwtBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token returned by login, signup, or refresh." }, "apiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Brain Dump API key", "description": "API key returned by POST /api/v1/auth/api-keys. Keys start with bdk_." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative way to send a Brain Dump API key." }, "adminApiKey": { "type": "apiKey", "in": "header", "name": "X-Admin-API-Key", "description": "Admin-only key used to grant or revoke lifetime beta API access." }, "stripeSignature": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe webhook signature." } }, "parameters": { "TodoId": { "name": "todoId", "in": "path", "required": true, "description": "Numeric todo ID owned by the authenticated API key user.", "schema": { "type": "integer", "minimum": 1 }, "example": 123 }, "ApiKeyId": { "name": "keyId", "in": "path", "required": true, "description": "API key record ID.", "schema": { "type": "string", "format": "uuid" }, "example": "7d1b0e85-f5f6-4778-a061-dad44fa7ec53" }, "SessionId": { "name": "sessionId", "in": "path", "required": true, "description": "Refresh-token session record ID.", "schema": { "type": "string", "format": "uuid" }, "example": "bff1b150-15f3-4ed5-9795-b5d0a1c51b48" } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Todo text must be between 1 and 5000 characters" } } } } }, "User": { "type": "object", "required": [ "id", "email", "username", "privilege" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "9f8b6ca1-95ec-4e97-a9a8-3f90bd86511f" }, "user_key": { "type": "string", "example": "9f8b6ca1-95ec-4e97-a9a8-3f90bd86511f" }, "name": { "type": "string", "nullable": true, "example": null }, "username": { "type": "string", "example": "user" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "privilege": { "type": "string", "example": "user" }, "date_joined": { "type": "string", "format": "date-time", "example": "2026-06-11T15:00:00.000Z" }, "email_confirmed": { "type": "integer", "example": 1 } } }, "AuthTokenData": { "type": "object", "required": [ "token", "refreshToken" ], "properties": { "token": { "type": "string", "description": "Short-lived JWT access token." }, "refreshToken": { "type": "string", "description": "Opaque refresh token. Store securely and rotate via /api/v1/auth/refresh." }, "user": { "$ref": "#/components/schemas/User" } } }, "AuthEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AuthTokenData" } } }, "MessageEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Password has been reset successfully" } } } } }, "Todo": { "type": "object", "required": [ "id", "text", "priority", "category", "createdAt" ], "properties": { "id": { "type": "integer", "minimum": 1, "example": 123 }, "text": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "Send project update" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 is urgent, 4 is low priority.", "example": 2 }, "category": { "type": "string", "minLength": 1, "maxLength": 100, "example": "work" }, "estimatedDurationMinutes": { "type": "integer", "minimum": 0, "nullable": true, "example": 25 }, "createdAt": { "type": "integer", "description": "Unix timestamp in seconds.", "example": 1781186400 } } }, "TodoCreateRequest": { "type": "object", "required": [ "text", "priority", "category" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "Send project update" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "example": 2 }, "category": { "type": "string", "minLength": 1, "maxLength": 100, "example": "work" }, "estimatedDurationMinutes": { "type": "integer", "minimum": 0, "nullable": true, "example": 25 } } }, "TodoUpdateRequest": { "type": "object", "minProperties": 1, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "Send final project update" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "example": 1 }, "category": { "type": "string", "minLength": 1, "maxLength": 100, "example": "work" }, "estimatedDurationMinutes": { "type": "integer", "minimum": 0, "nullable": true, "example": 15 } } }, "TodoListEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "todos" ], "properties": { "todos": { "type": "array", "items": { "$ref": "#/components/schemas/Todo" } } } } } }, "TodoEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "todo" ], "properties": { "todo": { "$ref": "#/components/schemas/Todo" } } } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "prefix", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "7d1b0e85-f5f6-4778-a061-dad44fa7ec53" }, "name": { "type": "string", "example": "Personal automation" }, "prefix": { "type": "string", "example": "bdk_abc123" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-06-11T15:00:00Z" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true, "example": null } } }, "ApiKeyListEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "ApiKeyCreatedEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "apiKey", "key" ], "properties": { "apiKey": { "type": "string", "description": "Full API key. It is shown only once.", "example": "bdk_e41TqxxSNur9EXAMPLEaYcRkX1" }, "key": { "$ref": "#/components/schemas/ApiKey" } } } } }, "Session": { "type": "object", "required": [ "id", "createdAt", "expiresAt", "isActive" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "bff1b150-15f3-4ed5-9795-b5d0a1c51b48" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "example": true }, "userAgent": { "type": "string", "nullable": true, "example": "Mozilla/5.0" }, "ipAddress": { "type": "string", "nullable": true, "example": "203.0.113.10" } } }, "SessionListEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } } } } }, "Subscription": { "type": "object", "required": [ "provider", "planCode", "status", "isActive", "isBetaLifetime", "cancelAtPeriodEnd" ], "properties": { "provider": { "type": "string", "nullable": true, "example": "stripe" }, "planCode": { "type": "string", "nullable": true, "example": "api_access_monthly" }, "status": { "type": "string", "example": "active" }, "isActive": { "type": "boolean", "example": true }, "isBetaLifetime": { "type": "boolean", "example": false }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "cancelAtPeriodEnd": { "type": "boolean", "example": false }, "stripeCustomerId": { "type": "string", "nullable": true, "example": "cus_123" } } }, "SubscriptionStatusEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "planCode", "monthlyPriceUsd", "checkoutEnabled", "subscription" ], "properties": { "planCode": { "type": "string", "example": "api_access_monthly" }, "monthlyPriceUsd": { "type": "number", "example": 5 }, "checkoutEnabled": { "type": "boolean", "example": true }, "subscription": { "$ref": "#/components/schemas/Subscription" } } } } }, "CheckoutSessionEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri", "example": "https://checkout.stripe.com/c/session_id" }, "sessionId": { "type": "string", "example": "cs_test_123" } } } } }, "BillingPortalEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "portalUrl": { "type": "string", "format": "uri", "example": "https://billing.stripe.com/p/session_id" }, "sessionId": { "type": "string", "example": "bps_123" } } } } }, "StatusEnvelope": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "status", "service", "timestamp", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ], "example": "ok" }, "service": { "type": "string", "example": "braindump-worker" }, "version": { "type": "string", "example": "unknown" }, "environment": { "type": "string", "example": "production" }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "db": { "type": "string", "enum": [ "ok", "error" ], "example": "ok" } } } } } } }, "AccountExportEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "exportedAt": { "type": "string", "format": "date-time" }, "version": { "type": "string", "example": "v1" }, "account": { "$ref": "#/components/schemas/User" }, "todos": { "type": "array", "items": { "$ref": "#/components/schemas/Todo" } }, "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "subscription": { "$ref": "#/components/schemas/Subscription" } } } } } } }, "paths": { "/api/v1/openapi.json": { "get": { "tags": [ "Status" ], "summary": "Download this OpenAPI contract", "description": "Returns the machine-readable API contract for Brain Dump.", "operationId": "getOpenApiSpec", "responses": { "200": { "description": "OpenAPI document" } } } }, "/api/v1/status": { "get": { "tags": [ "Status" ], "summary": "Check API health", "operationId": "getStatus", "responses": { "200": { "description": "Worker and database are healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusEnvelope" } } } }, "503": { "description": "Worker is degraded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SERVICE_DEGRADED", "message": "One or more health checks failed." } } } } } } } }, "/api/v1/auth/signup": { "post": { "tags": [ "Auth" ], "summary": "Create an account", "description": "Creates a Brain Dump account and returns JWT plus refresh token.", "operationId": "signup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "username": { "type": "string" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "passwordConfirm": { "type": "string", "minLength": 8, "maxLength": 128 }, "turnstileToken": { "type": "string", "description": "Required only when Turnstile is enabled." } } }, "example": { "email": "user@example.com", "password": "correct-horse-battery", "passwordConfirm": "correct-horse-battery" } } } }, "responses": { "201": { "description": "Account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEnvelope" } } } }, "400": { "description": "Invalid signup input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Password must be between 8 and 128 characters" } } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Log in", "description": "Returns a short-lived JWT access token plus a refresh token. Use the JWT for account routes.", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } }, "example": { "email": "user@example.com", "password": "correct-horse-battery" } } } }, "responses": { "200": { "description": "Authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEnvelope" } } } }, "400": { "description": "Malformed request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request body must be a JSON object" } } } } }, "401": { "description": "Invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_CREDENTIALS", "message": "Invalid email or password" } } } } }, "429": { "description": "Too many login attempts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many login attempts. Please retry shortly." } } } } } } } }, "/api/v1/auth/verify": { "get": { "tags": [ "Auth" ], "summary": "Verify current JWT", "operationId": "verifyJwt", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Authenticated user.", "content": { "application/json": { "example": { "success": true, "data": { "user": { "id": "9f8b6ca1-95ec-4e97-a9a8-3f90bd86511f", "email": "user@example.com" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authentication required" } } } } } } } }, "/api/v1/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh JWT and rotate refresh token", "description": "The old refresh token is revoked. Store both returned values.", "operationId": "refreshToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string" } } }, "example": { "refreshToken": "rft_abc123" } } } }, "responses": { "200": { "description": "Tokens refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEnvelope" } } } }, "401": { "description": "Refresh token invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_TOKEN", "message": "Invalid refresh token" } } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Log out and revoke refresh token", "operationId": "logout", "security": [ { "jwtBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" }, "allSessions": { "type": "boolean", "default": false } } }, "example": { "refreshToken": "rft_abc123" } } } }, "responses": { "200": { "description": "Logged out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" }, "example": { "success": true, "data": { "message": "Logged out" } } } } } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Request a password reset email", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "example": { "email": "user@example.com" } } } }, "responses": { "200": { "description": "Password reset response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } } } } }, "/api/v1/auth/verify-reset-code": { "post": { "tags": [ "Auth" ], "summary": "Verify password reset code", "operationId": "verifyResetCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" } } }, "example": { "email": "user@example.com", "code": "reset-token-from-email" } } } }, "responses": { "200": { "description": "Reset code verified.", "content": { "application/json": { "example": { "success": true, "data": { "token": "reset-token-from-email" } } } } }, "400": { "description": "Invalid reset code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_RESET_CODE", "message": "Invalid reset code" } } } } } } } }, "/api/v1/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Reset password with reset token", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "password", "passwordConfirm" ], "properties": { "token": { "type": "string" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "passwordConfirm": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "example": { "token": "reset-token-from-email", "password": "new-correct-horse", "passwordConfirm": "new-correct-horse" } } } }, "responses": { "200": { "description": "Password reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "400": { "description": "Invalid or expired token, or a malformed request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_TOKEN", "message": "Invalid or expired reset token" } } } } } } } }, "/api/v1/auth/change-password": { "post": { "tags": [ "Auth" ], "summary": "Change password while authenticated", "description": "Revokes active refresh-token sessions after the password changes.", "operationId": "changePassword", "security": [ { "jwtBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currentPassword", "newPassword", "newPasswordConfirm" ], "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 128 }, "newPasswordConfirm": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "example": { "currentPassword": "correct-horse-battery", "newPassword": "new-correct-horse", "newPasswordConfirm": "new-correct-horse" } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelope" } } } }, "401": { "description": "Current password incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_CREDENTIALS", "message": "Current password is incorrect" } } } } } } } }, "/api/v1/auth/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List user sessions", "operationId": "listSessions", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Session list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListEnvelope" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authentication required" } } } } } } } }, "/api/v1/auth/sessions/{sessionId}": { "delete": { "tags": [ "Sessions" ], "summary": "Revoke a session", "operationId": "revokeSession", "security": [ { "jwtBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "responses": { "200": { "description": "Session revoked.", "content": { "application/json": { "example": { "success": true, "data": { "revoked": true } } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Session not found" } } } } } } } }, "/api/v1/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Get API subscription status", "description": "Shows whether API-key todo access is active through Stripe or lifetime beta access.", "operationId": "getSubscriptionStatus", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Subscription status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionStatusEnvelope" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authentication required" } } } } } } } }, "/api/v1/billing/checkout-session": { "post": { "tags": [ "Billing" ], "summary": "Create Stripe checkout session", "operationId": "createCheckoutSession", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Checkout session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionEnvelope" } } } }, "409": { "description": "Beta lifetime users do not need checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "BETA_LIFETIME_ACCESS", "message": "Lifetime beta access is already active. No billing required." } } } } }, "503": { "description": "Billing not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "BILLING_UNAVAILABLE", "message": "Billing is not configured yet. Please contact support." } } } } } } } }, "/api/v1/billing/portal-session": { "post": { "tags": [ "Billing" ], "summary": "Create Stripe billing portal session", "operationId": "createBillingPortalSession", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Billing portal session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalEnvelope" } } } }, "404": { "description": "Stripe customer not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No Stripe customer found for this user." } } } } } } } }, "/api/v1/billing/subscription/cancel": { "post": { "tags": [ "Billing" ], "summary": "Cancel Stripe subscription at period end", "operationId": "cancelSubscription", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Subscription set to cancel at period end." }, "404": { "description": "Subscription not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_NOT_FOUND", "message": "No Stripe subscription found for this user." } } } } } } } }, "/api/v1/billing/subscription/reactivate": { "post": { "tags": [ "Billing" ], "summary": "Resume Stripe subscription renewal", "operationId": "reactivateSubscription", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Subscription reactivated." }, "409": { "description": "Subscription cannot be reactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_NOT_REACTIVATABLE", "message": "Only active subscriptions can be reactivated." } } } } } } } }, "/api/v1/billing/beta/grant": { "post": { "tags": [ "Billing" ], "summary": "Grant lifetime beta API access", "operationId": "grantBetaLifetimeAccess", "security": [ { "adminApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" } }, "oneOf": [ { "required": [ "userId" ] }, { "required": [ "email" ] } ] }, "example": { "email": "beta-user@example.com" } } } }, "responses": { "200": { "description": "Beta access granted." }, "401": { "description": "Admin key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "ADMIN_AUTH_REQUIRED", "message": "Admin authorization required" } } } } } } } }, "/api/v1/billing/beta/revoke": { "post": { "tags": [ "Billing" ], "summary": "Revoke lifetime beta API access", "operationId": "revokeBetaLifetimeAccess", "security": [ { "adminApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" } }, "oneOf": [ { "required": [ "userId" ] }, { "required": [ "email" ] } ] }, "example": { "userId": "9f8b6ca1-95ec-4e97-a9a8-3f90bd86511f" } } } }, "responses": { "200": { "description": "Beta access revoked." }, "404": { "description": "Beta access not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "BETA_ACCESS_NOT_FOUND", "message": "No lifetime beta access found for this user" } } } } } } } }, "/api/v1/auth/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "Requires JWT and active API subscription or lifetime beta access.", "operationId": "listApiKeys", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "API keys listed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListEnvelope" } } } }, "402": { "description": "Subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_REQUIRED", "message": "An active API subscription is required to manage API keys." } } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create API key", "description": "The full API key is returned once. Store it securely.", "operationId": "createApiKey", "security": [ { "jwtBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 } } }, "example": { "name": "Personal automation", "expiresInDays": 365 } } } }, "responses": { "201": { "description": "API key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedEnvelope" } } } }, "402": { "description": "Subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_REQUIRED", "message": "An active API subscription is required to create API keys." } } } } } } } }, "/api/v1/auth/api-keys/{keyId}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke API key", "operationId": "revokeApiKey", "security": [ { "jwtBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" } ], "responses": { "200": { "description": "API key revoked.", "content": { "application/json": { "example": { "success": true, "data": { "revoked": true } } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "API key not found" } } } } } } } }, "/api/v1/auth/api-keys/{keyId}/rotate": { "post": { "tags": [ "API Keys" ], "summary": "Rotate API key secret", "description": "Revokes the previous secret and returns the new full API key once.", "operationId": "rotateApiKey", "security": [ { "jwtBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "clearExpiry": { "type": "boolean" } } }, "example": { "expiresInDays": 365 } } } }, "responses": { "200": { "description": "API key rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedEnvelope" } } } }, "404": { "description": "API key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "API key not found" } } } } } } } }, "/api/v1/mcp": { "post": { "tags": [ "MCP" ], "summary": "MCP server (JSON-RPC 2.0)", "description": "Model Context Protocol endpoint over stateless streamable HTTP. Each POST carries one JSON-RPC 2.0 message (initialize, ping, tools/list, tools/call). JSON-RPC does not model well in OpenAPI, so this entry is a stub: call tools/list for the real tool contract. Connect an MCP client with the same Brain Dump API key used for /api/v1/todos.", "operationId": "mcp", "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A JSON-RPC 2.0 request object." }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } }, "responses": { "200": { "description": "A JSON-RPC 2.0 response object." }, "401": { "description": "API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "API_KEY_REQUIRED", "message": "Valid API key required" } } } } }, "402": { "description": "Subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_REQUIRED", "message": "An active API subscription is required to use todo API endpoints." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Initialize handshake", "source": "curl -sS -X POST \"https://braindump.latentedge.io/api/v1/mcp\" -H \"Authorization: Bearer bdk_your_api_key\" -H \"Content-Type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}'" } ] } }, "/api/v1/todos": { "get": { "tags": [ "Todos" ], "summary": "List todos", "description": "Returns only todos owned by the user who owns the API key.", "operationId": "listTodos", "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "responses": { "200": { "description": "Todo list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoListEnvelope" }, "example": { "success": true, "data": { "todos": [ { "id": 123, "text": "Send project update", "priority": 2, "category": "work", "estimatedDurationMinutes": 25, "createdAt": 1781186400 } ] } } } } }, "401": { "description": "API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "API_KEY_REQUIRED", "message": "Valid API key required" } } } } }, "402": { "description": "Subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_REQUIRED", "message": "An active API subscription is required to use todo API endpoints." } } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many todo read requests. Please retry shortly." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "List todos", "source": "curl -sS \"https://braindump.latentedge.io/api/v1/todos\" -H \"Authorization: Bearer bdk_your_api_key\"" } ] }, "post": { "tags": [ "Todos" ], "summary": "Create todo", "description": "Creates a todo in the API key owner account and broadcasts a realtime update to active sessions.", "operationId": "createTodo", "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoCreateRequest" }, "example": { "text": "Send project update", "priority": 2, "category": "work", "estimatedDurationMinutes": 25 } } } }, "responses": { "201": { "description": "Todo created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoEnvelope" } } } }, "400": { "description": "Invalid todo payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Todo text must be between 1 and 5000 characters" } } } } }, "401": { "description": "API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "API_KEY_REQUIRED", "message": "Valid API key required" } } } } }, "402": { "description": "Subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "SUBSCRIPTION_REQUIRED", "message": "An active API subscription is required to use todo API endpoints." } } } } } } } }, "/api/v1/todos/{todoId}": { "put": { "tags": [ "Todos" ], "summary": "Update todo", "description": "Partially updates an existing todo owned by the API key owner.", "operationId": "updateTodo", "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/TodoId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoUpdateRequest" }, "example": { "text": "Send final project update", "priority": 1 } } } }, "responses": { "200": { "description": "Todo updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TodoEnvelope" } } } }, "400": { "description": "Invalid todo payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Priority must be an integer between 1 and 4" } } } } }, "404": { "description": "Todo not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Todo not found" } } } } } } }, "delete": { "tags": [ "Todos" ], "summary": "Delete todo", "description": "Deletes an existing todo owned by the API key owner.", "operationId": "deleteTodo", "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "$ref": "#/components/parameters/TodoId" } ], "responses": { "200": { "description": "Todo deleted.", "content": { "application/json": { "example": { "success": true, "data": { "deleted": true } } } } }, "404": { "description": "Todo not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Todo not found" } } } } } } } }, "/api/v1/account/export": { "get": { "tags": [ "Account" ], "summary": "Export account data", "description": "Downloads account metadata, todos, API key metadata, sessions, and subscription state.", "operationId": "exportAccount", "security": [ { "jwtBearer": [] } ], "responses": { "200": { "description": "Account export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountExportEnvelope" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authentication required" } } } } } } } }, "/api/v1/account": { "delete": { "tags": [ "Account" ], "summary": "Delete account", "description": "Permanently deletes account data after password and DELETE confirmation.", "operationId": "deleteAccount", "security": [ { "jwtBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password", "confirmText" ], "properties": { "password": { "type": "string" }, "confirmText": { "type": "string", "enum": [ "DELETE" ] } } }, "example": { "password": "correct-horse-battery", "confirmText": "DELETE" } } } }, "responses": { "200": { "description": "Account deleted.", "content": { "application/json": { "example": { "success": true, "data": { "deleted": true, "message": "Account deleted." } } } } }, "401": { "description": "Password incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_CREDENTIALS", "message": "Password is incorrect" } } } } } } } }, "/sse": { "get": { "tags": [ "Realtime" ], "summary": "Open realtime todo event stream", "description": "First-party web app endpoint. EventSource clients pass JWT as token query parameter because EventSource cannot set custom headers.", "operationId": "openRealtimeStream", "parameters": [ { "name": "token", "in": "query", "required": false, "description": "JWT access token for EventSource clients.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent event stream. Event types include connected, ping, todos-updated, and todo-deleted.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"type\":\"connected\"}\n\n" } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Invalid token" } } } } } } } }, "/api/v1/billing/webhook/stripe": { "post": { "tags": [ "Billing" ], "summary": "Stripe webhook receiver", "description": "Stripe calls this endpoint to synchronize checkout and subscription lifecycle events.", "operationId": "stripeWebhook", "security": [ { "stripeSignature": [] } ], "responses": { "200": { "description": "Webhook accepted.", "content": { "application/json": { "example": { "success": true, "data": { "received": true } } } } }, "400": { "description": "Invalid signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INVALID_SIGNATURE", "message": "Invalid Stripe signature" } } } } } } } } } }