{"components":{"parameters":{"DatabaseId":{"description":"Unique database identifier (prefixed, e.g. db_xxx).","in":"path","name":"database_id","required":true,"schema":{"pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}},"DomainId":{"description":"Unique custom domain identifier (prefixed, e.g. dom_xxx).","in":"path","name":"domain_id","required":true,"schema":{"pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}},"OrgId":{"description":"Unique organization identifier.","in":"path","name":"org_id","required":true,"schema":{"example":"org_abc123","pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}},"PageSize":{"description":"Maximum number of items to return (1-100, default 20).","in":"query","name":"page_size","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},"PageToken":{"description":"Opaque token for cursor-based pagination.","in":"query","name":"page_token","schema":{"pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}},"ProjectId":{"description":"Unique project identifier (prefixed, e.g. prj_xxx).","in":"path","name":"project_id","required":true,"schema":{"pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}},"ReplicaId":{"description":"Unique replica identifier (prefixed, e.g. rep_xxx).","in":"path","name":"replica_id","required":true,"schema":{"pattern":"^[a-zA-Z0-9_.-]+$","type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request parameters."},"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource already exists or conflicts with current state."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Operation not allowed by current plan limits."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found."},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Service temporarily unavailable."},"TooManyRequests":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Rate limited. Try again later.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"example":60,"type":"integer"}}}},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or invalid authentication."}},"schemas":{"AccountExport":{"description":"Full account data export for privacy and data-portability requests.","properties":{"audit_logs":{"description":"Recent audit log entries associated with the account.","items":{"properties":{"action":{"description":"Action captured by the audit log entry.","type":"string"},"created_at":{"description":"When the audit log entry was recorded.","format":"date-time","type":"string"},"id":{"description":"Audit log entry identifier.","type":"string"},"ip_address":{"description":"IP address associated with the action, if known.","type":"string"},"resource_id":{"description":"Identifier of the affected resource.","type":"string"},"resource_type":{"description":"Type of resource affected by the action.","type":"string"}},"required":["id","action","created_at"],"type":"object"},"type":"array"},"consents":{"description":"Recorded legal-document acceptances for the user.","items":{"properties":{"accepted_at":{"description":"When the document was accepted.","format":"date-time","type":"string"},"document_type":{"description":"Legal document type accepted by the user.","type":"string"},"document_version":{"description":"Accepted document version.","type":"string"},"id":{"description":"Consent record identifier.","type":"string"},"ip_address":{"description":"IP address captured when consent was recorded.","type":"string"}},"required":["id","document_type","document_version","accepted_at"],"type":"object"},"type":"array"},"databases":{"description":"Databases registered under the exported projects.","items":{"properties":{"created_at":{"description":"When the database registration was created.","format":"date-time","type":"string"},"host":{"description":"Upstream PostgreSQL host.","type":"string"},"id":{"description":"Database identifier.","type":"string"},"name":{"description":"Upstream PostgreSQL database name.","type":"string"},"port":{"description":"Upstream PostgreSQL port.","type":"integer"},"project_id":{"description":"Owning project identifier.","type":"string"},"role":{"description":"Database role within the project.","type":"string"},"ssl_mode":{"description":"PostgreSQL SSL mode in use for the database.","type":"string"}},"required":["id","project_id","host","port","name","ssl_mode","role","created_at"],"type":"object"},"type":"array"},"email_preferences":{"description":"User communication preferences.","properties":{"marketing_emails":{"description":"Whether marketing emails are enabled.","type":"boolean"},"usage_limit_alerts":{"description":"Whether usage alert emails are enabled.","type":"boolean"}},"type":"object"},"exported_at":{"description":"When the export was generated.","format":"date-time","type":"string"},"organizations":{"description":"Organizations the user belongs to.","items":{"properties":{"created_at":{"description":"When the organization membership was created.","format":"date-time","type":"string"},"id":{"description":"Organization identifier.","type":"string"},"name":{"description":"Organization display name.","type":"string"},"role":{"description":"User role within the organization.","type":"string"},"slug":{"description":"Organization slug used in URLs and routing.","type":"string"}},"required":["id","name","slug","role","created_at"],"type":"object"},"type":"array"},"projects":{"description":"Projects owned through the user's organizations.","items":{"properties":{"created_at":{"description":"When the project was created.","format":"date-time","type":"string"},"description":{"description":"Project description at export time.","type":"string"},"id":{"description":"Project identifier.","type":"string"},"name":{"description":"Project display name.","type":"string"},"org_id":{"description":"Owning organization identifier.","type":"string"},"status":{"description":"Project lifecycle status.","type":"string"}},"required":["id","org_id","name","description","status","created_at"],"type":"object"},"type":"array"},"sessions":{"description":"Auth sessions associated with the user.","items":{"properties":{"created_at":{"description":"When the session was created.","format":"date-time","type":"string"},"expires_at":{"description":"When the session expires.","format":"date-time","type":"string"},"id":{"description":"Session identifier.","type":"string"},"ip_address":{"description":"IP address used to create the session, if known.","type":"string"},"user_agent":{"description":"User agent captured for the session, if known.","type":"string"}},"required":["id","expires_at","created_at"],"type":"object"},"type":"array"},"user":{"description":"Core user profile data.","properties":{"created_at":{"description":"When the user account was created.","format":"date-time","type":"string"},"email":{"description":"Primary account email address.","format":"email","type":"string"},"email_verified":{"description":"Whether the email address has been verified.","type":"boolean"},"id":{"description":"User identifier.","type":"string"},"image":{"description":"Avatar image URL, if present.","type":"string"},"name":{"description":"Display name for the user.","type":"string"},"updated_at":{"description":"When the user profile was last updated.","format":"date-time","type":"string"}},"required":["id","name","email","email_verified","created_at","updated_at"],"type":"object"}},"required":["user","organizations","projects","databases","sessions","email_preferences","consents","audit_logs","exported_at"],"type":"object"},"BillingHealthSummary":{"description":"Aggregate billing health metrics grouped by plan and provider.","properties":{"entries":{"description":"Aggregate counts for each billing segment.","items":{"properties":{"billing_provider":{"description":"Billing provider for the segment.","type":"string"},"org_count":{"description":"Number of organizations in the segment.","format":"int64","type":"integer"},"plan":{"description":"Plan tier for the segment.","type":"string"},"subscription_status":{"description":"Subscription status for the segment.","type":"string"}},"required":["plan","billing_provider","subscription_status","org_count"],"type":"object"},"type":"array"}},"required":["entries"],"type":"object"},"CacheConfig":{"description":"Query cache configuration.","properties":{"enabled":{"default":true,"description":"Whether query caching is enabled. When false, all queries bypass the cache.","type":"boolean"},"max_entries":{"default":10000,"description":"Maximum number of cached query results.","maximum":1000000,"minimum":0,"type":"integer"},"swr_seconds":{"default":30,"description":"Stale-while-revalidate window in seconds.","maximum":86400,"minimum":0,"type":"integer"},"ttl_seconds":{"default":60,"description":"Cache TTL in seconds for query results.","maximum":86400,"minimum":0,"type":"integer"}},"required":["enabled","ttl_seconds","max_entries","swr_seconds"],"type":"object"},"CacheRuleEntry":{"description":"Observed query shape and its cache recommendation for a database.","properties":{"avg_latency_ms":{"description":"Average query latency in milliseconds.","format":"double","type":"number"},"avg_response_bytes":{"description":"Average response size in bytes.","format":"int64","type":"integer"},"cache_enabled":{"description":"Whether caching is enabled for this query shape.","type":"boolean"},"cache_swr_seconds":{"description":"SWR override in seconds. Null means use project default.","example":60,"minimum":0,"nullable":true,"type":"integer"},"cache_ttl_seconds":{"description":"TTL override in seconds. Null means use project default.","example":300,"minimum":0,"nullable":true,"type":"integer"},"call_count":{"description":"Total number of executions observed.","format":"int64","type":"integer"},"first_seen_at":{"description":"When this query was first observed.","format":"date-time","type":"string"},"last_seen_at":{"description":"When this query was last observed.","format":"date-time","type":"string"},"normalized_sql":{"description":"SQL with literals replaced by $N placeholders.","example":"SELECT * FROM users WHERE id = $1","type":"string"},"p95_latency_ms":{"description":"95th percentile latency in milliseconds.","format":"double","type":"number"},"query_hash":{"description":"xxhash64 hex of the normalized SQL.","example":"a1b2c3d4e5f60718","type":"string"},"query_type":{"description":"Query classification.","enum":["read","write","other"],"type":"string"},"recommendation":{"description":"Cache recommendation based on frequency, latency, and stability.","enum":["great","good","fair","poor"],"type":"string"},"stability_rate":{"description":"Response stability rate (0.0 to 1.0). Higher means more stable.","format":"double","type":"number"}},"required":["query_hash","normalized_sql","query_type","cache_enabled","call_count","avg_latency_ms","p95_latency_ms","avg_response_bytes","stability_rate","recommendation","first_seen_at","last_seen_at"],"type":"object"},"CacheSummary":{"description":"Aggregate cache performance metrics for the selected time range.","properties":{"hit_rate":{"description":"Cache hit rate as a fraction (0.0 to 1.0).","format":"double","type":"number"},"total_hits":{"description":"Total number of cache hits in the selected time range.","format":"int64","type":"integer"},"total_misses":{"description":"Total number of cache misses in the selected time range.","format":"int64","type":"integer"}},"required":["total_hits","total_misses","hit_rate"],"type":"object"},"CancellationFeedbackRequest":{"description":"Request body for capturing cancellation feedback from a user.","properties":{"feedback":{"description":"Free-text feedback from the user.","example":"Switching to a self-hosted solution.","type":"string"},"reason":{"description":"Predefined cancellation reason.","example":"too-expensive","type":"string"}},"type":"object"},"CidrEntry":{"description":"An IP filtering rule with a CIDR range and optional human-readable label.","properties":{"cidr":{"description":"CIDR range in IPv4 (e.g. 203.0.113.0/24) or IPv6 (e.g. 2001:db8::/32) notation. A plain IP without prefix length defaults to /32 (IPv4) or /128 (IPv6).\n","example":"10.0.0.0/8","pattern":"^[0-9a-fA-F.:]+(/[0-9]+)?$","type":"string"},"label":{"description":"Optional human-readable label for this CIDR entry (e.g. \"Office\", \"VPC\").","example":"Office network","maxLength":100,"type":"string"}},"required":["cidr"],"type":"object"},"ConsentRecord":{"description":"Persisted legal-consent record for a user.","properties":{"accepted_at":{"description":"When the document was accepted.","format":"date-time","type":"string"},"document_type":{"description":"Accepted legal document type.","type":"string"},"document_version":{"description":"Accepted document version.","type":"string"},"id":{"description":"Consent record identifier.","type":"string"},"ip_address":{"description":"IP address captured when consent was recorded.","type":"string"},"user_id":{"description":"User identifier the consent belongs to.","type":"string"}},"required":["id","user_id","document_type","document_version","accepted_at"],"type":"object"},"CreateCustomDomainRequest":{"description":"Request body for attaching a custom domain to a project.","properties":{"domain":{"description":"The custom domain name to add (e.g., db.example.com).","example":"db.example.com","maxLength":253,"minLength":1,"pattern":"^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$","type":"string"}},"required":["domain"],"type":"object"},"CreateDatabaseRequest":{"description":"Request body for registering an upstream database.","properties":{"auto_read_routing":{"default":false,"description":"Auto-route SELECT queries to read replicas.\n","type":"boolean"},"cache_config":{"$ref":"#/components/schemas/CacheConfig"},"host":{"description":"PostgreSQL host.","example":"db.example.com","minLength":1,"pattern":"^[^\\s\\x00]+$","type":"string"},"name":{"description":"PostgreSQL database name.","example":"mydb","minLength":1,"pattern":"^[^\\x00]+$","type":"string"},"password":{"description":"PostgreSQL password. Stored encrypted at rest.","format":"password","minLength":1,"pattern":"^[^\\x00]+$","type":"string","writeOnly":true},"pool_config":{"$ref":"#/components/schemas/PoolConfig"},"pool_region":{"description":"Region where the connection pool is maintained (near the database). When set and different from the client's edge region, queries are relayed through the pool region's data plane. Empty means direct connection.\n","example":"us-east-1","type":"string"},"port":{"description":"PostgreSQL port.","example":5432,"maximum":65535,"minimum":1,"type":"integer"},"query_timeout_ms":{"default":0,"description":"Query timeout in milliseconds. 0 means disabled (default).\n","maximum":300000,"minimum":0,"type":"integer"},"role":{"$ref":"#/components/schemas/DatabaseRole"},"ssl_mode":{"$ref":"#/components/schemas/SSLMode"},"username":{"description":"PostgreSQL username.","example":"pgbeam","minLength":1,"pattern":"^[^\\x00]+$","type":"string"}},"required":["host","port","name","username","password"],"type":"object"},"CreateProjectRequest":{"description":"Request body for creating a project and its primary database.","properties":{"cloud":{"default":"aws","description":"Cloud provider for the project.","enum":["aws","azure","gcp"],"type":"string"},"database":{"$ref":"#/components/schemas/CreateDatabaseRequest"},"description":{"description":"Optional project description.","example":"Production database proxy","maxLength":500,"type":"string"},"name":{"description":"Human-readable project name.","example":"my-app","maxLength":100,"minLength":1,"pattern":"^[^\\x00]*$","type":"string"},"org_id":{"description":"Better Auth organization ID.","example":"org_abc123","minLength":1,"pattern":"^[^\\x00]+$","type":"string"},"tags":{"description":"User-defined labels to attach to the project.","example":["production","us-east-1"],"items":{"maxLength":50,"type":"string"},"maxItems":10,"type":"array"}},"required":["name","org_id","database"],"type":"object"},"CreateProjectResponse":{"description":"Response returned after creating a project and its primary database.","properties":{"database":{"$ref":"#/components/schemas/Database"},"project":{"$ref":"#/components/schemas/Project"}},"required":["project"],"type":"object"},"CreateReplicaRequest":{"description":"Request body for adding a read replica to a database.","properties":{"host":{"description":"PostgreSQL replica host.","example":"replica.us-west-2.rds.amazonaws.com","minLength":1,"pattern":"^[^\\s\\x00]+$","type":"string"},"port":{"description":"PostgreSQL replica port.","example":5432,"maximum":65535,"minimum":1,"type":"integer"},"ssl_mode":{"$ref":"#/components/schemas/SSLMode"}},"required":["host","port"],"type":"object"},"CustomDomain":{"description":"Custom database hostname attached to a project.","properties":{"created_at":{"description":"When the custom domain was created.","format":"date-time","type":"string"},"dns_instructions":{"$ref":"#/components/schemas/DnsInstructions"},"dns_verification_token":{"description":"Token value for the DNS TXT record verification.","type":"string"},"domain":{"description":"The custom domain name.","example":"db.example.com","type":"string"},"id":{"description":"Unique domain identifier (prefixed).","example":"dom_01h455vb4pex5vsknk084sn02q","type":"string"},"project_id":{"description":"Owning project ID.","example":"prj_01h455vb4pex5vsknk084sn02q","type":"string"},"tls_cert_expiry":{"description":"When the TLS certificate expires.","format":"date-time","nullable":true,"type":"string"},"updated_at":{"description":"When the custom domain was last updated.","format":"date-time","type":"string"},"verified":{"description":"Whether DNS ownership has been verified.","type":"boolean"},"verified_at":{"description":"When DNS verification was completed.","format":"date-time","nullable":true,"type":"string"}},"required":["id","project_id","domain","verified","dns_verification_token","created_at","updated_at"],"type":"object"},"DailyUsage":{"description":"Daily usage totals aggregated across all projects in an organization.","properties":{"bytes_transferred":{"description":"Total bytes transferred to clients.","format":"int64","type":"integer"},"cache_hits":{"description":"Total cache hits on the day.","format":"int64","type":"integer"},"cache_misses":{"description":"Total cache misses on the day.","format":"int64","type":"integer"},"connection_seconds":{"description":"Total proxy connection time consumed on the day.","format":"int64","type":"integer"},"day":{"description":"Usage date in UTC.","format":"date","type":"string"},"queries_total":{"description":"Total queries served on the day.","format":"int64","type":"integer"}},"required":["day","queries_total","cache_hits","cache_misses","connection_seconds","bytes_transferred"],"type":"object"},"Database":{"description":"Registered upstream PostgreSQL database for a project.","properties":{"auto_read_routing":{"default":false,"description":"When enabled and replicas are configured, SELECT queries automatically route to read replicas without requiring the @pgbeam:replica SQL annotation.\n","type":"boolean"},"cache_config":{"$ref":"#/components/schemas/CacheConfig"},"connection_string":{"description":"Connection string for connecting through PgBeam proxy. Password is replaced with a placeholder.","example":"postgresql://myuser:YOUR_PASSWORD@myproject.aws.pgbeam.app:5432/mydb","readOnly":true,"type":"string"},"created_at":{"description":"When the database registration was created.","format":"date-time","type":"string"},"host":{"description":"PostgreSQL host.","example":"db.example.com","type":"string"},"id":{"description":"Unique database identifier (prefixed).","example":"db_01h455vb4pex5vsknk084sn02q","type":"string"},"name":{"description":"PostgreSQL database name.","example":"mydb","type":"string"},"pool_config":{"$ref":"#/components/schemas/PoolConfig"},"pool_region":{"description":"Region where the connection pool is maintained (near the database). When set and different from the client's edge region, queries are relayed through the pool region's data plane. Empty means direct connection.\n","example":"us-east-1","type":"string"},"port":{"description":"PostgreSQL port.","example":5432,"maximum":65535,"minimum":1,"type":"integer"},"project_id":{"description":"Owning project ID.","example":"prj_01h455vb4pex5vsknk084sn02q","type":"string"},"query_timeout_ms":{"default":0,"description":"Query timeout in milliseconds. When set (\u003e 0), the proxy sends SET statement_timeout on upstream connections. 0 means disabled (default).\n","maximum":300000,"minimum":0,"type":"integer"},"role":{"$ref":"#/components/schemas/DatabaseRole"},"ssl_mode":{"$ref":"#/components/schemas/SSLMode"},"updated_at":{"description":"When the database registration was last updated.","format":"date-time","type":"string"},"username":{"description":"PostgreSQL username.","example":"pgbeam","type":"string"}},"required":["id","project_id","host","port","name","username","ssl_mode","cache_config","pool_config","created_at","updated_at"],"type":"object"},"DatabaseRole":{"default":"primary","description":"Database role. Primary receives writes, replicas receive reads.","enum":["primary","replica"],"type":"string"},"DnsInstructions":{"description":"DNS records the user needs to create for domain verification.","properties":{"acme_cname_host":{"description":"The CNAME record host for ACME TLS certificate issuance.","example":"_acme-challenge.db.example.com","type":"string"},"acme_cname_target":{"description":"The CNAME target for ACME challenge delegation.","example":"_acme-challenge.abc.aws.pgbeam.app","type":"string"},"cname_host":{"description":"The CNAME record host.","example":"db.example.com","type":"string"},"cname_target":{"description":"The CNAME record target.","example":"abc.aws.pgbeam.app","type":"string"},"txt_host":{"description":"The TXT record host for verification.","example":"_pgbeam-verify.db.example.com","type":"string"},"txt_value":{"description":"The TXT record value for verification.","example":"pgbeam-verify=abc123token","type":"string"}},"type":"object"},"EnterprisePlanRequest":{"description":"Internal request body for assigning a custom enterprise plan.","properties":{"billing_provider":{"description":"Billing provider for the enterprise org.","enum":["stripe","manual"],"type":"string"},"bytes_per_month":{"description":"Monthly data transfer allowance in bytes. 0 means unlimited.","format":"int64","minimum":0,"type":"integer"},"included_seats":{"description":"Number of seats included in the enterprise plan.","minimum":1,"type":"integer"},"max_connections":{"description":"Maximum concurrent connections allowed per project. 0 means unlimited.","minimum":0,"type":"integer"},"max_databases":{"description":"Maximum databases allowed per project.","minimum":1,"type":"integer"},"max_projects":{"description":"Maximum active projects allowed.","minimum":1,"type":"integer"},"max_query_shapes":{"description":"Maximum query shapes in cache rules. 0 means unlimited.","minimum":0,"type":"integer"},"org_id":{"description":"Organization identifier to update.","minLength":1,"type":"string"},"overage_per_1k":{"description":"Overage price in dollars per 1,000 queries.","format":"double","minimum":0,"type":"number"},"overage_per_gb":{"description":"Overage price in dollars per gigabyte transferred.","format":"double","minimum":0,"type":"number"},"queries_per_day":{"description":"Daily query allowance for the enterprise plan. 0 means unlimited.","format":"int64","minimum":0,"type":"integer"},"queries_per_second":{"description":"Maximum sustained queries per second per project. 0 means unlimited.","minimum":0,"type":"integer"}},"required":["org_id","billing_provider"],"type":"object"},"Error":{"description":"Standard error response envelope for PgBeam API requests.","properties":{"error":{"description":"Error metadata for the failed request.","properties":{"code":{"description":"Machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"HealthResponse":{"description":"Health status and build metadata for the API service.","properties":{"image_sha":{"description":"Resolved image SHA (digest or SHA tag).","example":"f1f01eda9e1bc25a3a1d28b1e18c5579fa9a128fede12169d3a392504f9729e4","type":"string"},"status":{"description":"Overall service health.","enum":["ok","degraded"],"type":"string"},"timestamp":{"description":"Server time.","format":"date-time","type":"string"},"version":{"description":"API server version.","example":"1.0.0","type":"string"}},"required":["status","version","image_sha"],"type":"object"},"LatencySummary":{"description":"Aggregate latency metrics for the selected time range.","properties":{"avg_ms":{"description":"Average latency in milliseconds across all queries.","format":"double","type":"number"},"p99_ms":{"description":"P99 latency in milliseconds across all queries.","format":"double","type":"number"}},"required":["avg_ms","p99_ms"],"type":"object"},"ListCacheRulesResponse":{"description":"Cursor-paginated cache-rule entries for a database.","properties":{"entries":{"description":"Query shapes returned for the current page.","items":{"$ref":"#/components/schemas/CacheRuleEntry"},"type":"array"},"next_page_token":{"description":"Opaque token for cursor-based pagination.","type":"string"}},"required":["entries"],"type":"object"},"ListCustomDomainsResponse":{"description":"Cursor-paginated list of custom domains for a project.","properties":{"domains":{"description":"Custom domains on the current page.","items":{"$ref":"#/components/schemas/CustomDomain"},"type":"array"},"next_page_token":{"description":"Token for the next page. Empty if no more results.","type":"string"}},"required":["domains"],"type":"object"},"ListDatabasesResponse":{"description":"Cursor-paginated list of databases attached to a project.","properties":{"databases":{"description":"Databases on the current page.","items":{"$ref":"#/components/schemas/Database"},"type":"array"},"next_page_token":{"description":"Token for the next page. Empty if no more results.","type":"string"}},"required":["databases"],"type":"object"},"ListPlansResponse":{"description":"Response envelope for listing available billing plans.","properties":{"plans":{"description":"Billing plans available for self-serve signups.","items":{"$ref":"#/components/schemas/PlanInfo"},"type":"array"}},"required":["plans"],"type":"object"},"ListProjectsResponse":{"description":"Cursor-paginated list of projects for an organization.","properties":{"next_page_token":{"description":"Token for the next page. Empty if no more results.","type":"string"},"projects":{"description":"Projects on the current page.","items":{"$ref":"#/components/schemas/Project"},"type":"array"},"total":{"description":"Total number of projects (across all pages).","type":"integer"}},"required":["projects","total"],"type":"object"},"ListRegionsResponse":{"description":"Response envelope for available region queries.","properties":{"regions":{"description":"Regions currently known to the control plane.","items":{"$ref":"#/components/schemas/Region"},"type":"array"}},"required":["regions"],"type":"object"},"ListReplicasResponse":{"description":"Response envelope for listing registered replicas.","properties":{"next_page_token":{"description":"Opaque token for cursor-based pagination.","type":"string"},"replicas":{"description":"Read replicas attached to the database.","items":{"$ref":"#/components/schemas/Replica"},"type":"array"}},"required":["replicas"],"type":"object"},"MetricsSnapshot":{"description":"Aggregated project metrics captured for a point in time.","properties":{"active_connections":{"description":"Current active proxy connections.","type":"integer"},"avg_connect_ms":{"description":"Average upstream connection acquisition latency in milliseconds.","format":"double","type":"number"},"avg_latency_ms":{"description":"Average end-to-end query latency in milliseconds.","format":"double","type":"number"},"avg_query_ms":{"description":"Average upstream query execution latency in milliseconds.","format":"double","type":"number"},"cache_hits":{"description":"Number of queries served from cache.","format":"int64","type":"integer"},"cache_misses":{"description":"Number of queries forwarded upstream.","format":"int64","type":"integer"},"created_at":{"description":"When the snapshot was recorded.","format":"date-time","type":"string"},"id":{"description":"Unique metrics snapshot identifier.","type":"string"},"p99_latency_ms":{"description":"99th percentile end-to-end query latency in milliseconds.","format":"double","type":"number"},"project_id":{"description":"Project that produced the metrics snapshot.","type":"string"},"queries_total":{"description":"Total queries served during the snapshot interval.","format":"int64","type":"integer"},"region":{"description":"Region where the traffic was served.","type":"string"}},"required":["id","project_id","region","queries_total","cache_hits","cache_misses","active_connections","avg_latency_ms","p99_latency_ms","created_at"],"type":"object"},"OnboardingProgress":{"description":"Progress state for the dashboard onboarding checklist.","properties":{"completed":{"description":"Whether all onboarding steps are complete.","type":"boolean"},"completed_at":{"description":"When onboarding was completed. Null if not yet completed.","format":"date-time","nullable":true,"type":"string"},"connection_string_copied":{"description":"Whether the connection string has been copied.","type":"boolean"},"connection_tested":{"description":"Whether the database connection has been tested.","type":"boolean"},"database_added":{"description":"Whether a database has been added.","type":"boolean"},"dismissed":{"description":"Whether the user has dismissed the onboarding checklist.","type":"boolean"},"first_query_run":{"description":"Whether the first query has been run through PgBeam.","type":"boolean"},"org_created":{"description":"Whether the organization has been created.","type":"boolean"},"organization_id":{"description":"Organization ID this onboarding belongs to.","type":"string"},"project_created":{"description":"Whether a project has been created.","type":"boolean"},"steps_completed":{"description":"Number of completed onboarding steps.","type":"integer"},"steps_total":{"description":"Total number of onboarding steps.","type":"integer"}},"required":["organization_id","org_created","project_created","database_added","connection_tested","connection_string_copied","first_query_run","dismissed","completed","steps_completed","steps_total"],"type":"object"},"OrganizationPlan":{"description":"Billing state and plan limits for an organization.","properties":{"billing_provider":{"description":"Which billing provider manages this organization's subscription.","enum":["stripe","vercel","aws","manual"],"type":"string"},"created_at":{"description":"When the billing record was created.","format":"date-time","type":"string"},"current_period_end":{"description":"End of current billing period.","format":"date-time","type":"string"},"custom_pricing":{"description":"Whether the organization has custom enterprise pricing.","type":"boolean"},"enabled":{"description":"Whether the organization billing is active (false = suspended).","type":"boolean"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"org_id":{"description":"Organization identifier the plan applies to.","example":"org_abc123","type":"string"},"plan":{"description":"Current plan tier.","enum":["starter","pro","scale","enterprise"],"type":"string"},"spend_limit":{"description":"Monthly spend limit in dollars. Null means no limit.","example":500,"format":"double","nullable":true,"type":"number"},"subscription_status":{"description":"Stripe subscription status.","enum":["none","active","trialing","past_due","canceled","unpaid","incomplete","incomplete_expired","paused"],"type":"string"},"updated_at":{"description":"When the billing record was last updated.","format":"date-time","type":"string"}},"required":["org_id","plan","limits"],"type":"object"},"PlanInfo":{"description":"Publicly visible plan metadata and limits.","properties":{"annual_price":{"description":"Annual price in dollars (if applicable).","type":"integer"},"description":{"description":"Short description of the plan.","type":"string"},"label":{"description":"Display label for the plan.","type":"string"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"monthly_price":{"description":"Monthly price in dollars.","type":"integer"},"name":{"description":"Plan tier name (starter, pro, scale).","type":"string"},"overage_text":{"description":"Human-readable overage pricing text.","type":"string"},"trial_days":{"description":"Number of trial days for new signups.","type":"integer"}},"required":["name","label","monthly_price","limits"],"type":"object"},"PlanLimits":{"description":"Effective usage limits enforced for an organization plan.","properties":{"bytes_per_month":{"description":"Monthly data transfer quota in bytes. 0 means unlimited.","format":"int64","type":"integer"},"included_seats":{"description":"Number of seats included in the plan.","type":"integer"},"max_connections":{"description":"Maximum concurrent connections per project.","type":"integer"},"max_databases":{"description":"Maximum databases per project.","type":"integer"},"max_projects":{"description":"Maximum number of active projects.","type":"integer"},"max_query_shapes":{"description":"Maximum query shapes in cache rules. 0 means unlimited.","type":"integer"},"queries_per_day":{"description":"Maximum queries per day across all projects. 0 means unlimited.","format":"int64","type":"integer"},"queries_per_second":{"description":"Maximum queries per second per project.","type":"integer"}},"required":["queries_per_day","max_projects","max_databases","max_connections","queries_per_second","bytes_per_month","max_query_shapes","included_seats"],"type":"object"},"PoolConfig":{"description":"Connection pool configuration.","properties":{"max_active":{"default":200,"description":"Maximum concurrent upstream connections per pool.","maximum":10000,"minimum":1,"type":"integer"},"min_pool_size":{"default":1,"description":"Minimum idle connections maintained.","example":5,"maximum":10000,"minimum":1,"type":"integer"},"pool_mode":{"$ref":"#/components/schemas/PoolMode"},"pool_size":{"default":10,"description":"Maximum connections in the pool.","example":20,"maximum":10000,"minimum":1,"type":"integer"}},"required":["pool_size","min_pool_size","pool_mode"],"type":"object"},"PoolMode":{"description":"Connection pool mode.","enum":["session","transaction","statement"],"example":"transaction","type":"string"},"Project":{"description":"Project configuration and current control-plane state.","properties":{"active_connections":{"description":"Current active connections (latest metrics snapshot). 0 when no metrics data.","readOnly":true,"type":"integer"},"allowed_cidrs":{"description":"IP filtering rules as CIDR ranges with optional labels. When non-empty, only connections from matching IPs are accepted. Empty array means all IPs are allowed (default). Both IPv4 (e.g. 10.0.0.0/8) and IPv6 (e.g. 2001:db8::/32) are supported.\n","example":[{"cidr":"10.0.0.0/8","label":"VPC"},{"cidr":"2001:db8::/32","label":"IPv6 range"}],"items":{"$ref":"#/components/schemas/CidrEntry"},"maxItems":50,"type":"array"},"burst_size":{"description":"Burst allowance above the steady-state rate. 0 uses queries_per_second as burst.","example":200,"format":"int32","maximum":2147483647,"minimum":0,"readOnly":true,"type":"integer"},"cloud":{"description":"Cloud provider where the project runs.","enum":["aws","azure","gcp"],"readOnly":true,"type":"string"},"created_at":{"description":"When the project was created.","format":"date-time","type":"string"},"database_count":{"description":"Number of databases attached to this project.","readOnly":true,"type":"integer"},"description":{"description":"Optional project description.","example":"Production database proxy","maxLength":500,"type":"string"},"id":{"description":"Unique project identifier (prefixed).","example":"prj_01h455vb4pex5vsknk084sn02q","type":"string"},"max_connections":{"description":"Maximum concurrent proxy connections. 0 means unlimited.","example":500,"format":"int32","maximum":2147483647,"minimum":0,"readOnly":true,"type":"integer"},"name":{"description":"Human-readable project name.","example":"my-app","maxLength":100,"minLength":1,"type":"string"},"org_id":{"description":"Better Auth organization ID that owns this project.","example":"org_abc123","type":"string"},"proxy_host":{"description":"Proxy hostname for connecting through PgBeam (e.g., myproject.aws.pgbeam.app).","readOnly":true,"type":"string"},"queries_per_second":{"description":"Maximum queries per second for this project. 0 means unlimited.","example":1000,"format":"int32","maximum":2147483647,"minimum":0,"readOnly":true,"type":"integer"},"status":{"$ref":"#/components/schemas/ProjectStatus"},"tags":{"description":"User-defined labels applied to the project.","example":["production","us-east-1"],"items":{"maxLength":50,"type":"string"},"maxItems":10,"type":"array"},"updated_at":{"description":"When the project was last updated.","format":"date-time","type":"string"}},"required":["id","org_id","name","status","created_at","updated_at"],"type":"object"},"ProjectDailyUsage":{"description":"Daily usage totals for a single project and region.","properties":{"bytes_transferred":{"description":"Total bytes transferred to clients.","format":"int64","type":"integer"},"cache_hits":{"description":"Total cache hits on the day.","format":"int64","type":"integer"},"cache_misses":{"description":"Total cache misses on the day.","format":"int64","type":"integer"},"connection_seconds":{"description":"Total proxy connection time consumed on the day.","format":"int64","type":"integer"},"day":{"description":"Usage date in UTC.","format":"date","type":"string"},"queries_total":{"description":"Total queries served on the day.","format":"int64","type":"integer"},"region":{"description":"Region where the traffic was served.","type":"string"}},"required":["day","region","queries_total","cache_hits","cache_misses","connection_seconds","bytes_transferred"],"type":"object"},"ProjectInsights":{"description":"Query insights, cache performance, and latency for a project.","properties":{"cache":{"$ref":"#/components/schemas/CacheSummary"},"latency":{"$ref":"#/components/schemas/LatencySummary"},"queries":{"description":"Top query shapes observed for the project.","items":{"$ref":"#/components/schemas/QueryInsight"},"type":"array"}},"required":["queries","cache","latency"],"type":"object"},"ProjectMetricsResponse":{"description":"Response envelope for recent project metrics snapshots.","properties":{"snapshots":{"description":"Metrics snapshots ordered from newest to oldest.","items":{"$ref":"#/components/schemas/MetricsSnapshot"},"type":"array"}},"required":["snapshots"],"type":"object"},"ProjectStatus":{"description":"Project lifecycle status.","enum":["active","suspended","deleted"],"type":"string"},"ProjectUsageResponse":{"description":"Response envelope for project usage queries.","properties":{"usage":{"description":"Daily usage entries grouped by region for the project.","items":{"$ref":"#/components/schemas/ProjectDailyUsage"},"type":"array"}},"required":["usage"],"type":"object"},"QueryInsight":{"description":"Aggregated analytics for a normalized SQL query shape.","properties":{"avg_latency_ms":{"description":"Average query latency in milliseconds.","format":"double","type":"number"},"p99_latency_ms":{"description":"P99 query latency in milliseconds.","format":"double","type":"number"},"query_hash":{"description":"xxhash64 of the normalized SQL pattern (hex).","type":"string"},"query_pattern":{"description":"Normalized SQL pattern (truncated to 500 chars).","type":"string"},"total_cache_hits":{"description":"Total cache hits attributed to the query shape.","format":"int64","type":"integer"},"total_cache_misses":{"description":"Total cache misses attributed to the query shape.","format":"int64","type":"integer"},"total_count":{"description":"Total number of executions in the time range.","format":"int64","type":"integer"}},"required":["query_hash","query_pattern","total_count","total_cache_hits","total_cache_misses","avg_latency_ms","p99_latency_ms"],"type":"object"},"ReconcileResponse":{"description":"Result summary for an internal billing reconciliation run.","properties":{"orgs_checked":{"description":"Number of organizations inspected during reconciliation.","type":"integer"},"orgs_updated":{"description":"Number of organizations whose billing state changed.","type":"integer"},"status":{"description":"Result of the reconciliation run.","type":"string"}},"required":["status"],"type":"object"},"RecordConsentRequest":{"description":"Request body for recording acceptance of a legal document.","properties":{"document_type":{"description":"Legal document that was accepted.","enum":["terms_of_service","privacy_policy"],"type":"string"},"document_version":{"description":"Version of the accepted document.","minLength":1,"type":"string"},"ip_address":{"description":"IP address captured when consent was recorded.","type":"string"},"user_id":{"description":"User identifier the consent applies to.","minLength":1,"type":"string"}},"required":["user_id","document_type","document_version"],"type":"object"},"Region":{"description":"Data plane region available for PgBeam traffic.","properties":{"available":{"description":"Whether new projects can currently be assigned to the region.","type":"boolean"},"continent":{"description":"Continent where the region is located.","type":"string"},"country":{"description":"Country where the region is located.","type":"string"},"id":{"description":"Region identifier (e.g. us-east-1).","example":"us-east-1","type":"string"},"name":{"description":"Human-readable region name.","example":"US East (N. Virginia)","type":"string"},"provider":{"description":"Cloud provider.","enum":["aws","azure","gcp"],"example":"aws","type":"string"},"status":{"description":"Region operational status.","enum":["active","draining","inactive"],"type":"string"}},"required":["id","name","provider","status","available"],"type":"object"},"Replica":{"description":"Read replica registered for a primary database.","properties":{"created_at":{"description":"When the replica was created.","format":"date-time","type":"string"},"database_id":{"description":"Parent database ID.","example":"db_01h455vb4pex5vsknk084sn02q","type":"string"},"host":{"description":"PostgreSQL replica host.","example":"replica.db.example.com","type":"string"},"id":{"description":"Unique replica identifier (prefixed).","example":"rep_01h455vb4pex5vsknk084sn02q","type":"string"},"port":{"description":"PostgreSQL replica port.","example":5432,"maximum":65535,"minimum":1,"type":"integer"},"ssl_mode":{"$ref":"#/components/schemas/SSLMode"},"updated_at":{"description":"When the replica was last updated.","format":"date-time","type":"string"}},"required":["id","database_id","host","port","ssl_mode","created_at","updated_at"],"type":"object"},"SSLMode":{"description":"PostgreSQL SSL connection mode.","enum":["disable","allow","prefer","require","verify-ca","verify-full"],"example":"require","type":"string"},"SyncPlanRequest":{"description":"Internal request body for syncing a subscription plan from the dashboard.","properties":{"org_id":{"description":"Organization identifier to update.","minLength":1,"type":"string"},"plan":{"description":"Plan tier to apply.","enum":["starter","pro","scale"],"type":"string"},"status":{"description":"Current subscription lifecycle status.","enum":["none","active","trialing","past_due","canceled","unpaid","incomplete","incomplete_expired","paused"],"type":"string"},"stripe_customer_id":{"description":"Stripe customer identifier, if billing is managed in Stripe.","type":"string"},"stripe_subscription_id":{"description":"Stripe subscription identifier, if present.","type":"string"}},"required":["org_id","plan","status"],"type":"object"},"SyncPlanResponse":{"description":"Result returned after syncing subscription state from the dashboard.","properties":{"status":{"description":"Result of the sync operation (synced, skipped_custom_pricing).","type":"string"}},"required":["status"],"type":"object"},"TestConnectionResult":{"description":"Result of testing connectivity to an upstream database.","properties":{"error":{"description":"Error message if the connection test failed.","type":"string"},"latency_ms":{"description":"Round-trip connection time in milliseconds.","nullable":true,"type":"number"},"ok":{"description":"Whether the connection test succeeded.","type":"boolean"},"server_version":{"description":"PostgreSQL server version string, if available.","type":"string"}},"required":["ok"],"type":"object"},"UpdateCacheRuleRequest":{"description":"Request body for updating cache behavior of a query shape.","properties":{"cache_enabled":{"description":"Whether to enable caching for this query shape.","type":"boolean"},"cache_swr_seconds":{"description":"SWR override in seconds. Null to use project default.","example":60,"maximum":86400,"minimum":0,"nullable":true,"type":"integer"},"cache_ttl_seconds":{"description":"TTL override in seconds. Null to use project default.","example":300,"maximum":86400,"minimum":0,"nullable":true,"type":"integer"}},"required":["cache_enabled"],"type":"object"},"UpdateCacheRuleResponse":{"description":"Response returned after updating a cache rule.","properties":{"entry":{"$ref":"#/components/schemas/CacheRuleEntry"}},"required":["entry"],"type":"object"},"UpdateDatabaseRequest":{"description":"Request body for partially updating an upstream database.","properties":{"auto_read_routing":{"description":"Auto-route SELECT queries to read replicas.\n","type":"boolean"},"cache_config":{"$ref":"#/components/schemas/CacheConfig"},"host":{"description":"Updated PostgreSQL host.","example":"db.example.com","minLength":1,"pattern":"^[^\\x00]+$","type":"string"},"name":{"description":"Updated PostgreSQL database name.","example":"mydb","pattern":"^[^\\x00]*$","type":"string"},"password":{"description":"Updated PostgreSQL password.","format":"password","pattern":"^[^\\x00]*$","type":"string","writeOnly":true},"pool_config":{"$ref":"#/components/schemas/PoolConfig"},"pool_region":{"description":"Region where the connection pool is maintained (near the database). When set and different from the client's edge region, queries are relayed through the pool region's data plane. Empty means direct connection.\n","example":"us-east-1","type":"string"},"port":{"description":"Updated PostgreSQL port.","example":5432,"maximum":65535,"minimum":1,"type":"integer"},"query_timeout_ms":{"description":"Query timeout in milliseconds. 0 means disabled.\n","maximum":300000,"minimum":0,"type":"integer"},"role":{"$ref":"#/components/schemas/DatabaseRole"},"ssl_mode":{"$ref":"#/components/schemas/SSLMode"},"username":{"description":"Updated PostgreSQL username.","example":"pgbeam","pattern":"^[^\\x00]*$","type":"string"}},"type":"object"},"UpdateOnboardingRequest":{"description":"Request body for advancing or dismissing onboarding.","properties":{"dismiss":{"description":"Set to true to dismiss the onboarding checklist.","type":"boolean"},"step":{"description":"The onboarding step to mark as complete.","enum":["project_created","database_added","connection_tested","connection_string_copied","first_query_run"],"example":"project_created","type":"string"}},"type":"object"},"UpdateProjectRequest":{"description":"Request body for partially updating a project.","properties":{"allowed_cidrs":{"description":"IP filtering rules as CIDR ranges with optional labels. Empty array means allow all. Both IPv4 and IPv6 CIDR notation are supported.\n","example":[{"cidr":"10.0.0.0/8","label":"VPC"},{"cidr":"203.0.113.5/32","label":"Office"}],"items":{"$ref":"#/components/schemas/CidrEntry"},"maxItems":50,"type":"array"},"description":{"description":"Updated project description.","example":"Production database proxy","maxLength":500,"type":"string"},"name":{"description":"Updated project name.","example":"my-app","maxLength":100,"minLength":1,"pattern":"^[^\\x00]*$","type":"string"},"status":{"$ref":"#/components/schemas/ProjectStatus"},"tags":{"description":"Replacement set of user-defined project labels.","example":["production","us-east-1"],"items":{"maxLength":50,"type":"string"},"maxItems":10,"type":"array"}},"type":"object"},"UpdateSpendLimitRequest":{"description":"Request body for updating an organization's monthly spend cap.","properties":{"spend_limit":{"description":"Monthly spend limit in dollars. Null to remove the limit.","example":500,"format":"double","nullable":true,"type":"number"}},"type":"object"},"UsageResponse":{"description":"Response envelope for organization usage queries.","properties":{"usage":{"description":"Daily usage entries aggregated across the organization.","items":{"$ref":"#/components/schemas/DailyUsage"},"type":"array"}},"required":["usage"],"type":"object"},"VerifyCustomDomainResponse":{"description":"Result of checking DNS ownership for a custom domain.","properties":{"domain":{"$ref":"#/components/schemas/CustomDomain"},"error":{"description":"Error message if verification failed.","type":"string"},"verified":{"description":"Whether DNS verification succeeded.","type":"boolean"}},"required":["verified"],"type":"object"}},"securitySchemes":{"AWSMarketplaceAuth":{"description":"AWS Marketplace registration token or shared secret for SNS webhook verification.","in":"header","name":"X-Amz-Marketplace-Token","type":"apiKey"},"ApiKeyAuth":{"bearerFormat":"APIKey","description":"API key issued via the dashboard. Pass it as `Authorization: Bearer \u003capi-key\u003e`.","scheme":"bearer","type":"http"},"BearerAuth":{"bearerFormat":"JWT","description":"JWT issued by Better Auth. Verified via JWKS.","scheme":"bearer","type":"http"},"InternalSecret":{"description":"Shared secret for dashboard-to-API service calls.","in":"header","name":"X-Internal-Secret","type":"apiKey"},"VercelOIDC":{"bearerFormat":"JWT","description":"Vercel Marketplace OIDC JWT. Verified via JWKS at marketplace.vercel.com.","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"PgBeam","url":"https://pgbeam.com"},"description":"REST API for the PgBeam multi-tenant PostgreSQL proxy platform.\nManages projects, database connections, cache/pool configuration, and regions.\n","license":{"name":"Proprietary","url":"https://pgbeam.com/terms"},"title":"PgBeam Control Plane API","version":"1.0.0"},"openapi":"3.0.0","paths":{"/v1/account/export":{"get":{"description":"Returns all personal data associated with the authenticated user in a structured JSON format. Supports GDPR data portability and CCPA right to know. Audit logs are limited to the most recent 1000 entries.","operationId":"ExportAccountData","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountExport"}}},"description":"Account data export."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Export account data","tags":["Account"]}},"/v1/aws-marketplace/claim":{},"/v1/aws-marketplace/customers/{customerIdentifier}":{"parameters":[{"in":"path","name":"customerIdentifier","required":true,"schema":{"type":"string"}}]},"/v1/aws-marketplace/resolve":{},"/v1/aws-marketplace/webhook":{},"/v1/databases/{database_id}/replicas":{"get":{"description":"Lists all read replicas for a database.","operationId":"ListReplicas","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListReplicasResponse"}}},"description":"List of replicas."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List replicas","tags":["Projects"]},"parameters":[{"$ref":"#/components/parameters/DatabaseId"}],"post":{"description":"Adds a read replica to a database.","operationId":"CreateReplica","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReplicaRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Replica"}}},"description":"Replica created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add a replica","tags":["Projects"]}},"/v1/databases/{database_id}/replicas/{replica_id}":{"delete":{"description":"Removes a read replica from a database.","operationId":"DeleteReplica","responses":{"204":{"description":"Replica deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete a replica","tags":["Projects"]},"parameters":[{"$ref":"#/components/parameters/DatabaseId"},{"$ref":"#/components/parameters/ReplicaId"}]},"/v1/health":{"get":{"description":"Returns the health status of the API server.","operationId":"GetHealth","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"description":"Service is healthy."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Health check","tags":["Platform"]}},"/v1/installations/{installationId}":{"parameters":[{"in":"path","name":"installationId","required":true,"schema":{"type":"string"}}]},"/v1/installations/{installationId}/plans":{"parameters":[{"in":"path","name":"installationId","required":true,"schema":{"type":"string"}}]},"/v1/installations/{installationId}/resources":{"parameters":[{"in":"path","name":"installationId","required":true,"schema":{"type":"string"}}]},"/v1/installations/{installationId}/resources/{resourceId}":{"parameters":[{"in":"path","name":"installationId","required":true,"schema":{"type":"string"}},{"in":"path","name":"resourceId","required":true,"schema":{"type":"string"}}]},"/v1/installations/{installationId}/resources/{resourceId}/plans":{"parameters":[{"in":"path","name":"installationId","required":true,"schema":{"type":"string"}},{"in":"path","name":"resourceId","required":true,"schema":{"type":"string"}}]},"/v1/internal/billing-health":{"get":{"description":"Returns aggregate billing metrics grouped by plan tier,\nbilling provider, and subscription status.\n","operationId":"GetBillingHealth","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingHealthSummary"}}},"description":"Billing health summary."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"InternalSecret":[]}],"summary":"Get billing health summary","tags":["Internal"],"x-internal":true}},"/v1/internal/consent":{"post":{"description":"Records that a user accepted a legal document (terms of service, privacy policy). Called by the dashboard at sign-up.","operationId":"RecordConsent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordConsentRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentRecord"}}},"description":"Consent recorded."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"InternalSecret":[]}],"summary":"Record user consent","tags":["Internal"],"x-internal":true}},"/v1/internal/enterprise-plan":{"post":{"description":"Sets custom enterprise pricing for an organization. Bypasses\nthe standard Stripe subscription flow. Authenticated via internal secret.\n","operationId":"SetEnterprisePlan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterprisePlanRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationPlan"}}},"description":"Enterprise plan set."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"InternalSecret":[]}],"summary":"Set enterprise plan for an organization","tags":["Internal"],"x-internal":true}},"/v1/internal/organizations/{org_id}":{"delete":{"description":"Cleans up PgBeam resources for an organization being deleted.\nSoft-deletes projects, notifies data planes, removes Vercel installations,\nand deletes the organization plan row.\nAuthenticated via internal shared secret (not JWT/API key).\n","operationId":"DeleteOrganizationResources","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"204":{"description":"Organization resources deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"InternalSecret":[]}],"summary":"Delete organization resources","tags":["Internal"],"x-internal":true}},"/v1/internal/reconcile":{"post":{"description":"Forces an immediate Stripe subscription reconciliation cycle.\nAuthenticated via internal shared secret.\n","operationId":"TriggerReconcile","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileResponse"}}},"description":"Reconciliation completed."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"InternalSecret":[]}],"summary":"Trigger on-demand Stripe reconciliation","tags":["Internal"],"x-internal":true}},"/v1/internal/sync-plan":{"post":{"description":"Called by the dashboard's durable workflow after subscription changes.\nAuthenticated via internal shared secret (not JWT/API key).\n","operationId":"SyncPlan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPlanRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPlanResponse"}}},"description":"Plan synced successfully."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"InternalSecret":[]}],"summary":"Sync subscription plan from dashboard","tags":["Internal"],"x-internal":true}},"/v1/mcp":{},"/v1/organizations/{org_id}/cancellation-feedback":{"post":{"description":"Records optional feedback when a user cancels their subscription.","operationId":"SubmitCancellationFeedback","parameters":[{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationFeedbackRequest"}}},"required":true},"responses":{"204":{"description":"Feedback recorded."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Submit cancellation feedback","tags":["Analytics"]}},"/v1/organizations/{org_id}/onboarding":{"get":{"description":"Returns the onboarding checklist progress for an organization.","operationId":"GetOnboardingProgress","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingProgress"}}},"description":"Onboarding progress."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Get onboarding progress","tags":["Account"]},"parameters":[{"$ref":"#/components/parameters/OrgId"}],"patch":{"description":"Mark an onboarding step as complete or dismiss the checklist.","operationId":"UpdateOnboardingProgress","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOnboardingRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingProgress"}}},"description":"Updated onboarding progress."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update onboarding progress","tags":["Account"]}},"/v1/organizations/{org_id}/plan":{"get":{"description":"Returns the current plan and limits for the organization.","operationId":"GetOrganizationPlan","parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationPlan"}}},"description":"Organization plan details."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get organization plan","tags":["Analytics"]}},"/v1/organizations/{org_id}/spend-limit":{"put":{"description":"Sets the monthly spend limit for an organization. Null removes the limit.","operationId":"UpdateSpendLimit","parameters":[{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpendLimitRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationPlan"}}},"description":"Spend limit updated."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Update spend limit","tags":["Analytics"]}},"/v1/organizations/{org_id}/usage":{"get":{"description":"Returns daily usage data aggregated across all projects in the organization.","operationId":"GetOrganizationUsage","parameters":[{"$ref":"#/components/parameters/OrgId"},{"description":"Start date (inclusive, YYYY-MM-DD).","in":"query","name":"start_date","required":true,"schema":{"example":"2024-01-01","format":"date","type":"string"}},{"description":"End date (inclusive, YYYY-MM-DD).","in":"query","name":"end_date","required":true,"schema":{"example":"2024-01-31","format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}},"description":"Daily usage data."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get organization usage","tags":["Analytics"]}},"/v1/plans":{"get":{"description":"Returns all available plan tiers with their limits and pricing.","operationId":"ListPlans","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPlansResponse"}}},"description":"List of available plans."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"List available plans","tags":["Analytics"]}},"/v1/products/{productSlug}/plans":{"parameters":[{"in":"path","name":"productSlug","required":true,"schema":{"type":"string"}}]},"/v1/projects":{"get":{"description":"Lists projects filtered by organization. Requires org_id query parameter.","operationId":"ListProjects","parameters":[{"description":"Organization ID to filter projects.","in":"query","name":"org_id","required":true,"schema":{"example":"org_abc123","pattern":"^[\\x20-\\x7E]+$","type":"string"}},{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"},{"description":"Sort field for projects list.","in":"query","name":"sort_by","schema":{"default":"created_at","enum":["name","created_at","active_connections"],"example":"created_at","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListProjectsResponse"}}},"description":"List of projects."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List projects","tags":["Projects"]},"post":{"description":"Creates a new project within the specified organization.","operationId":"CreateProject","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectResponse"}}},"description":"Project created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create a project","tags":["Projects"]}},"/v1/projects/{project_id}":{"delete":{"description":"Soft-deletes a project and all associated databases.","operationId":"DeleteProject","responses":{"204":{"description":"Project deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete a project","tags":["Projects"]},"get":{"description":"Returns a single project by ID.","operationId":"GetProject","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"Project found."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Get a project","tags":["Projects"]},"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"patch":{"description":"Partially updates a project. Only provided fields are modified.","operationId":"UpdateProject","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"Project updated."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update a project","tags":["Projects"]}},"/v1/projects/{project_id}/databases":{"get":{"description":"Lists all databases registered for the project.","operationId":"ListDatabases","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDatabasesResponse"}}},"description":"List of databases."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List databases","tags":["Databases"]},"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"post":{"description":"Registers a new upstream PostgreSQL database for the project.","operationId":"CreateDatabase","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatabaseRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}},"description":"Database created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add a database","tags":["Databases"]}},"/v1/projects/{project_id}/databases/{database_id}":{"delete":{"description":"Removes a database registration from the project.","operationId":"DeleteDatabase","responses":{"204":{"description":"Database deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete a database","tags":["Databases"]},"get":{"description":"Returns a single database by ID.","operationId":"GetDatabase","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}},"description":"Database found."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Get a database","tags":["Databases"]},"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DatabaseId"}],"patch":{"description":"Partially updates a database connection. Only provided fields are modified.","operationId":"UpdateDatabase","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDatabaseRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}},"description":"Database updated."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update a database","tags":["Databases"]}},"/v1/projects/{project_id}/databases/{database_id}/cache-rules":{"get":{"description":"Returns the cache rules for a database, showing all observed query\nshapes with their stats and cache recommendations.\n","operationId":"ListCacheRules","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCacheRulesResponse"}}},"description":"Cache rule entries."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List cache rules","tags":["Projects"]},"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DatabaseId"}]},"/v1/projects/{project_id}/databases/{database_id}/cache-rules/{query_hash}":{"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DatabaseId"},{"description":"xxhash64 hex of the normalized SQL.","in":"path","name":"query_hash","required":true,"schema":{"maxLength":16,"minLength":16,"pattern":"^[a-f0-9]+$","type":"string"}}],"put":{"description":"Enable or disable caching for a specific query shape, with optional\nTTL and SWR overrides. Requires the query to exist in the cache rules.\n","operationId":"UpdateCacheRule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCacheRuleRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCacheRuleResponse"}}},"description":"Cache rule updated."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update cache rule","tags":["Projects"]}},"/v1/projects/{project_id}/databases/{database_id}/test-connection":{"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DatabaseId"}],"post":{"description":"Attempts to connect to the upstream database using the stored credentials and returns the result.","operationId":"TestDatabaseConnection","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestConnectionResult"}}},"description":"Connection test result."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Test database connection","tags":["Databases"]}},"/v1/projects/{project_id}/domains":{"get":{"description":"Lists all custom domains registered for the project.","operationId":"ListCustomDomains","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCustomDomainsResponse"}}},"description":"List of custom domains."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List custom domains","tags":["Projects"],"x-feature-flag":"custom-domains"},"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"post":{"description":"Registers a new custom domain for the project. Returns DNS verification instructions. Requires a Scale or Enterprise plan.","operationId":"CreateCustomDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomDomainRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDomain"}}},"description":"Custom domain created."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Custom domains require a Scale or Enterprise plan."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add a custom domain","tags":["Projects"],"x-feature-flag":"custom-domains"}},"/v1/projects/{project_id}/domains/{domain_id}":{"delete":{"description":"Removes a custom domain from the project and revokes its TLS certificate.","operationId":"DeleteCustomDomain","responses":{"204":{"description":"Custom domain deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete a custom domain","tags":["Projects"],"x-feature-flag":"custom-domains"},"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DomainId"}]},"/v1/projects/{project_id}/domains/{domain_id}/verify":{"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DomainId"}],"post":{"description":"Checks DNS TXT record to verify domain ownership. Updates domain status on success. Requires a Scale or Enterprise plan.","operationId":"VerifyCustomDomain","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCustomDomainResponse"}}},"description":"Verification result."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Custom domains require a Scale or Enterprise plan."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Verify custom domain DNS","tags":["Projects"],"x-feature-flag":"custom-domains"}},"/v1/projects/{project_id}/insights":{"get":{"description":"Returns aggregated query-level analytics for a project including top queries\nby count, cache hit/miss summary, and latency statistics.\n","operationId":"GetProjectInsights","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"description":"Time range to query. Defaults to 24h.","in":"query","name":"range","schema":{"default":"24h","enum":["1h","6h","24h","7d"],"example":"24h","type":"string"}},{"description":"Maximum number of top queries to return (1-100).","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectInsights"}}},"description":"Query insights for the project."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get query insights for a project","tags":["Analytics"]}},"/v1/projects/{project_id}/metrics":{"get":{"description":"Returns recent project metrics snapshots, optionally filtered by region.","operationId":"GetProjectMetrics","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"description":"Maximum number of recent snapshots to return.","in":"query","name":"limit","schema":{"default":60,"maximum":1000,"minimum":1,"type":"integer"}},{"description":"Filter metrics by region code.","in":"query","name":"region","schema":{"example":"us-east-1","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectMetricsResponse"}}},"description":"Metrics snapshots"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get project metrics","tags":["Projects"]}},"/v1/projects/{project_id}/usage":{"get":{"description":"Returns daily usage data for a specific project, broken down by region.","operationId":"GetProjectUsage","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"description":"Start date (inclusive, YYYY-MM-DD).","in":"query","name":"start_date","required":true,"schema":{"example":"2024-01-01","format":"date","type":"string"}},{"description":"End date (inclusive, YYYY-MM-DD).","in":"query","name":"end_date","required":true,"schema":{"example":"2024-01-31","format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUsageResponse"}}},"description":"Daily usage data by region."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get project usage","tags":["Analytics"]}},"/v1/regions":{"get":{"description":"Returns all active data plane regions.","operationId":"ListRegions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRegionsResponse"}}},"description":"List of regions."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List available regions","tags":["Platform"]}}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"servers":[{"description":"Production","url":"https://api.pgbeam.com"}],"tags":[{"description":"Project lifecycle, custom domains, read replicas, and cache rules","name":"Projects","x-icon":"FolderKanban"},{"description":"Database connection management per project","name":"Databases","x-icon":"Database"},{"description":"Usage metrics, billing data, and query insights","name":"Analytics","x-icon":"ChartLine"},{"description":"Regions and health checks","name":"Platform","x-icon":"Globe"},{"description":"Account data, privacy controls, and onboarding","name":"Account","x-icon":"CircleUser"},{"description":"Internal service-to-service endpoints","name":"Internal"},{"description":"Vercel Marketplace Partner API endpoints","name":"Marketplace"},{"description":"AWS Marketplace integration endpoints","name":"AWSMarketplace"},{"description":"Model Context Protocol (MCP) remote server endpoint","name":"MCP","x-sdk-exclude":["go","ts"]}],"x-iac-resources":{"CacheRule":{"description":"Manages a per-query cache rule. Deletion disables caching (soft-delete).","id-field":"query_hash","operations":{"list":"listCacheRules","upsert":"updateCacheRule"},"soft-delete":{"cache_enabled":false}},"CustomDomain":{"connection-details":["dns_verification_token"],"description":"Manages a custom domain for a PgBeam project.","operations":{"create":"createCustomDomain","delete":"deleteCustomDomain","list":"listCustomDomains","verify":"verifyCustomDomain"}},"Database":{"connection-details":["connection_string"],"description":"Manages an upstream database connection within a PgBeam project.","operations":{"create":"createDatabase","delete":"deleteDatabase","list":"listDatabases","read":"getDatabase","update":"updateDatabase"}},"Project":{"adoption":{"list-query-params":{"org_id":"org_id","page_size":100},"match-fields":["name"]},"connection-details":["proxy_host"],"description":"Manages a PgBeam project with a primary database.","extra-outputs":{"primary_database_id":{"description":"ID of the primary database created with this project.","path":"database.id"}},"operations":{"create":"createProject","delete":"deleteProject","list":"listProjects","read":"getProject","update":"updateProject"}},"Replica":{"description":"Manages a read replica for a PgBeam database.","operations":{"create":"createReplica","delete":"deleteReplica","list":"listReplicas"}},"SpendLimit":{"description":"Manages the monthly spend limit for an organization.","id-field":"org_id","operations":{"read":"getOrganizationPlan","upsert":"updateSpendLimit"},"soft-delete":{"spend_limit":null}}}}