{ "openapi": "3.0.3", "servers": [ { "url": "https://console.neon.tech/api/v2" } ], "info": { "title": "Neon API", "description": "The Neon API allows you to access and manage Neon programmatically. You can use the Neon API to manage API keys, projects, branches, compute endpoints, databases, roles, and operations. For information about these features, refer to the [Neon documentation](https://neon.com/docs/manage/overview/).\n\nYou can run Neon API requests from this API reference using the **Try It** feature. Enter your API key as a **Bearer** token in the **Authorization** section of the page.\n\nYou can create and manage API keys in the Neon Console. See [Manage API keys](https://neon.com/docs/manage/api-keys/) for instructions.", "version": "v2", "contact": { "email": "help@databricks.com" }, "license": { "name": "Proprietary" } }, "x-readme": { "samples-languages": [ "shell" ] }, "security": [ { "BearerAuth": [] }, { "CookieAuth": [] }, { "TokenCookieAuth": [] } ], "tags": [ { "name": "API Key", "description": "These methods allow you to create and manage API keys for your Neon account. For related information, see [Manage API keys](https://neon.com/docs/manage/api-keys)." }, { "name": "Operation", "description": "These methods allow you to view operation details for your Neon project. For related information, see [Operations](https://neon.com/docs/manage/operations)." }, { "name": "Project", "description": "These methods allow you to create and manage Neon projects. For related information, see [Manage projects](https://neon.com/docs/manage/projects)." }, { "name": "Branch", "description": "These methods allow you to create and manage branches in your Neon project. For related information, see [Manage branches](https://neon.com/docs/manage/branches)." }, { "name": "Endpoint", "description": "These methods allow you to create and manage compute endpoints in your Neon project. For related information, see [Manage compute endpoints](https://neon.com/docs/manage/endpoints)." }, { "name": "Snapshot", "description": "These methods allow you to create and manage snapshots." }, { "name": "Preview", "description": "New API methods that are in a Preview state and may be subject to changes." }, { "name": "Region", "description": "These methods allow you to inspect Neon regions." }, { "name": "Users", "description": "These methods allow you to manage your Neon user account." }, { "name": "Consumption", "description": "These methods allow you to view consumption details for your Neon account." }, { "name": "Organizations", "description": "These methods allow you to manage your Neon organizations." }, { "name": "Auth", "description": "These methods allow you to create and manage Neon Auth projects." }, { "name": "Auth (legacy)", "description": "These methods allow you to create and manage Neon Auth projects. Deprecated. See routes with the `Auth` tag instead." }, { "name": "Storage", "description": "These methods allow you to inspect branchable object-storage state for Neon branches." }, { "name": "Buckets", "description": "These methods allow you to create and manage branchable object-storage buckets and their objects." }, { "name": "Functions", "description": "These methods allow you to create and manage functions on your Neon branches." }, { "name": "AI Gateway", "description": "These methods allow you to inspect the AI Gateway endpoint for your Neon branches." }, { "name": "Credentials", "description": "These methods allow you to issue and manage scoped credentials on your Neon branches." } ], "paths": { "/projects/{project_id}/advisors": { "parameters": [ { "name": "project_id", "description": "Neon project ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Get advisor issues", "description": "Analyzes the database for security and performance issues.\nReturns a list of issues categorized by severity (ERROR, WARN, INFO).\n\nRequires read access to the project and Data API enabled.\n", "operationId": "getProjectAdvisorSecurityIssues", "tags": [ "Project" ], "x-stability-level": "alpha", "parameters": [ { "name": "branch_id", "in": "query", "required": false, "description": "Branch ID to analyze. If not specified, the project's default branch is used.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "database_name", "in": "query", "required": false, "description": "Database name to analyze. Required if branch has multiple databases.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter issues by category", "schema": { "$ref": "#/components/schemas/AdvisorCategory" } }, { "name": "min_severity", "in": "query", "required": false, "description": "Minimum severity level to include. For example, WARN returns WARN and ERROR issues, excluding INFO.", "schema": { "type": "string", "enum": [ "INFO", "WARN", "ERROR" ] } } ], "responses": { "200": { "description": "Successfully retrieved security advisor issues", "content": { "application/json": { "schema": { "type": "object", "required": [ "issues" ], "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/AdvisorIssue" } } } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/api_keys": { "get": { "summary": "List API keys", "description": "Retrieves the API keys for your Neon account.\nThe response does not include API key tokens. A token is only provided when creating an API key.\nAPI keys can also be managed in the Neon Console.\nFor more information, see [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "API Key" ], "operationId": "listApiKeys", "responses": { "200": { "description": "Returned the API keys for the Neon account", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeysListResponseItem" }, "example": [ { "id": 165432, "name": "mykey_1", "created_at": "2022-11-15T20:13:35Z", "created_by": { "id": "629982cc-de05-43db-ae16-28f2399c4910", "name": "John Smith", "image": "http://link.to.image" }, "last_used_at": "2022-11-15T20:22:51Z", "last_used_from_addr": "192.0.2.255" }, { "id": 165433, "name": "mykey_2", "created_at": "2022-11-15T20:12:36Z", "created_by": { "id": "629982cc-de05-43db-ae16-28f2399c4910", "name": "John Smith", "image": "http://link.to.image" }, "last_used_at": "2022-11-15T20:15:04Z", "last_used_from_addr": "192.0.2.255" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Create API key", "description": "Creates an API key.\nThe `key_name` is a user-specified name for the key.\nReturns an `id` and `key`; the `key` is a randomly generated, 64-bit token required to access the Neon API.\nStore the key securely \u2014 it is only returned once.\nAPI keys can also be managed in the Neon Console.\nSee [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "API Key" ], "operationId": "createApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" }, "example": { "key_name": "mykey" } } }, "required": true }, "responses": { "200": { "description": "Created an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" }, "example": { "id": 165434, "key": "9v1faketcjbl4sn1013keyd43n2a8qlfakeog8yvp40hx16keyjo1bpds4y2dfms3", "name": "mykey", "created_at": "2022-11-15T20:13:35Z", "created_by": "629982cc-de05-43db-ae16-28f2399c4910" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/api_keys/{key_id}": { "delete": { "summary": "Revoke API key", "description": "Revokes the specified API key.\nAn API key that is no longer needed can be revoked.\nThis action cannot be reversed.\nAPI keys can also be managed in the Neon Console.\nSee [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "API Key" ], "operationId": "revokeApiKey", "parameters": [ { "name": "key_id", "in": "path", "description": "The API key ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Revoked the specified API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRevokeResponse" }, "example": { "id": 165435, "name": "mykey", "created_at": "2022-11-15T20:13:35Z", "created_by": "629982cc-de05-43db-ae16-28f2399c4910", "last_used_at": "2022-11-15T20:15:04Z", "last_used_from_addr": "192.0.2.255", "revoked": true } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/operations/{operation_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "operation_id", "in": "path", "description": "The operation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Retrieve operation details", "description": "Retrieves details for the specified operation.\nAn operation is an action performed on a Neon project resource.\n", "tags": [ "Operation" ], "operationId": "getProjectOperation", "responses": { "200": { "description": "Returned details for the specified operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" }, "example": { "operation": { "id": "a07f8772-1877-4da9-a939-3a3ae62d1d8d", "project_id": "floral-king-961888", "branch_id": "br-bitter-sound-247814", "endpoint_id": "ep-dark-snowflake-942567", "action": "create_timeline", "status": "finished", "failures_count": 0, "created_at": "2022-10-04T18:20:17Z", "updated_at": "2022-10-04T18:20:18Z", "total_duration_ms": 100 } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects": { "get": { "summary": "List projects", "description": "Retrieves a list of projects for the specified organization.\nIf using a personal API key, include the `org_id` parameter to specify which organization to work with.\nIf using an org API key, `org_id` is automatically inferred from the key.\nFor more information, see [Manage organizations using the Neon API](https://neon.com/docs/manage/orgs-api)\nand [Manage projects](https://neon.com/docs/manage/projects/).\n", "tags": [ "Project" ], "operationId": "listProjects", "parameters": [ { "name": "cursor", "description": "Specify the cursor value from the previous response to retrieve the next batch of projects.", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Specify a value from 1 to 400 to limit number of projects in the response.", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10, "maximum": 400 } }, { "name": "search", "description": "Search by project `name` or `id`. You can specify partial `name` or `id` values to filter results.", "in": "query", "schema": { "type": "string" } }, { "name": "org_id", "description": "Search for projects by `org_id`.", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "$ref": "#/components/parameters/TimeoutParam" }, { "name": "recoverable", "description": "Show only deleted projects within the recovery window.\n", "in": "query", "x-stability-level": "beta", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Returned a list of projects for the Neon account", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProjectsResponse" }, { "$ref": "#/components/schemas/PaginationResponse" }, { "$ref": "#/components/schemas/ProjectsApplicationsMapResponse" }, { "$ref": "#/components/schemas/ProjectsIntegrationsMapResponse" } ] }, "example": { "projects": [ { "id": "shiny-wind-028834", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "shiny-wind-028834", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z", "proxy_host": "us-east-2.aws.neon.tech", "cpu_used_sec": 0, "branch_logical_size_limit": 0, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10800, "active_time": 100 }, { "id": "winter-boat-259881", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "winter-boat-259881", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-23T17:52:25Z", "updated_at": "2022-11-23T17:52:25Z", "proxy_host": "us-east-2.aws.neon.tech", "cpu_used_sec": 0, "branch_logical_size_limit": 0, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10800, "active_time": 100, "org_id": "org-morning-bread-81040908" } ], "applications": { "winter-boat-259881": [ "vercel", "github" ] }, "integrations": { "winter-boat-259881": [ "vercel", "github" ] } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Create project", "description": "Creates a Neon project within an organization.\nIf using a personal API key, include the `org_id` parameter to specify which organization to create the project in.\nIf using an org API key, `org_id` is automatically inferred from the key.\nPlan limits define how many projects you can create.\nFor more information, see [Manage projects](https://neon.com/docs/manage/projects/).\n\nYou can specify a region and Postgres version in the request body.\nNeon currently supports PostgreSQL 14, 15, 16, 17, and 18.\nFor supported regions and `region_id` values, see [Regions](https://neon.com/docs/introduction/regions/).\n", "tags": [ "Project" ], "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequest" }, "examples": { "required_attributes_only": { "summary": "Required attributes only", "value": { "project": { "name": "myproject" } } }, "commonly_specified_attributes": { "summary": "Commonly-specified attributes", "value": { "project": { "name": "myproject", "region_id": "aws-us-east-2", "pg_version": 15 } } }, "with_autoscaling": { "summary": "With autoscaling attributes", "value": { "project": { "name": "myproject", "region_id": "aws-us-east-2", "pg_version": 15, "autoscaling_limit_min_cu": 0.25, "autoscaling_limit_max_cu": 1, "provisioner": "k8s-neonvm" } } }, "with_branch_attributes": { "summary": "With branch attributes", "value": { "project": { "name": "myproject", "region_id": "aws-us-east-2", "pg_version": 15, "branch": { "name": "mybranch", "role_name": "sally", "database_name": "mydb" } } } } } } } }, "responses": { "201": { "$ref": "#/components/responses/CreatedProject" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/shared": { "get": { "summary": "List shared projects", "description": "Retrieves a list of projects shared with your Neon account.\nFor more information, see [Manage projects](https://neon.com/docs/manage/projects/).\n", "tags": [ "Project" ], "operationId": "listSharedProjects", "parameters": [ { "name": "cursor", "description": "Specify the cursor value from the previous response to get the next batch of projects.", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Specify a value from 1 to 400 to limit number of projects in the response.", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10, "maximum": 400 } }, { "name": "search", "description": "Search query by name or id.", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/TimeoutParam" } ], "responses": { "200": { "description": "Returned a list of shared projects for the Neon account", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProjectsResponse" }, { "$ref": "#/components/schemas/PaginationResponse" } ] }, "example": { "projects": [ { "id": "shiny-wind-028834", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "shiny-wind-028834", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z", "proxy_host": "us-east-2.aws.neon.tech", "cpu_used_sec": 0, "branch_logical_size_limit": 0, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10800, "active_time": 100 }, { "id": "winter-boat-259881", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "winter-boat-259881", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-23T17:52:25Z", "updated_at": "2022-11-23T17:52:25Z", "proxy_host": "us-east-2.aws.neon.tech", "cpu_used_sec": 0, "branch_logical_size_limit": 0, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10800, "active_time": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve project details", "description": "Retrieves information about the specified project.\nReturned details include the project settings, compute configuration, history retention, owner information, and current usage metrics.\n", "tags": [ "Project" ], "operationId": "getProject", "responses": { "200": { "description": "Returned information about the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "example": { "project": { "id": "shiny-wind-028834", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "shiny-wind-028834", "provisioner": "k8s-pod", "pg_version": 15, "history_retention_seconds": 604800, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z", "proxy_host": "us-east-2.aws.neon.tech", "branch_logical_size_limit": 0, "cpu_used_sec": 10, "owner_id": "1232111", "owner": { "name": "John Smith", "email": "some@email.com", "branches_limit": 10, "subscription_type": "scale" }, "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10500, "data_storage_bytes_hour": 1040, "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "consumption_period_start": "2023-02-01T00:00:00Z", "consumption_period_end": "2023-03-01T00:00:00Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update project", "description": "Updates the specified project.\nConfigurable properties include the project name, default compute settings, history retention period, and IP allowlist.\n", "tags": [ "Project" ], "operationId": "updateProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequest" }, "example": { "project": { "name": "myproject" } } } } }, "responses": { "200": { "description": "Updated the specified project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProjectResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "example": { "operations": [], "project": { "id": "shiny-wind-028834", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "myproject", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-12-04T02:39:25Z", "proxy_host": "us-east-2.aws.neon.tech", "branch_logical_size_limit": 0, "cpu_used_sec": 213230, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10500, "data_storage_bytes_hour": 1040, "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "history_retention_seconds": 604800, "consumption_period_start": "2023-02-01T00:00:00Z", "consumption_period_end": "2023-03-01T00:00:00Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete project", "description": "Deletes the specified project and all its endpoints, branches, databases, and users.\nDeleted projects can be recovered within 7 days using `POST /projects/{project_id}/recover`.\nTo list recoverable projects, use `GET /projects?recoverable=true`.\n", "tags": [ "Project" ], "operationId": "deleteProject", "responses": { "200": { "description": "Deleted the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "example": { "project": { "id": "bold-cloud-468218", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "bold-cloud-468218", "provisioner": "k8s-pod", "pg_version": 15, "created_at": "2022-11-30T18:41:29Z", "updated_at": "2022-11-30T18:41:29Z", "proxy_host": "us-east-2.aws.neon.tech", "cpu_used_sec": 23004200, "branch_logical_size_limit": 0, "owner_id": "1232111", "creation_source": "console", "store_passwords": true, "branch_logical_size_limit_bytes": 10500, "data_storage_bytes_hour": 1040, "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "history_retention_seconds": 604800, "consumption_period_start": "2023-02-01T00:00:00Z", "consumption_period_end": "2023-03-01T00:00:00Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/recover": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Recover a deleted project", "description": "Recovers a deleted project within the 7-day deletion recovery period.\nRestores branches, endpoints, settings, and connection strings.\nSome integrations require manual reconfiguration after recovery.\nTo list recoverable projects, use `GET /projects?recoverable=true`.\n", "tags": [ "Project" ], "operationId": "recoverProject", "x-stability-level": "beta", "responses": { "200": { "description": "Returned the recovered project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecoverResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/operations": { "get": { "summary": "List operations", "description": "Retrieves a list of operations for the specified Neon project.\nThe number of operations returned can be large.\nTo paginate the response, issue an initial request with a `limit` value.\nThen, add the `cursor` value that was returned in the response to the next request.\nOperations older than 6 months may be deleted from our systems.\nIf you need more history than that, you should store your own history.\n", "tags": [ "Operation" ], "operationId": "listProjectOperations", "parameters": [ { "name": "cursor", "description": "Specify the cursor value from the previous response to get the next batch of operations", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Specify a value from 1 to 1000 to limit number of operations in the response", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "responses": { "200": { "$ref": "#/components/responses/ListOperations" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/permissions": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List project access", "description": "Retrieves details about users who have access to the project, including the permission `id`, the granted-to email address, and the date project access was granted.", "tags": [ "Project" ], "operationId": "listProjectPermissions", "responses": { "200": { "description": "Returned project access details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPermissions" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Grant project access", "description": "Grants project access to the account associated with the specified email address.\n", "tags": [ "Project" ], "operationId": "grantPermissionToProject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantPermissionToProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Granted project access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPermission" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/permissions/{permission_id}": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Revoke project access", "description": "Revokes project access from the user associated with the specified permission `id`. You can retrieve a user's permission `id` by listing project access.", "tags": [ "Project" ], "operationId": "revokePermissionFromProject", "responses": { "200": { "description": "Revoked project access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPermission" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/available_preload_libraries": { "get": { "summary": "List available shared preload libraries", "description": "Returns the shared preload libraries available for the specified project's Postgres version.\nShared preload libraries are Postgres extensions that require the `shared_preload_libraries`\nsetting and a compute restart to activate.\nUse this list to determine which libraries can be enabled in the project's\n`settings.preload_libraries` configuration.\n", "tags": [ "Project" ], "operationId": "getAvailablePreloadLibraries", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "responses": { "200": { "description": "Successfully returned available shared preload libraries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailablePreloadLibraries" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/transfer_requests": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create a project transfer request", "description": "Creates a transfer request for the specified project. The request expires after a set period.\nTo accept the request, the recipient calls `PUT /projects/{project_id}/transfer_requests/{request_id}`\nor uses the Neon Console claim link.\nThe optional `ru` parameter redirects the recipient after acceptance.\n", "tags": [ "Project" ], "operationId": "createProjectTransferRequest", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_seconds": { "type": "integer", "format": "int64", "description": "Specifies the validity duration of the transfer request in seconds. If not provided,\nthe request will expire after 24 hours (86,400 seconds).\n" } } } } } }, "responses": { "201": { "description": "Project transfer request created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTransferRequestResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/transfer_requests/{request_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "request_id", "in": "path", "description": "The Neon project transfer request ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "put": { "summary": "Accept a project transfer request", "description": "Accepts a transfer request for the specified project, transferring it to the specified organization\nor user. If org_id is not passed, the project will be transferred to the current user or organization account.\n", "tags": [ "Project" ], "operationId": "acceptProjectTransferRequest", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "description": "The Neon organization ID to transfer the project to. If not provided, the project will be\ntransferred to the current user or organization account.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } } } }, "responses": { "204": { "description": "Project transfer request accepted successfully" }, "406": { "description": "Account doesn't satisfy the plan requirements to own the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptProjectTransferRequestSatisfiesPlanError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/jwks": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List JWKS URLs", "description": "Returns the JWKS URLs available for verifying JWTs used as the authentication mechanism for the specified project.\n", "tags": [ "Project" ], "operationId": "getProjectJWKS", "responses": { "200": { "description": "The JWKS URLs available for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectJWKSResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Add JWKS URL", "description": "Adds a JWKS URL to the specified project for verifying JWTs used as the authentication mechanism.\n\nThe URL must be a valid HTTPS URL that returns a JSON Web Key Set.\n\nThe `provider_name` field allows you to specify which authentication provider you're using (e.g., Clerk, Auth0, AWS Cognito).\n\nThe `branch_id` scopes the JWKS URL to specific branches; if not specified, it applies to all branches.\n\nThe `role_names` scopes the URL to specific roles; if not specified, default roles are used (`authenticator`, `authenticated`, `anonymous`).\n\nThe `jwt_audience` specifies which `aud` values are accepted in JWTs.\n", "tags": [ "Project" ], "operationId": "addProjectJWKS", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectJWKSRequest" } } } }, "responses": { "201": { "description": "The JWKS URL was added to the project's authentication connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKSCreationOperation" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/jwks/{jwks_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "jwks_id", "in": "path", "description": "The JWKS ID", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete JWKS URL", "description": "Removes the specified JWKS URL from the project.\nJWTs signed by keys from the removed URL can no longer authenticate to the project's endpoints.\n", "tags": [ "Project" ], "operationId": "deleteProjectJWKS", "responses": { "200": { "description": "Deleted a JWKS URL from the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKS" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/data-api/{database_name}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "database_name", "in": "path", "description": "The database name", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create Neon Data API", "description": "Creates a new instance of Neon Data API in the specified branch.\nThe Data API exposes a REST interface over the branch database. The `database_name` path parameter determines which database the API serves.\n", "tags": [ "DataAPI" ], "operationId": "createProjectBranchDataAPI", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataAPICreateRequest" } } } }, "responses": { "201": { "description": "Creates a new app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataAPICreateResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update Neon Data API", "description": "Updates the Neon Data API configuration for the specified branch.\nYou can optionally provide settings to update the Data API configuration.\nThe schema cache is always refreshed as part of this operation.\n", "tags": [ "DataAPI" ], "operationId": "updateProjectBranchDataAPI", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataAPIUpdateRequest" } } } }, "responses": { "201": { "description": "Updated the Neon Data API configuration and refreshed the schema cache", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete Neon Data API", "description": "Deletes the Neon Data API for the specified branch.\nExisting connections using the Data API endpoint will fail after deletion.\n", "tags": [ "DataAPI" ], "operationId": "deleteProjectBranchDataAPI", "responses": { "200": { "description": "Deleted the Neon Data API for the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "get": { "summary": "Retrieve Neon Data API configuration", "description": "Retrieves the Neon Data API configuration for the specified branch,\nincluding endpoint URL, enabled state, and database settings.\n", "tags": [ "DataAPI" ], "operationId": "getProjectBranchDataAPI", "responses": { "200": { "description": "Returns the Neon Data API for the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataAPIReponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/auth/create": { "post": { "summary": "Create Neon Auth integration", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth` instead. Creates a project on a third-party authentication provider's platform for use with Neon Auth.\nUse this endpoint if the frontend integration flow can't be used.\n", "tags": [ "Auth (legacy)" ], "operationId": "createNeonAuthIntegration", "deprecated": true, "x-sunset": "2026-03-01", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateIntegrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Creates Neon Auth integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateIntegrationResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve Neon Auth details for the branch", "description": "Retrieves the Neon Auth integration details for the specified branch,\nincluding the auth provider type and integration status.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "getNeonAuth", "responses": { "200": { "description": "Fetched the details of the Neon Auth integration for the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthIntegration" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Enable Neon Auth for the branch", "description": "Enables Neon Auth for the specified branch by connecting it to an authentication provider.\nCreating the integration provisions the `neon_auth` schema in the branch database, which stores user identity data synchronized from the provider.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "createNeonAuth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableNeonAuthIntegrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Enables Neon Auth integration for the branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateIntegrationResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Disable Neon Auth for the branch", "description": "Disables the Neon Auth integration for the specified branch, removing the connection\nto the authentication provider.\nIf `delete_data` is `true`, also deletes the `neon_auth` schema and all associated tables\nfrom the branch database.\nThe integration can be re-enabled by calling `POST /projects/{project_id}/branches/{branch_id}/auth`.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "disableNeonAuth", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "delete_data": { "type": "boolean", "description": "If true, deletes the `neon_auth` schema from the database", "default": false } } } } } }, "responses": { "200": { "description": "Delete the integration with the authentication provider" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/domains": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List trusted redirect URI domains", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/domains` instead. Lists the domains in the redirect_uri whitelist for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "listNeonAuthRedirectURIWhitelistDomains", "responses": { "200": { "description": "Returned the domains in the redirect_uri whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthRedirectURIWhitelistResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Add trusted redirect URI domain", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/domains` instead. Adds a domain to the redirect_uri whitelist for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "addNeonAuthDomainToRedirectURIWhitelist", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAddDomainToRedirectURIWhitelistRequest" } } }, "required": true }, "responses": { "201": { "description": "Added the domain to the redirect_uri whitelist" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete trusted redirect URI domain", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/domains` instead. Deletes a domain from the redirect_uri whitelist for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "deleteNeonAuthDomainFromRedirectURIWhitelist", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthDeleteDomainFromRedirectURIWhitelistRequest" } } }, "required": true }, "responses": { "200": { "description": "Deleted the domain from the redirect_uri whitelist" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/domains": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List domains in redirect_uri whitelist", "description": "Lists the trusted domains in the redirect URI whitelist for the specified branch.\nOnly domains in this list are permitted as redirect targets after authentication.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "listBranchNeonAuthTrustedDomains", "responses": { "200": { "description": "Returned the domains in the redirect_uri whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthRedirectURIWhitelistResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Add domain to redirect_uri whitelist", "description": "Adds a domain to the redirect URI whitelist for the specified branch.\nOnly domains in this list are permitted as redirect targets after authentication.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "addBranchNeonAuthTrustedDomain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAddDomainToRedirectURIWhitelistRequest" } } }, "required": true }, "responses": { "201": { "description": "Added the domain to the redirect_uri whitelist" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete domain from redirect_uri whitelist", "description": "Removes a domain from the redirect URI whitelist for the specified branch.\nAfter removal, the domain can no longer be used as a redirect target after authentication.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "deleteBranchNeonAuthTrustedDomain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthDeleteDomainFromRedirectURIWhitelistRequest" } } }, "required": true }, "responses": { "200": { "description": "Deleted the domain from the redirect_uri whitelist" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/auth/keys": { "post": { "summary": "Create Auth Provider SDK keys", "description": "Generates SDK or API Keys for the auth provider. These might be called different things depending\non the auth provider you're using, but are generally used for setting up the frontend and backend SDKs.\n", "tags": [ "Auth (legacy)" ], "operationId": "createNeonAuthProviderSDKKeys", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateAuthProviderSDKKeysRequest" } } }, "required": true }, "responses": { "201": { "description": "Creates Auth Provider SDK keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateIntegrationResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/auth/user": { "post": { "summary": "Create new auth user", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/users` instead. Creates a new user in Neon Auth.\nThe user will be created in your neon_auth.users_sync table and automatically propagated to your auth project, whether Neon-managed or provider-owned.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "createNeonAuthNewUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateNewUserRequest" } } }, "required": true }, "responses": { "201": { "description": "Creates new user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateNewUserResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/users": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create new auth user", "description": "Creates a new user in the Neon Auth user directory for the specified branch.\nThe user is created in the `neon_auth.users_sync` table and can immediately authenticate\nusing the branch's configured auth providers.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "createBranchNeonAuthNewUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchNeonAuthNewUserRequest" } } }, "required": true }, "responses": { "201": { "description": "Creates new user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthCreateNewUserResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "auth_user_id", "in": "path", "description": "The Neon user ID", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete auth user", "description": "Deletes the specified user from the Neon Auth user directory for the specified branch.\nRemoves the user record from `neon_auth.users_sync`. This action cannot be undone.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "deleteBranchNeonAuthUser", "responses": { "204": { "description": "Deleted the auth user" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}/role": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "auth_user_id", "in": "path", "description": "The Neon user ID", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Update auth user role", "description": "Updates the role of a user in the Neon Auth user directory for the specified branch.\nThe role controls the user's level of access within the Neon Auth integration.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthUserRole", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNeonAuthUserRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated the auth user role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNeonAuthUserRoleResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/users/{auth_user_id}": { "delete": { "summary": "Delete auth user", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}` instead. Deletes the auth user for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "deleteNeonAuthUser", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "auth_user_id", "in": "path", "description": "The Neon user ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted the auth user" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/auth/transfer_ownership": { "post": { "summary": "Transfer Neon-managed auth project to your own account", "description": "Transfers ownership of your Neon-managed auth project to your own auth provider account.\n", "tags": [ "Auth (legacy)" ], "operationId": "transferNeonAuthProviderProject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthTransferAuthProviderProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Transfer initiated. Follow the URL to complete the process in your auth provider's UI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthTransferAuthProviderProjectResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/integrations": { "get": { "summary": "List active integrations with auth providers", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth` instead.", "tags": [ "Auth (legacy)" ], "operationId": "listNeonAuthIntegrations", "deprecated": true, "x-sunset": "2026-03-01", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "responses": { "200": { "description": "Return management API keys metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNeonAuthIntegrationsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/oauth_providers": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List OAuth providers", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/oauth_providers` instead. Lists the OAuth providers for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "listNeonAuthOauthProviders", "responses": { "200": { "description": "Returns the OAuth providers for the Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNeonAuthOauthProvidersResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Add an OAuth provider", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/oauth_providers` instead.\nAdds an OAuth provider to the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "addNeonAuthOauthProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAddOAuthProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "The OAuth provider has been added to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/oauth_providers": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List OAuth providers for the branch", "description": "Lists the OAuth providers configured for the specified branch's Neon Auth integration.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "listBranchNeonAuthOauthProviders", "responses": { "200": { "description": "Returns the OAuth providers for the Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNeonAuthOauthProvidersResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Add an OAuth provider", "description": "Adds an OAuth provider configuration to the specified branch's Neon Auth integration.\nAfter adding, users can authenticate using the configured provider.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "addBranchNeonAuthOauthProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAddOAuthProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "The OAuth provider has been added to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/oauth_providers/{oauth_provider_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "oauth_provider_id", "in": "path", "description": "The OAuth provider ID", "required": true, "schema": { "$ref": "#/components/schemas/NeonAuthOauthProviderId" } } ], "patch": { "summary": "Update OAuth provider", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/oauth_providers/{oauth_provider_id}` instead. Updates a OAuth provider for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "updateNeonAuthOauthProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthUpdateOAuthProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "The OAuth provider has been added to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete OAuth provider", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/oauth_providers/{oauth_provider_id}` instead. Deletes a OAuth provider from the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "deleteNeonAuthOauthProvider", "responses": { "200": { "description": "Deleted the OAuth provider from the project" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/oauth_providers/{oauth_provider_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "oauth_provider_id", "in": "path", "description": "The OAuth provider ID", "required": true, "schema": { "$ref": "#/components/schemas/NeonAuthOauthProviderId" } } ], "patch": { "summary": "Update OAuth provider", "description": "Updates a OAuth provider for the specified project.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "updateBranchNeonAuthOauthProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthUpdateOAuthProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "The OAuth provider has been added to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete OAuth provider", "description": "Deletes a OAuth provider from the specified project.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "deleteBranchNeonAuthOauthProvider", "responses": { "200": { "description": "Deleted the OAuth provider from the project" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/email_server": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve email server configuration", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/email_provider` instead. Gets the email server configuration for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "getNeonAuthEmailServer", "responses": { "200": { "description": "Returns the email server configuration for the Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update email server configuration", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth/email_provider` instead. Updates the email server configuration for the specified project.\n", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "updateNeonAuthEmailServer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } }, "required": true }, "responses": { "200": { "description": "The OAuth provider has been added to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/send_test_email": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Send test email", "description": "Sends a test email using the configured email server settings to verify SMTP connectivity and credentials.\nThe request body must include the SMTP server settings\n(`host`, `port`, `username`, `password`, `sender_email`, `sender_name`) and the `recipient_email` address.\n", "tags": [ "Auth" ], "x-stability-level": "beta", "operationId": "sendNeonAuthTestEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNeonAuthTestEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Response with the result of the test email send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNeonAuthTestEmailResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/email_and_password": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve email and password configuration", "description": "Retrieves the email and password authentication configuration for the specified branch's Neon Auth integration,\nincluding whether it is enabled and the email verification method.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthEmailAndPasswordConfig", "responses": { "200": { "description": "Returns the email and password configuration for Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailAndPasswordConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update email and password configuration", "description": "Updates the email and password authentication configuration for the specified branch's Neon Auth integration.\nOnly the fields provided in the request body are updated.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthEmailAndPasswordConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailAndPasswordConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "The email and password configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailAndPasswordConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/email_provider": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve email provider configuration", "description": "Retrieves the email provider configuration for the specified branch's Neon Auth integration,\nincluding the provider type and server settings.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthEmailProvider", "responses": { "200": { "description": "Returns the email provider configuration for the Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update email provider configuration", "description": "Updates the email provider configuration for the specified branch's Neon Auth integration.\nThe email provider handles transactional messages such as verification emails and password reset links.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthEmailProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } }, "required": true }, "responses": { "200": { "description": "The email provider configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/auth/integration/{auth_provider}": { "delete": { "summary": "Delete integration with auth provider", "description": "DEPRECATED, use `/projects/{project_id}/branches/{branch_id}/auth` instead.", "tags": [ "Auth (legacy)" ], "deprecated": true, "x-sunset": "2026-03-01", "operationId": "deleteNeonAuthIntegration", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "auth_provider", "in": "path", "description": "The authentication provider name", "required": true, "schema": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "delete_data": { "type": "boolean", "description": "If true, deletes the `neon_auth` schema from the database", "default": false } } } } } }, "responses": { "200": { "description": "Delete the integration with the authentication provider" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/connection_uri": { "get": { "summary": "Retrieve connection URI", "description": "Retrieves a connection URI for the specified database.\nThe URI uses the standard PostgreSQL connection string format. Set `pooled=true` to include the `-pooler` suffix for a connection pooler URI.\n", "tags": [ "Project" ], "operationId": "getConnectionURI", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "query", "description": "The branch ID. Defaults to your project's default `branch_id` if not specified.", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "endpoint_id", "in": "query", "description": "The endpoint ID. Defaults to the read-write `endpoint_id` associated with the `branch_id` if not specified.", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "database_name", "in": "query", "description": "The database name", "required": true, "schema": { "type": "string" } }, { "name": "role_name", "in": "query", "description": "The role name", "required": true, "schema": { "type": "string" } }, { "name": "pooled", "in": "query", "description": "Adds the `-pooler` option to the connection URI when set to `true`, creating a pooled connection URI.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Returned the connection URI", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionURIResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/allow_localhost": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve localhost allow setting", "description": "Retrieves the localhost allow setting for the specified branch's Neon Auth integration.\nWhen enabled, authentication flows work from `localhost` without adding it to the redirect URI whitelist.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthAllowLocalhost", "responses": { "200": { "description": "The allow localhost configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAllowLocalhostResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update localhost allow setting", "description": "Updates the localhost allow setting for the specified branch's Neon Auth integration.\nWhen enabled, authentication flows work from `localhost` without adding it to the redirect URI whitelist.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthAllowLocalhost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNeonAuthAllowLocalhostRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated the allow localhost configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthAllowLocalhostResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/plugins": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve Neon Auth plugin configurations", "description": "Returns all plugin configurations for Neon Auth in a single response.\nThis endpoint aggregates organization, email provider, email and password,\nOAuth providers, and localhost settings.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthPluginConfigs", "responses": { "200": { "description": "Returns all plugin configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthPluginConfigs" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/plugins/organization": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "patch": { "summary": "Update organization plugin configuration", "description": "Updates the organization plugin configuration for Neon Auth.\nThe organization plugin enables multi-tenant organization support.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthOrganizationPlugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOrganizationConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "The organization plugin configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthOrganizationConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/config": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "patch": { "summary": "Update auth configuration", "description": "Updates the auth configuration for the branch.\nCurrently supports updating the application name used in auth emails.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthConfig", "x-internal": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "The auth configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthConfigResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/plugins/magic-link": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "patch": { "summary": "Update magic link plugin configuration", "description": "Updates the magic link plugin configuration for Neon Auth.\nThe magic link plugin enables passwordless authentication via email magic links.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthMagicLinkPlugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthMagicLinkConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "The magic link plugin configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthMagicLinkConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/plugins/phone-number": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve phone number plugin configuration", "description": "Returns the phone number plugin configuration for Neon Auth.\nThe phone number plugin enables phone-based OTP authentication.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthPhoneNumberPlugin", "responses": { "200": { "description": "Returns the phone number plugin configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthPhoneNumberConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update phone number plugin configuration", "description": "Updates the phone number plugin configuration for Neon Auth.\nOnly the fields provided in the request body are updated; omitted fields retain their current values.\nThe phone number plugin enables phone-based OTP authentication.\nOTP codes are delivered via the `send.otp` webhook event with `delivery_preference: \"sms\"`.\nA webhook must be configured with the `send.otp` event enabled for SMS delivery to work.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthPhoneNumberPlugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthPhoneNumberConfigUpdate" } } }, "required": true }, "responses": { "200": { "description": "The phone number plugin configuration has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthPhoneNumberConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/auth/webhooks": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve Neon Auth webhook configuration", "description": "Returns the webhook configuration for the specified branch's Neon Auth integration,\nincluding the endpoint URL and the events that trigger it.\n", "tags": [ "Auth" ], "operationId": "getNeonAuthWebhookConfig", "responses": { "200": { "description": "Returns webhook configuration for Neon Auth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthWebhookConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "put": { "summary": "Update Neon Auth webhook configuration", "description": "Updates the webhook configuration for the specified branch's Neon Auth integration.\nWebhooks notify an external endpoint when auth events occur, such as user creation or sign-in.\n", "tags": [ "Auth" ], "operationId": "updateNeonAuthWebhookConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthWebhookConfig" } } } }, "responses": { "200": { "description": "Returns the updated webhook configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAuthWebhookConfig" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create branch", "description": "Creates a branch in the specified project.\nNo request body is required, but you can specify one to create a compute endpoint or select a non-default parent branch.\nBy default, the branch is created from the project's default branch with no compute endpoint, and the branch name is auto-generated.\nTo access the branch, add a `read_write` endpoint.\nEach branch supports one read-write endpoint and multiple read-only endpoints.\nFor related information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "tags": [ "Branch" ], "operationId": "createProjectBranch", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchCreateRequest" }, { "$ref": "#/components/schemas/AnnotationCreateValueRequest" } ] }, "examples": { "branch_only": { "summary": "Branch only", "value": { "branch": { "parent_id": "br-aged-salad-637688", "name": "mybranch" } } }, "branch_with_endpoint": { "summary": "Branch with endpoint", "value": { "endpoints": [ { "type": "read_write" } ], "branch": { "parent_id": "br-aged-salad-637688", "name": "mybranch" } } } } } }, "required": false }, "responses": { "201": { "$ref": "#/components/responses/CreatedBranch" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "get": { "summary": "List branches", "description": "Retrieves a list of branches for the specified project.\n\nEach Neon project has a root branch named `main`.\nA `branch_id` value has a `br-` prefix.\nA project may contain child branches that were branched from `main` or from another branch.\nA parent branch is identified by the `parent_id` value, which is the `id` of the parent branch.\nFor related information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "tags": [ "Branch" ], "operationId": "listProjectBranches", "parameters": [ { "name": "search", "description": "Search by branch `name` or `id`. You can specify partial `name` or `id` values to filter results.", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "description": "Sort the branches by sort_field. If not provided, branches will be sorted by updated_at descending order", "in": "query", "schema": { "type": "string", "default": "updated_at", "enum": [ "name", "created_at", "updated_at" ] } }, { "$ref": "#/components/parameters/CursorParam" }, { "$ref": "#/components/parameters/SortOrderParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "include_deleted", "description": "If true, return recoverable deleted branches too (soft-deleted within the recovery window).\nIf false or not provided, return only active (non-deleted) branches.\n\nThis parameter is part of the Branch Recovery feature, which is in preview and not available to all users.\n", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Returned a list of branches for the specified project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchesResponse" }, { "$ref": "#/components/schemas/AnnotationsMapResponse" }, { "$ref": "#/components/schemas/CursorPaginationResponse" } ] }, "example": { "branches": [ { "id": "br-aged-salad-637688", "project_id": "shiny-wind-028834", "name": "main", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "logical_size": 28, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, { "id": "br-sweet-breeze-497520", "project_id": "shiny-wind-028834", "parent_id": "br-aged-salad-637688", "parent_lsn": "0/1DE2850", "name": "dev2", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "logical_size": 28, "created_at": "2022-11-30T19:09:48Z", "updated_at": "2022-11-30T19:09:49Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, { "id": "br-raspy-hill-832856", "project_id": "shiny-wind-028834", "parent_id": "br-aged-salad-637688", "parent_lsn": "0/19623D8", "name": "dev1", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "logical_size": 21, "created_at": "2022-11-30T17:36:57Z", "updated_at": "2022-11-30T17:36:57Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" } ], "annotations": { "br-aged-salad-637688": { "object": { "type": "console/branch", "id": "br-aged-salad-637688" }, "value": { "vercel-commit-ref": "test" }, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z" } }, "pagination": { "next": "eyJjcmVhdGV", "sort_by": "updated_at", "sort_order": "desc" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branch_anonymized": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create anonymized branch", "description": "Creates a new branch with anonymized data using PostgreSQL Anonymizer for static masking.\nThis allows developers to work with masked production data.\nOptionally, provide `masking_rules` to set initial masking rules for the branch\nand `start_anonymization` to automatically start anonymization after creation. This\ncombines functionality of updating masking rules and starting anonymization into the\nbranch creation request.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Branch" ], "operationId": "createProjectBranchAnonymized", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchAnonymizedCreateRequest" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/CreatedBranch" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/count": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve number of branches", "description": "Retrieves the total number of branches in the specified project.\nSupports an optional `search` parameter to count branches matching a name filter.\n", "tags": [ "Branch" ], "operationId": "countProjectBranches", "parameters": [ { "name": "search", "description": "Count branches matching the `name` in search query", "in": "query", "schema": { "type": "string" } } ], "responses": { "default": { "$ref": "#/components/responses/GeneralError" }, "200": { "description": "Returned a count of branches for the specified project", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchesCountResponse" } ] } } } } } } }, "/projects/{project_id}/branches/{branch_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve branch details", "description": "Retrieves information about the specified branch.\nA `branch_id` value has a `br-` prefix.\n\nEach Neon project is initially created with a root and default branch named `main`.\nA project can contain one or more branches.\nA parent branch is identified by a `parent_id` value, which is the `id` of the parent branch.\nFor related information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "tags": [ "Branch" ], "operationId": "getProjectBranch", "responses": { "200": { "description": "Returned information about the specified branch", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/AnnotationResponse" } ] }, "example": { "branch": { "id": "br-aged-salad-637688", "project_id": "shiny-wind-028834", "name": "main", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "logical_size": 28, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, "annotation": { "object": { "type": "console/branch", "id": "br-aged-salad-637688" }, "value": { "vercel-commit-ref": "test" }, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete branch", "description": "Deletes the specified branch from a project and places all compute endpoints into an idle state, breaking existing client connections.\n\nThe deletion completes after all operations finish.\nYou cannot delete a project's root or default branch, or a branch that has a child branch.\nA project must have at least one branch.\n\nBy default, deleted branches can be recovered within a 7-day grace period.\nUse the `hard_delete` parameter to permanently delete the branch immediately.\nFor related information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "tags": [ "Branch" ], "operationId": "deleteProjectBranch", "parameters": [ { "name": "hard_delete", "in": "query", "description": "If true, the branch is permanently deleted immediately without a recovery window.\nIf false (default), the branch can be recovered within 7 days via the recover endpoint.\n\nThis parameter is part of the Branch Recovery feature, which is in preview and not available to all users.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Deleted the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOperations" }, "example": { "branch": { "id": "br-aged-salad-637688", "project_id": "shiny-wind-028834", "name": "main", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "logical_size": 28, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, "operations": [ { "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2", "project_id": "shiny-wind-028834", "branch_id": "br-sweet-breeze-497520", "endpoint_id": "ep-soft-violet-752733", "action": "suspend_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-01T19:53:05Z", "updated_at": "2022-12-01T19:53:05Z", "total_duration_ms": 100 }, { "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2", "project_id": "shiny-wind-028834", "branch_id": "br-sweet-breeze-497520", "action": "delete_timeline", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-01T19:53:05Z", "updated_at": "2022-12-01T19:53:05Z", "total_duration_ms": 100 } ] } } } }, "204": { "description": "Returned if the branch doesn't exist or has already been deleted" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "tags": [ "Branch" ], "summary": "Update branch", "description": "Updates the specified branch.\nFor more information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "operationId": "updateProjectBranch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchUpdateRequest" }, "example": { "branch": { "name": "mybranch" } } } }, "required": true }, "responses": { "200": { "description": "Updated the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOperations" }, "example": { "branch": { "id": "br-icy-dream-250089", "project_id": "shiny-wind-028834", "parent_id": "br-aged-salad-637688", "parent_lsn": "0/1E19478", "name": "mybranch", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z", "data_transfer_bytes": 1000000, "written_data_bytes": 100800, "compute_time_seconds": 100, "active_time_seconds": 100, "cpu_used_sec": 100, "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, "operations": [] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/restore": { "post": { "tags": [ "Branch" ], "summary": "Restore branch to a historical state", "description": "Restores a branch to an earlier state in its own or another branch's history\nby specifying an LSN or timestamp.\nCreates a new branch from the historical state.\n", "operationId": "restoreProjectBranch", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchRestoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOperations" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/schema": { "get": { "tags": [ "Branch" ], "summary": "Retrieve database schema", "description": "Retrieves the schema from the specified database. The `lsn` and `timestamp` values cannot be specified at the same time. If both are omitted, the database schema is retrieved from database's head.", "operationId": "getProjectBranchSchema", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "db_name", "in": "query", "description": "Name of the database for which the schema is retrieved", "required": true, "schema": { "type": "string" } }, { "name": "lsn", "in": "query", "description": "The Log Sequence Number (LSN) for which the schema is retrieved\n", "schema": { "type": "string" } }, { "name": "timestamp", "in": "query", "description": "The point in time for which the schema is retrieved\n", "schema": { "type": "string", "format": "date-time", "example": "2022-11-30T20:09:48Z" } }, { "name": "format", "in": "query", "description": "The format of the schema to retrieve. Possible values:\n- `sql` (default)\n- `json`\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schema definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSchemaResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/compare_schema": { "get": { "tags": [ "Branch" ], "summary": "Compare database schema", "description": "Compares the schema from the specified database with another branch's schema.", "operationId": "getProjectBranchSchemaComparison", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "base_branch_id", "in": "query", "description": "The branch ID to compare the schema with", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "db_name", "in": "query", "description": "Name of the database for which the schema is retrieved", "required": true, "schema": { "type": "string" } }, { "name": "lsn", "in": "query", "description": "The Log Sequence Number (LSN) for which the schema is retrieved\n", "schema": { "type": "string" } }, { "name": "timestamp", "in": "query", "description": "The point in time for which the schema is retrieved\n", "schema": { "type": "string", "format": "date-time", "example": "2022-11-30T20:09:48Z" } }, { "name": "base_lsn", "in": "query", "description": "The Log Sequence Number (LSN) for the base branch schema\n", "schema": { "type": "string" } }, { "name": "base_timestamp", "in": "query", "description": "The point in time for the base branch schema\n", "schema": { "type": "string", "format": "date-time", "example": "2022-11-30T20:09:48Z" } } ], "responses": { "200": { "description": "Difference between the schemas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSchemaCompareResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/masking_rules": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "tags": [ "Branch" ], "summary": "Retrieve masking rules", "description": "Retrieves the masking rules for the specified anonymized branch.\nMasking rules define how sensitive data should be anonymized using PostgreSQL Anonymizer.\n\n**Note**: This endpoint is currently in Beta.\n", "operationId": "getMaskingRules", "responses": { "200": { "description": "Masking rules retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskingRulesResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "tags": [ "Branch" ], "summary": "Update masking rules", "description": "Updates the masking rules for the specified anonymized branch.\nMasking rules define how sensitive data should be anonymized using PostgreSQL Anonymizer.\n\n**Note**: This endpoint is currently in Beta.\n", "operationId": "updateMaskingRules", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskingRulesUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Masking rules updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskingRulesResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/anonymized_status": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "tags": [ "Branch" ], "summary": "Retrieve anonymized branch status", "description": "Retrieves the current status of an anonymized branch, including its state and progress information.\nThis endpoint allows you to monitor the anonymization process from initialization through completion.\nOnly anonymized branches will have status information available.\n\n**Note**: This endpoint is currently in Beta.\n", "operationId": "getAnonymizedBranchStatus", "responses": { "200": { "description": "Anonymized branch status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymizedBranchStatusResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/anonymize": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "tags": [ "Branch" ], "summary": "Start anonymization", "description": "Starts the anonymization process for an anonymized branch that is in the initialized, error, or anonymized state.\nThis will apply all defined masking rules to anonymize sensitive data in the branch databases.\nThe branch must be an anonymized branch to start anonymization.\n\n**Note**: This endpoint is currently in Beta.\n", "operationId": "startAnonymization", "responses": { "200": { "description": "Anonymization started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymizedBranchStatusResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/set_as_default": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "tags": [ "Branch" ], "summary": "Set branch as default", "description": "Sets the specified branch as the project's default branch.\nThe default designation is automatically removed from the previous default branch.\nFor more information, see [Manage branches](https://neon.com/docs/manage/branches/).\n", "operationId": "setDefaultProjectBranch", "responses": { "200": { "description": "Updated the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOperations" }, "example": { "branch": { "cpu_used_sec": 1, "active_time_seconds": 1, "compute_time_seconds": 1, "written_data_bytes": 100, "data_transfer_bytes": 100, "id": "br-icy-dream-250089", "project_id": "shiny-wind-028834", "parent_id": "br-aged-salad-637688", "parent_lsn": "0/1E19478", "name": "mybranch", "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:26Z", "default": true, "protected": false, "creation_source": "console", "init_source": "parent-data" }, "operations": [] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/recover": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Recover a deleted branch", "description": "Recovers a deleted branch within the 7-day deletion recovery period.\nThe branch must have been soft deleted and not yet permanently deleted.\nRecovery restores the branch and its endpoints to an idle state.\nConnection strings remain valid after recovery.\nTTL branches become non-TTL branches after recovery.\n\nTo list deleted branches available for recovery, use `GET /projects/{project_id}/branches?include_deleted=true`.\n", "tags": [ "Branch" ], "operationId": "recoverProjectBranch", "x-stability-level": "beta", "responses": { "200": { "description": "Recovered the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchRecoverResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/finalize_restore": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Finalize branch restore from snapshot", "description": "Finalize the restore operation for a branch created from a snapshot.\nThis operation updates the branch so it functions as the original branch it replaced.\nThis includes:\n - Reassigning any computes from the original branch to the restored branch (this will restart the computes)\n - Renaming the restored branch to the original branch's name\n - Renaming the original branch so it no longer uses the original name\n\nThis operation only applies to branches created using the `restoreSnapshot` endpoint with `finalize_restore: false`.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Branch" ], "operationId": "finalizeRestoreBranch", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "used to rename the existing branch when it is replaced. if omitted, a default name is generated and used" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/endpoints": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List branch endpoints", "description": "Retrieves a list of compute endpoints for the specified branch.\nNeon permits only one read-write compute endpoint per branch.\nA branch can have multiple read-only compute endpoints.\n", "tags": [ "Branch" ], "operationId": "listProjectBranchEndpoints", "responses": { "200": { "description": "Returned a list of endpoints for the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointsResponse" }, "example": { "endpoints": [ { "host": "ep-little-smoke-851426.us-east-2.aws.neon.tech", "id": "ep-little-smoke-851426", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-11-23T17:00:00Z", "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-30T18:25:21Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/databases": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List databases", "description": "Retrieves a list of databases for the specified branch.\nA branch can have multiple databases.\nFor related information, see [Manage databases](https://neon.com/docs/manage/databases/).\n", "tags": [ "Branch" ], "operationId": "listProjectBranchDatabases", "responses": { "200": { "description": "Returned a list of databases of the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabasesResponse" }, "example": { "databases": [ { "id": 834686, "branch_id": "br-aged-salad-637688", "name": "main", "owner_name": "casey", "created_at": "2022-11-30T18:25:15Z", "updated_at": "2022-11-30T18:25:15Z" }, { "id": 834686, "branch_id": "br-aged-salad-637688", "name": "mydb", "owner_name": "casey", "created_at": "2022-10-30T17:14:13Z", "updated_at": "2022-10-30T17:14:13Z" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "tags": [ "Branch" ], "summary": "Create database", "description": "Creates a database in the specified branch.\nA branch can have multiple databases.\nFor related information, see [Manage databases](https://neon.com/docs/manage/databases/).\n", "operationId": "createProjectBranchDatabase", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseCreateRequest" }, "example": { "database": { "name": "mydb", "owner_name": "casey" } } } }, "required": true }, "responses": { "201": { "description": "Created a database in the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseOperations" }, "example": { "database": { "id": 876692, "branch_id": "br-aged-salad-637688", "name": "mydb", "owner_name": "casey", "created_at": "2022-12-04T00:15:04Z", "updated_at": "2022-12-04T00:15:04Z" }, "operations": [ { "id": "39426015-db00-40fa-85c5-1c7072df46d0", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "endpoint_id": "ep-little-smoke-851426", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-04T00:15:04Z", "updated_at": "2022-12-04T00:15:04Z", "total_duration_ms": 100 }, { "id": "b7483d4e-33da-4d40-b319-ac858d4d3e69", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "endpoint_id": "ep-little-smoke-851426", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-04T00:15:04Z", "updated_at": "2022-12-04T00:15:04Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/databases/{database_name}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "database_name", "in": "path", "description": "The database name", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Retrieve database details", "description": "Retrieves information about the specified database.\nFor related information, see [Manage databases](https://neon.com/docs/manage/databases/).\n", "tags": [ "Branch" ], "operationId": "getProjectBranchDatabase", "responses": { "200": { "description": "Returned the database details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseResponse" }, "example": { "database": { "id": 834686, "branch_id": "br-aged-salad-637688", "name": "main", "owner_name": "casey", "created_at": "2022-11-30T18:25:15Z", "updated_at": "2022-11-30T18:25:15Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "tags": [ "Branch" ], "summary": "Update database", "description": "Updates the specified database in the branch.\nFor related information, see [Manage databases](https://neon.com/docs/manage/databases/).\n", "operationId": "updateProjectBranchDatabase", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseUpdateRequest" }, "example": { "database": { "name": "mydb", "owner_name": "sally" } } } }, "required": true }, "responses": { "200": { "description": "Updated the database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseOperations" }, "example": { "database": { "id": 876692, "branch_id": "br-aged-salad-637688", "name": "mydb", "owner_name": "sally", "created_at": "2022-12-04T00:15:04Z", "updated_at": "2022-12-04T00:15:04Z" }, "operations": [ { "id": "9ef1c2ed-dce4-43aa-bae8-78aea636bf8a", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "endpoint_id": "ep-little-smoke-851426", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-04T00:21:01Z", "updated_at": "2022-12-04T00:21:01Z", "total_duration_ms": 100 }, { "id": "42dafb46-f861-497b-ae89-f2bec54f4966", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "endpoint_id": "ep-little-smoke-851426", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-04T00:21:01Z", "updated_at": "2022-12-04T00:21:01Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete database", "description": "Deletes the specified database from the branch.\nFor related information, see [Manage databases](https://neon.com/docs/manage/databases/).\n", "tags": [ "Branch" ], "operationId": "deleteProjectBranchDatabase", "responses": { "200": { "description": "Deleted the specified database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseOperations" }, "example": { "database": { "id": 851537, "branch_id": "br-raspy-hill-832856", "name": "mydb", "owner_name": "casey", "created_at": "2022-12-01T19:41:46Z", "updated_at": "2022-12-01T19:41:46Z" }, "operations": [ { "id": "9ef1c2ed-dce4-43aa-bae8-78aea636bf8a", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "endpoint_id": "ep-steep-bush-777093", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-01T19:51:41Z", "updated_at": "2022-12-01T19:51:41Z", "total_duration_ms": 100 }, { "id": "42dafb46-f861-497b-ae89-f2bec54f4966", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "endpoint_id": "ep-steep-bush-777093", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-01T19:51:41Z", "updated_at": "2022-12-01T19:51:41Z", "total_duration_ms": 100 } ] } } } }, "204": { "description": "Returned if the database doesn't exist or has already been deleted" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/roles": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List roles", "description": "Retrieves a list of Postgres roles from the specified branch.\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n", "tags": [ "Branch" ], "operationId": "listProjectBranchRoles", "responses": { "200": { "description": "Returned a list of roles from the specified branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesResponse" }, "example": { "roles": [ { "branch_id": "br-aged-salad-637688", "name": "casey", "protected": false, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z" }, { "branch_id": "br-aged-salad-637688", "name": "thomas", "protected": false, "created_at": "2022-10-22T17:38:21Z", "updated_at": "2022-10-22T17:38:21Z" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Create role", "description": "Creates a Postgres role in the specified branch.\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n\nConnections established to the active compute endpoint will be dropped.\nIf the compute endpoint is idle, the endpoint becomes active for a short period of time and is suspended afterward.\n", "tags": [ "Branch" ], "operationId": "createProjectBranchRole", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleCreateRequest" }, "example": { "role": { "name": "sally" } } } }, "required": true }, "responses": { "201": { "description": "Created a role in the specified branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleOperations" }, "example": { "role": { "branch_id": "br-noisy-sunset-458773", "name": "sally", "password": "Onf1AjayKwe0", "protected": false, "created_at": "2022-12-03T11:58:29Z", "updated_at": "2022-12-03T11:58:29Z" }, "operations": [ { "id": "2c2be371-d5ac-4db5-8b68-79f05e8bc287", "project_id": "shiny-wind-028834", "branch_id": "br-noisy-sunset-458773", "endpoint_id": "ep-small-pine-767857", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-03T11:58:29Z", "updated_at": "2022-12-03T11:58:29Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/roles/{role_name}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "role_name", "in": "path", "description": "The role name", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Retrieve role details", "description": "Retrieves details about the specified role.\nIn Neon, the terms \"role\" and \"user\" are synonymous.\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n", "tags": [ "Branch" ], "operationId": "getProjectBranchRole", "responses": { "200": { "description": "Returned details for the specified role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponse" }, "example": { "role": { "branch_id": "br-noisy-sunset-458773", "name": "casey", "protected": false, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete role", "description": "Deletes the specified Postgres role from the branch.\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n", "tags": [ "Branch" ], "operationId": "deleteProjectBranchRole", "responses": { "200": { "description": "Deleted the specified role from the branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleOperations" }, "example": { "role": { "branch_id": "br-raspy-hill-832856", "name": "thomas", "protected": false, "created_at": "2022-12-01T14:36:23Z", "updated_at": "2022-12-01T14:36:23Z" }, "operations": [ { "id": "db646be3-eace-4910-9f60-8150823c5cb8", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "endpoint_id": "ep-steep-bush-777093", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-01T19:48:11Z", "updated_at": "2022-12-01T19:48:11Z", "total_duration_ms": 100 }, { "id": "ab94cdad-7630-4943-a55e-5a0952d2e598", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "endpoint_id": "ep-steep-bush-777093", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-01T19:48:11Z", "updated_at": "2022-12-01T19:48:11Z", "total_duration_ms": 100 } ] } } } }, "204": { "description": "Returned if the role doesn't exist or has already been deleted" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/roles/{role_name}/reveal_password": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "role_name", "in": "path", "description": "The role name", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Retrieve role password", "description": "Retrieves the password for the specified Postgres role, if possible.\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n", "tags": [ "Branch" ], "operationId": "getProjectBranchRolePassword", "responses": { "200": { "description": "Returned password for the specified role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePasswordResponse" }, "example": { "password": "mypass" } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "412": { "description": "Storing passwords is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/roles/{role_name}/reset_password": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "role_name", "in": "path", "description": "The role name", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reset role password", "description": "Resets the password for the specified Postgres role.\nReturns a new password and operations. The new password is ready to use when the last operation finishes.\nThe old password remains valid until last operation finishes.\nConnections to the compute endpoint are dropped. If idle,\nthe compute endpoint becomes active for a short period of time.\n\nFor related information, see [Manage roles](https://neon.com/docs/manage/roles/).\n", "tags": [ "Branch" ], "operationId": "resetProjectBranchRolePassword", "responses": { "200": { "description": "Reset the password for the specified role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleOperations" }, "example": { "role": { "branch_id": "br-noisy-sunset-458773", "name": "sally", "password": "ClfD0aVuK3eK", "protected": false, "created_at": "2022-12-03T12:39:39Z", "updated_at": "2022-12-03T12:58:18Z" }, "operations": [ { "id": "6bef07a0-ebca-40cd-9100-7324036cfff2", "project_id": "shiny-wind-028834", "branch_id": "br-noisy-sunset-458773", "endpoint_id": "ep-small-pine-767857", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-03T12:58:18Z", "updated_at": "2022-12-03T12:58:18Z", "total_duration_ms": 100 }, { "id": "16b5bfca-4697-4194-a338-d2cdc9aca2af", "project_id": "shiny-wind-028834", "branch_id": "br-noisy-sunset-458773", "endpoint_id": "ep-small-pine-767857", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-03T12:58:18Z", "updated_at": "2022-12-03T12:58:18Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/vpc_endpoints": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List VPC endpoint restrictions", "description": "Lists VPC endpoint restrictions for the specified Neon project.\n", "tags": [ "Project" ], "operationId": "listProjectVPCEndpoints", "responses": { "200": { "description": "Returned VPC endpoint restrictions for the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/vpc_endpoints/{vpc_endpoint_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "vpc_endpoint_id", "in": "path", "description": "The VPC endpoint ID", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Set VPC endpoint restriction", "description": "Sets or updates a VPC endpoint restriction for a Neon project.\nWhen a VPC endpoint restriction is set, the project only accepts connections\nfrom the specified VPC.\nA VPC endpoint can be set as a restriction only after it is assigned to the\nparent organization of the Neon project.\n", "tags": [ "Project" ], "operationId": "assignProjectVPCEndpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointAssignment" } } }, "required": true }, "responses": { "200": { "description": "Configured the specified VPC endpoint as a restriction for the specified project." }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete VPC endpoint restriction", "description": "Removes the specified VPC endpoint restriction from a Neon project.\n", "tags": [ "Project" ], "operationId": "deleteProjectVPCEndpoint", "responses": { "200": { "description": "Removed the VPC endpoint restriction from the specified Neon project" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/endpoints": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create compute endpoint", "description": "Creates a compute endpoint for the specified branch.\nA compute endpoint is a Neon compute instance.\nThere is a maximum of one read-write compute endpoint per branch.\nIf the specified branch already has a read-write compute endpoint, the operation fails.\nA branch can have multiple read-only compute endpoints.\n\nFor more information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "createProjectEndpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointCreateRequest" }, "examples": { "required_attributes_only": { "summary": "Required attributes only", "value": { "endpoint": { "branch_id": "br-floral-mountain-251143", "type": "read_write" } } }, "with_region_attribute": { "summary": "With region attribute", "value": { "endpoint": { "branch_id": "br-floral-mountain-251143", "type": "read_write", "region_id": "aws-us-east-2" } } }, "with_pooler_attribute": { "summary": "With pooler attribute", "value": { "endpoint": { "branch_id": "br-floral-mountain-251143", "type": "read_write", "pooler_enabled": true } } } } } }, "required": true }, "responses": { "201": { "description": "Created a compute endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-shrill-thunder-454069.us-east-2.aws.neon.tech", "id": "ep-shrill-thunder-454069", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "init", "pending_state": "active", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:37:07Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "suspend_timeout_seconds": 10800, "provisioner": "k8s-pod" }, "operations": [ { "id": "874f8bfe-f51d-4c61-85af-a29bea73e0e2", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "start_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:37:07Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "get": { "summary": "List compute endpoints", "description": "Retrieves a list of compute endpoints for the specified project.\nA compute endpoint is a Neon compute instance.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "listProjectEndpoints", "responses": { "200": { "description": "Returned a list of endpoints for the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointsResponse" }, "example": { "endpoints": [ { "host": "ep-little-smoke-851426.us-east-2.aws.neon.tech", "creation_source": "console", "suspend_timeout_seconds": 10800, "provisioner": "k8s-pod", "id": "ep-little-smoke-851426", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-11-23T17:00:00Z", "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-30T18:25:21Z", "proxy_host": "us-east-2.aws.neon.tech" }, { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "creation_source": "console", "suspend_timeout_seconds": 10800, "provisioner": "k8s-pod", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-11-30T17:00:00Z", "created_at": "2022-11-30T17:36:57Z", "updated_at": "2022-11-30T18:42:58Z", "proxy_host": "us-east-2.aws.neon.tech" }, { "host": "ep-soft-violet-752733.us-east-2.aws.neon.tech", "creation_source": "console", "suspend_timeout_seconds": 10800, "provisioner": "k8s-pod", "id": "ep-soft-violet-752733", "project_id": "shiny-wind-028834", "branch_id": "br-sweet-breeze-497520", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-11-30T19:00:00Z", "created_at": "2022-11-30T19:09:48Z", "updated_at": "2022-11-30T19:14:51Z", "proxy_host": "us-east-2.aws.neon.tech" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/endpoints/{endpoint_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "endpoint_id", "in": "path", "description": "The endpoint ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve compute endpoint details", "description": "Retrieves information about the specified compute endpoint.\nA compute endpoint is a Neon compute instance.\nAn `endpoint_id` has an `ep-` prefix.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "getProjectEndpoint", "responses": { "200": { "description": "Returned information about the specified endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" }, "example": { "endpoint": { "host": "ep-little-smoke-851426.us-east-2.aws.neon.tech", "id": "ep-little-smoke-851426", "project_id": "shiny-wind-028834", "branch_id": "br-aged-salad-637688", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-11-23T17:00:00Z", "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-30T18:25:21Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete compute endpoint", "description": "Deletes the specified compute endpoint.\nA compute endpoint is a Neon compute instance.\nDeleting a compute endpoint drops existing network connections to the compute endpoint.\nThe deletion is completed when the last operation in the chain finishes successfully.\n\nAn `endpoint_id` has an `ep-` prefix.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "deleteProjectEndpoint", "responses": { "200": { "description": "Deleted the specified compute endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-12-03T15:00:00Z", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:49:10Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 }, "operations": [ { "id": "fd11748e-3c68-458f-b9e3-66d409e3eef0", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "suspend_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 } ] } } } }, "204": { "description": "Returned if the endpoint doesn't exist or has already been deleted" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "tags": [ "Endpoint" ], "summary": "Update compute endpoint", "description": "Updates the specified compute endpoint.\n\nAn `endpoint_id` has an `ep-` prefix. A `branch_id` has a `br-` prefix.\nFor more information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n\nIf the returned list of operations is not empty, the compute endpoint is not ready to use.\nThe client must wait for the last operation to finish before using the compute endpoint.\nIf the compute endpoint was idle before the update, it becomes active for a short period of time,\nand the control plane suspends it again after the update.\n", "operationId": "updateProjectEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointUpdateRequest" }, "example": { "endpoint": { "suspend_timeout_seconds": 300 } } } } }, "responses": { "200": { "description": "Updated the specified compute endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-12-03T15:00:00Z", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:49:10Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 }, "operations": [ { "id": "3fc98ab8-f191-47b8-a427-5eb668ccc5b9", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "apply_config", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 }, { "id": "9ffda74b-a582-4cff-b0f0-aaa8d14b8e6a", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "suspend_compute", "status": "scheduling", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/endpoints/{endpoint_id}/start": { "post": { "summary": "Start compute endpoint", "description": "Starts a compute endpoint.\nThe compute endpoint is ready to use after the last operation in the chain finishes successfully.\n\nAn `endpoint_id` has an `ep-` prefix.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "startProjectEndpoint", "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "endpoint_id", "in": "path", "description": "The endpoint ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "responses": { "200": { "description": "Started the specified compute endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-12-03T15:00:00Z", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:49:10Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 }, "operations": [ { "id": "e061087e-3c99-4856-b9c8-6b7751a253af", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "start_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/endpoints/{endpoint_id}/suspend": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "endpoint_id", "in": "path", "description": "The endpoint ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Suspend compute endpoint", "description": "Suspends the specified compute endpoint.\nAn `endpoint_id` has an `ep-` prefix.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "suspendProjectEndpoint", "responses": { "200": { "description": "Suspended the specified endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-12-03T15:00:00Z", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:49:10Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 }, "operations": [ { "id": "e061087e-3c99-4856-b9c8-6b7751a253af", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "suspend_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/endpoints/{endpoint_id}/restart": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "endpoint_id", "in": "path", "description": "The endpoint ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Restart compute endpoint", "description": "Restarts the specified compute endpoint by immediately suspending it and then starting it again.\nAn `endpoint_id` has an `ep-` prefix.\nFor information about compute endpoints, see [Manage computes](https://neon.com/docs/manage/endpoints/).\n", "tags": [ "Endpoint" ], "operationId": "restartProjectEndpoint", "responses": { "200": { "description": "Restarted endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointOperations" }, "example": { "endpoint": { "host": "ep-steep-bush-777093.us-east-2.aws.neon.tech", "id": "ep-steep-bush-777093", "project_id": "shiny-wind-028834", "branch_id": "br-raspy-hill-832856", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "idle", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "last_active": "2022-12-03T15:00:00Z", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:49:10Z", "proxy_host": "us-east-2.aws.neon.tech", "creation_source": "console", "provisioner": "k8s-pod", "suspend_timeout_seconds": 10800 }, "operations": [ { "id": "e061087e-3c99-4856-b9c8-6b7751a253af", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "suspend_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 }, { "id": "e061087e-3c99-4856-b9c8-6b7751a253af", "project_id": "bitter-meadow-966132", "branch_id": "br-proud-paper-090813", "endpoint_id": "ep-shrill-thunder-454069", "action": "start_compute", "status": "running", "failures_count": 0, "created_at": "2022-12-03T15:51:06Z", "updated_at": "2022-12-03T15:51:06Z", "total_duration_ms": 100 } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/consumption_history/projects": { "get": { "summary": "Retrieve project consumption metrics (legacy plans)", "description": "Retrieves consumption metrics for Scale, Business, and Enterprise plan projects. History begins at the time of upgrade.\nResults are ordered by time in ascending order (oldest to newest).\nIssuing a call to this API does not wake a project's compute endpoint.\n", "tags": [ "Consumption" ], "operationId": "getConsumptionHistoryPerProject", "parameters": [ { "name": "cursor", "description": "Specify the cursor value from the previous response to get the next batch of projects.", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Specify a value from 1 to 100 to limit number of projects in the response.", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10, "maximum": 100 } }, { "name": "project_ids", "description": "Specify a list of project IDs to filter the response.\nIf omitted, the response will contain all projects.\nA list of project IDs can be specified as an array of parameter values or as a comma-separated list in a single parameter value.\n- As an array of parameter values: `project_ids=cold-poetry-09157238%20&project_ids=quiet-snow-71788278`\n- As a comma-separated list in a single parameter value: `project_ids=cold-poetry-09157238,quiet-snow-71788278`\n", "in": "query", "schema": { "type": "array", "items": { "pattern": "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$", "type": "string" }, "minItems": 0, "maxItems": 100 } }, { "name": "from", "description": "Specify the start `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified `granularity`.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n\nThe consumption history is available starting from `March 1, 2024, at 00:00:00 UTC`.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "to", "description": "Specify the end `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified granularity.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "granularity", "description": "Specify the granularity of consumption metrics.\nHourly, daily, and monthly metrics are available for the last 168 hours, 60 days,\nand 1 year, respectively.\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryGranularity" }, "required": true }, { "name": "org_id", "description": "Specify the organization for which the project consumption metrics should be returned.\nIf this parameter is not provided, the endpoint will return the metrics for the\nauthenticated user's projects.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "include_v1_metrics", "description": "The field is deprecated. Please use `metrics` instead.\nIf `metrics` is specified, this field is ignored.\nInclude metrics utilized in previous pricing models.\n- **data_storage_bytes_hour**: The sum of the maximum observed storage values for each hour,\n which never decreases.\n", "in": "query", "deprecated": true, "schema": { "type": "boolean" } }, { "name": "metrics", "description": "Specify a list of metrics to include in the response.\nIf omitted, active_time, compute_time, written_data, synthetic_storage_size are returned.\nPossible values:\n- `active_time_seconds`\n- `compute_time_seconds`\n- `written_data_bytes`\n- `synthetic_storage_size_bytes`\n- `data_storage_bytes_hour`\n- `logical_size_bytes`\n- `logical_size_bytes_hour`\n\nA list of metrics can be specified as an array of parameter values or as a comma-separated list in a single parameter value.\n- As an array of parameter values: `metrics=cpu_seconds&metrics=ram_bytes`\n- As a comma-separated list in a single parameter value: `metrics=cpu_seconds,ram_bytes`\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryQueryMetrics" } } ], "responses": { "200": { "description": "Returned project consumption metrics for the Neon account", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ConsumptionHistoryPerProjectResponse" }, { "$ref": "#/components/schemas/PaginationResponse" } ] } } } }, "403": { "description": "This endpoint is not available. It is only supported with Scale, Business, and Enterprise plan accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "404": { "description": "Account is not a member of the organization specified by `org_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "406": { "description": "The specified `date-time` range is outside the boundaries of the specified `granularity`.\nAdjust your `from` and `to` values or select a different `granularity`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/consumption_history/v2/projects": { "get": { "summary": "Retrieve project consumption metrics", "description": "Returns consumption metrics for up to `limit` projects per page. If `project_ids` is omitted,\nprojects in the organization are included across pages (use `cursor`). If `project_ids` is\nprovided, the response is limited to those projects (up to 100). Available for accounts on\nLaunch, Scale, Agent, Business, and Enterprise plans.\n\nHistory starts when the account upgrades to an eligible plan.\n\nThe `metrics` query parameter is required. Supported values:\n`compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`,\n`instant_restore_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`,\n`extra_branches_month`, `snapshot_storage_bytes_month`.\n\nConsumption metrics within each project are returned in ascending time order (oldest first).\nThis request does not wake project computes.\n", "tags": [ "Consumption" ], "operationId": "getConsumptionHistoryPerProjectV2", "parameters": [ { "name": "cursor", "description": "Cursor from the previous response (`pagination.cursor`). Pass it to fetch the next page\nof projects. Pages are ordered by project creation order (newest first).\n", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Maximum number of projects per page. Allowed range: 1 to 100. Default: 10.\n", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10, "maximum": 100 } }, { "name": "project_ids", "description": "Optional project IDs to filter the response (up to 100). If omitted, projects in the\norganization are included across pages (use `cursor` and `limit`).\n\nPass multiple IDs as repeated query parameters or a comma-separated list:\n- `project_ids=cold-poetry-09157238&project_ids=quiet-snow-71788278`\n- `project_ids=cold-poetry-09157238,quiet-snow-71788278`\n", "in": "query", "schema": { "type": "array", "items": { "pattern": "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$", "type": "string" }, "minItems": 0, "maxItems": 100 } }, { "name": "from", "description": "Specify the start `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified `granularity`.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n\nThe earliest allowed `from` value is `March 1, 2024, at 00:00:00 UTC`.\nMetrics are returned from when the account upgraded to an eligible plan, which may be\nlater than that date.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "to", "description": "Specify the end `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified `granularity`.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "granularity", "description": "Specify the granularity of consumption metrics.\nHourly, daily, and monthly metrics are available for the last 168 hours, 60 days,\nand 1 year, respectively.\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryGranularity" }, "required": true }, { "name": "org_id", "description": "Organization ID. Metrics are returned for projects in this organization.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "required": true }, { "name": "metrics", "required": true, "description": "Required. List the metrics to return. Supported values:\n- `compute_unit_seconds`\n- `root_branch_bytes_month`\n- `child_branch_bytes_month`\n- `instant_restore_bytes_month`\n- `public_network_transfer_bytes`\n- `private_network_transfer_bytes`\n- `extra_branches_month`\n- `snapshot_storage_bytes_month`\n\nPass multiple values as repeated query parameters or a comma-separated list:\n- `metrics=compute_unit_seconds&metrics=extra_branches_month`\n- `metrics=compute_unit_seconds,extra_branches_month`\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryQueryMetrics" } } ], "responses": { "200": { "description": "Project consumption metrics for the Neon account.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ConsumptionHistoryPerProjectV2Response" }, { "$ref": "#/components/schemas/PaginationResponse" } ] } } } }, "403": { "description": "Not available for this account. Project consumption history requires a Launch, Scale,\nAgent, Business, or Enterprise plan.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "404": { "description": "Account is not a member of the organization specified by `org_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "406": { "description": "The `from` and `to` range is not valid for the selected `granularity`. Adjust the range or\nchoose a different granularity.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/consumption_history/v2/branches": { "get": { "summary": "Retrieve branch consumption metrics", "description": "Returns consumption metrics for each branch across one or more projects listed in\n`project_ids` (1 to 100 projects). Available for accounts on paid usage-based Launch, Scale,\nAgent, and Enterprise plans.\n\nHistory starts when the account first ingests branch-level consumption data.\n\nThe `metrics` query parameter is required. Only these six values are supported on this\nendpoint:\n`compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`,\n`instant_restore_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`.\n\nThis endpoint does not support `extra_branches_month` or `snapshot_storage_bytes_month`.\nUse `GET /consumption_history/v2/projects` for those.\n\nConsumption metrics within each branch are returned in ascending time order (oldest first).\nThis request does not wake project computes.\n", "tags": [ "Consumption" ], "x-stability-level": "beta", "operationId": "getConsumptionHistoryPerBranchV2", "parameters": [ { "name": "cursor", "description": "Cursor from the previous response (`pagination.cursor`). Pass it to fetch the next page\nof branches. Pages are ordered by project ID, then branch ID.\n", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "Maximum number of branches per page. Allowed range: 1 to 1000. Default: 100.\n", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 100, "maximum": 1000 } }, { "name": "project_ids", "description": "Project IDs to include (required, 1 to 100). Returns metrics for branches in these projects.\n\nPass multiple IDs as repeated query parameters or a comma-separated list:\n- `project_ids=cold-poetry-09157238&project_ids=quiet-snow-71788278`\n- `project_ids=cold-poetry-09157238,quiet-snow-71788278`\n", "in": "query", "required": true, "schema": { "type": "array", "items": { "pattern": "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$", "type": "string" }, "minItems": 1, "maxItems": 100 } }, { "name": "branch_ids", "description": "Optional branch IDs to filter the response (up to 100). If omitted, all branches in the\nlisted projects are included.\n\nPass multiple IDs as repeated query parameters or a comma-separated list:\n- `branch_ids=br-aged-salad-637688&branch_ids=br-sweet-breeze-497520`\n- `branch_ids=br-aged-salad-637688,br-sweet-breeze-497520`\n", "in": "query", "schema": { "type": "array", "items": { "pattern": "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$", "type": "string" }, "minItems": 0, "maxItems": 100 } }, { "name": "from", "description": "Specify the start `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified `granularity`.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n\nBranch-level metrics are returned from when the account first ingests branch-level\nconsumption data. Periods before that time contain no branch metrics.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "to", "description": "Specify the end `date-time` for the consumption period.\nThe `date-time` value is rounded according to the specified `granularity`.\nFor example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.\nThe specified `date-time` value must respect the specified `granularity`:\n- For `hourly`, consumption metrics are limited to the last 168 hours.\n- For `daily`, consumption metrics are limited to the last 60 days.\n- For `monthly`, consumption metrics are limited to the last year.\n", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "granularity", "description": "Specify the granularity of consumption metrics.\nHourly, daily, and monthly metrics are available for the last 168 hours, 60 days,\nand 1 year, respectively.\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryGranularity" }, "required": true }, { "name": "org_id", "description": "Organization ID. Metrics are returned for projects in this organization.\n", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "required": true }, { "name": "metrics", "required": true, "description": "Required. List the metrics to return. Only these values are supported:\n- `compute_unit_seconds`\n- `root_branch_bytes_month`\n- `child_branch_bytes_month`\n- `instant_restore_bytes_month`\n- `public_network_transfer_bytes`\n- `private_network_transfer_bytes`\n\nNot supported on this endpoint: `extra_branches_month`, `snapshot_storage_bytes_month`.\nUse `GET /consumption_history/v2/projects` for those.\n\nPass multiple values as repeated query parameters or a comma-separated list:\n- `metrics=compute_unit_seconds&metrics=public_network_transfer_bytes`\n- `metrics=compute_unit_seconds,public_network_transfer_bytes`\n", "in": "query", "schema": { "$ref": "#/components/schemas/ConsumptionHistoryQueryMetrics" } } ], "responses": { "200": { "description": "Branch consumption metrics for the Neon account.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ConsumptionHistoryPerBranchV2Response" }, { "$ref": "#/components/schemas/PaginationResponse" } ] } } } }, "403": { "description": "Not available for this account. Branch consumption history requires a paid usage-based\nLaunch, Scale, Agent, or Enterprise plan.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "404": { "description": "Account is not a member of the organization specified by `org_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "406": { "description": "The `from` and `to` range is not valid for the selected `granularity`. Adjust the range or\nchoose a different granularity.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve organization details", "description": "Retrieves details for the specified organization, including its name, plan, and configuration.\n", "tags": [ "Organizations" ], "operationId": "getOrganization", "responses": { "200": { "description": "Returned information about the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "example": { "id": "my-organization-morning-bread-81040908", "name": "my-organization", "handle": "my-organization-my-organization-morning-bread-81040908", "plan": "scale", "managed_by": "console", "created_at": "2024-02-23T17:42:25Z", "updated_at": "2024-02-26T20:41:25Z", "require_mfa": false } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/api_keys": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List organization API keys", "description": "Retrieves the API keys for the specified organization.\nThe response does not include API key tokens. A token is only provided when creating an API key.\nAPI keys can also be managed in the Neon Console.\nFor more information, see [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "Organizations" ], "operationId": "listOrgApiKeys", "responses": { "200": { "description": "Returned the API keys for the specified organization", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgApiKeysListResponseItem" }, "example": [ { "id": 165432, "name": "orgkey_1", "created_at": "2022-11-15T20:13:35Z", "created_by": { "id": "629982cc-de05-43db-ae16-28f2399c4910", "name": "John Smith", "image": "http://link.to.image" }, "last_used_at": "2022-11-15T20:22:51Z", "last_used_from_addr": "192.0.2.255" }, { "id": 165433, "name": "orgkey_2", "created_at": "2022-11-15T20:12:36Z", "created_by": { "id": "629982cc-de05-43db-ae16-28f2399c4910", "name": "John Smith", "image": "http://link.to.image" }, "last_used_at": "2022-11-15T20:15:04Z", "last_used_from_addr": "192.0.2.255" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Create organization API key", "description": "Creates an API key for the specified organization.\nThe `key_name` is a user-specified name for the key.\nReturns an `id` and `key`; the `key` is a randomly generated, 64-bit token required to access the Neon API.\nStore the key securely \u2014 it is only returned once.\nAPI keys can also be managed in the Neon Console.\nSee [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "Organizations" ], "operationId": "createOrgApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyCreateRequest" }, "example": { "key_name": "orgkey" } } }, "required": true }, "responses": { "200": { "description": "Created an organization API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyCreateResponse" }, "example": { "id": 165434, "key": "9v1faketcjbl4sn1013keyd43n2a8qlfakeog8yvp40hx16keyjo1bpds4y2dfms3", "name": "orgkey", "created_at": "2022-11-15T20:13:35Z", "created_by": "629982cc-de05-43db-ae16-28f2399c4910" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/api_keys/{key_id}": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "delete": { "summary": "Revoke organization API key", "description": "Revokes the specified organization API key.\nAn API key that is no longer needed can be revoked.\nThis action cannot be reversed.\nAPI keys can also be managed in the Neon Console.\nSee [Manage API keys](https://neon.com/docs/manage/api-keys/).\n", "tags": [ "Organizations" ], "operationId": "revokeOrgApiKey", "parameters": [ { "name": "key_id", "in": "path", "description": "The API key ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Revoked the specified organization API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyRevokeResponse" }, "example": { "id": 165435, "name": "orgkey", "created_at": "2022-11-15T20:13:35Z", "created_by": "629982cc-de05-43db-ae16-28f2399c4910", "last_used_at": "2022-11-15T20:15:04Z", "last_used_from_addr": "192.0.2.255", "revoked": true } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/billing/spending_limit": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve organization spending limit", "description": "Returns the configured monthly spending limit for the specified organization.\n`spending_limit_cents: null` indicates that no limit is currently set.\nAvailable to organization members with read access on Launch and Scale plans only.\n", "tags": [ "Organizations" ], "x-stability-level": "beta", "operationId": "getOrganizationSpendingLimit", "responses": { "200": { "description": "The organization's current spending limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingLimitResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "put": { "summary": "Set organization spending limit", "description": "Sets the monthly spending limit for the specified organization.\nTo remove a previously configured limit, send a DELETE request to this endpoint.\nWhen a limit is configured, email notifications are sent at 80% and 100% of the limit.\nComputes are not suspended when the limit is reached.\nAvailable to organization admins on Launch and Scale plans only.\n", "tags": [ "Organizations" ], "x-stability-level": "beta", "operationId": "setOrganizationSpendingLimit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingLimitUpdateRequest" } } } }, "responses": { "200": { "description": "The updated spending limit value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingLimitResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Remove organization spending limit", "description": "Removes the configured monthly spending limit for the specified organization.\nIdempotent \u2014 removing an already-unset limit still succeeds.\nAvailable to organization admins on Launch and Scale plans only.\n", "tags": [ "Organizations" ], "x-stability-level": "beta", "operationId": "deleteOrganizationSpendingLimit", "responses": { "200": { "description": "The spending limit has been cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/members": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List organization members", "description": "Retrieves a paginated list of members for the specified organization.\n", "tags": [ "Organizations" ], "operationId": "getOrganizationMembers", "parameters": [ { "name": "sort_by", "description": "Sort the members by the specified field. Defaults to `joined_at`.", "in": "query", "schema": { "type": "string", "default": "joined_at", "enum": [ "email", "role", "joined_at" ] } }, { "$ref": "#/components/parameters/CursorParam" }, { "$ref": "#/components/parameters/SortOrderParam" }, { "name": "limit", "description": "The maximum number of members to return in the response", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Returned information about organization members", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OrganizationMembersResponse" }, { "$ref": "#/components/schemas/CursorPaginationResponse" } ] }, "example": { "members": [ { "member": { "id": "d57833f2-d308-4ede-9d2e-468d9d013d1b", "user_id": "b107d689-6dd2-4c9a-8b9e-0b25e457cf56", "org_id": "my-organization-morning-bread-81040908", "role": "admin", "joined_at": "2024-02-23T17:42:25Z" }, "user": { "email": "user1@email.com" } }, { "member": { "id": "5fee13ac-957b-40cd-8de0-4d494cc28e28", "user_id": "6df052ac-ca9a-4321-8963-b6507b2d7dee", "org_id": "my-organization-morning-bread-81040908", "role": "member", "joined_at": "2024-02-21T16:42:25Z" }, "user": { "email": "user2@email.com" } } ], "pagination": { "next": "eyJtZW1iZXJfaWQiOiI1ZmVlMTNhYy05NTdiLTQwY2QtOGRlMC00ZDQ5NGNjMjhlMjgiLCJzb3J0X2J5Ijoiam9pbmVkX2F0In0=", "sort_by": "joined_at", "sort_order": "desc" } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/members/{member_id}": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "member_id", "in": "path", "description": "The Neon organization member ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Retrieve organization member details", "description": "Retrieves information about the specified organization member.\n", "tags": [ "Organizations" ], "operationId": "getOrganizationMember", "responses": { "200": { "description": "Returned information about the organization member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" }, "example": { "id": "d57833f2-d308-4ede-9d2e-468d9d013d1b", "user_id": "b107d689-6dd2-4c9a-8b9e-0b25e457cf56", "org_id": "my-organization-morning-bread-81040908", "role": "admin", "joined_at": "2024-02-23T17:42:25Z" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update role for organization member", "description": "Updates the role of an existing member in the specified organization.\nThe requested role must be valid for the organization.\nOnly organization admins can call this endpoint.\n", "tags": [ "Organizations" ], "operationId": "updateOrganizationMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberUpdateRequest" }, "example": { "role": "member" } } } }, "responses": { "200": { "description": "The updated organization member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Remove organization member", "description": "Removes the specified member from the organization.\nOnly organization admins can perform this action.\nThe last admin in an organization cannot be removed.\n", "tags": [ "Organizations" ], "operationId": "removeOrganizationMember", "responses": { "200": { "description": "Removed organization member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/invitations": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List organization invitations", "description": "Retrieves pending and accepted invitations for the specified organization.\n", "tags": [ "Organizations" ], "operationId": "getOrganizationInvitations", "responses": { "200": { "description": "Returned information about the organization invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitationsResponse" }, "example": { "invitations": [ { "id": "db8faf32-b07f-4b0f-94c8-5c288909f5d3", "email": "invited1@email.com", "org_id": "my-organization-morning-bread-81040908", "invited_by": "some@email.com", "role": "admin", "invited_at": "2024-02-23T17:42:25Z" }, { "id": "c52f0d22-ebd9-4708-ae44-2872cae49a83", "email": "invited2@email.com", "org_id": "my-organization-morning-bread-81040908", "invited_by": "some@email.com", "role": "member", "invited_at": "2024-02-23T12:42:25Z" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Create organization invitations", "description": "Creates invitations for a specific organization.\nIf the invited user has an existing account, they automatically join as a member.\nIf they don't yet have an account, they are invited to create one, after which they become a member.\nEach invited user receives an email notification.\n", "tags": [ "Organizations" ], "operationId": "createOrganizationInvitations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitesCreateRequest" }, "example": { "invitations": [ { "email": "invited-user@email.com", "role": "member" } ] } } } }, "responses": { "200": { "description": "The created organization invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitationsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{source_org_id}/projects/transfer": { "parameters": [ { "name": "source_org_id", "in": "path", "description": "The Neon organization ID (source org, which currently owns the project)", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Transfer projects between organizations", "description": "Transfers selected projects, identified by their IDs, from your organization to another specified organization.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferProjectsToOrganizationRequest" } } } }, "tags": [ "Organizations" ], "operationId": "transferProjectsFromOrgToOrg", "responses": { "200": { "description": "Projects successfully transferred from organization to organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "406": { "description": "Transfer failed - the target organization has too many projects or its plan is incompatible with the source organization. Reduce projects or upgrade the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsUnsatisfiedResponse" } } } }, "422": { "description": "One or more of the provided project IDs have GitHub or Vercel integrations installed. Transferring integration projects is currently not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsWithIntegrationResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/vpc/vpc_endpoints": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List VPC endpoints across all regions", "description": "Retrieves the list of VPC endpoints for the specified Neon organization across all regions.\n", "tags": [ "Organizations" ], "operationId": "listOrganizationVPCEndpointsAllRegions", "responses": { "200": { "description": "The list of configured VPC endpoint IDs for the specified organization across all regions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointsWithRegionResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "region_id", "in": "path", "description": "The Neon region ID", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List VPC endpoints", "description": "Retrieves the list of VPC endpoints for the specified Neon organization.\n", "tags": [ "Organizations" ], "operationId": "listOrganizationVPCEndpoints", "responses": { "200": { "description": "The list of configured VPC endpoint IDs for the specified organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints/{vpc_endpoint_id}": { "parameters": [ { "name": "org_id", "in": "path", "description": "The Neon organization ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "region_id", "in": "path", "description": "The Neon region ID.\nAzure regions are currently not supported.\n", "required": true, "schema": { "type": "string" } }, { "name": "vpc_endpoint_id", "in": "path", "description": "The VPC endpoint ID", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Retrieve VPC endpoint details", "description": "Retrieves the current state and configuration details of a specified VPC endpoint.\n", "tags": [ "Organizations" ], "operationId": "getOrganizationVPCEndpointDetails", "responses": { "200": { "description": "Returned the current status and configuration details of the specified VPC endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointDetails" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "post": { "summary": "Assign or update VPC endpoint", "description": "Assigns a VPC endpoint to a Neon organization or updates its existing assignment.\n", "tags": [ "Organizations" ], "operationId": "assignOrganizationVPCEndpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VPCEndpointAssignment" } } }, "required": true }, "responses": { "200": { "description": "Assigned the VPC endpoint to the specified Neon organization" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete VPC endpoint", "description": "Deletes the VPC endpoint from the specified Neon organization.\nIf you delete a VPC endpoint from a Neon organization, that VPC endpoint cannot\nbe added back to the Neon organization.\n", "tags": [ "Organizations" ], "operationId": "deleteOrganizationVPCEndpoint", "responses": { "200": { "description": "Deleted the VPC endpoint from the specified Neon organization" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/regions": { "get": { "summary": "List supported regions", "description": "Lists supported Neon regions.\n\n**Note:** Not all regions are available to all organizations. Pass the `org_id`\nparameter to get an accurate list of regions available to your organization.\n", "tags": [ "Region" ], "operationId": "getActiveRegions", "parameters": [ { "name": "org_id", "description": "Organization ID. When provided, returns only regions available to this organization.\nRecommended for accurate region availability.\n", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "responses": { "200": { "description": "The list of active regions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveRegionsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/users/me": { "get": { "summary": "Retrieve current user details", "description": "Retrieves information about the currently authenticated Neon user,\nincluding account identifiers, plan details, and linked auth accounts.\n", "tags": [ "Users" ], "operationId": "getCurrentUserInfo", "responses": { "200": { "description": "Returned information about the current user\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUserInfoResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/users/me/organizations": { "get": { "summary": "List organizations for the current user", "description": "Retrieves the organizations that the currently authenticated user belongs to.\n\nWhen called with an organization- or project-scoped API key (which is not\ntied to a user), this returns the single organization that owns the key.\n", "operationId": "getCurrentUserOrganizations", "tags": [ "Users", "Organizations" ], "responses": { "200": { "description": "Returned information about the current user organizations\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/users/me/projects/transfer": { "post": { "deprecated": true, "x-sunset": "2026-07-01", "summary": "Transfer projects from personal account to organization", "description": "DEPRECATED. Personal accounts have been migrated to organizations, making this operation no longer applicable.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferProjectsToOrganizationRequest" } } } }, "tags": [ "Users" ], "operationId": "transferProjectsFromUserToOrg", "responses": { "200": { "description": "Projects successfully transferred from personal account to organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "406": { "description": "Transfer failed - the target organization has too many projects or its plan is incompatible with the source account. Reduce the number of projects or upgrade the target organization to increase its capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsUnsatisfiedResponse" } } } }, "422": { "description": "One or more of the provided project IDs have GitHub or Vercel integrations installed. Transferring integration projects is currently not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsWithIntegrationResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/auth": { "get": { "summary": "Retrieve request authentication details", "description": "Returns authentication details for the credentials used in the request,\nincluding the credential type (API key, Bearer token, or OAuth session)\nand the associated identity.\n", "tags": [ "Users" ], "operationId": "getAuthDetails", "responses": { "200": { "description": "Returned auth information about the current auth entity\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthDetailsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/snapshot": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create snapshot", "description": "Creates a snapshot from the specified branch.\nThis operation may initiate an asynchronous process.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "createSnapshot", "parameters": [ { "name": "lsn", "in": "query", "description": "The target Log Sequence Number (LSN) to take the snapshot from.\nMust fall within the restore window. Cannot be used with `timestamp`\n", "required": false, "schema": { "type": "string" } }, { "name": "timestamp", "in": "query", "description": "The target timestamp for the snapshot. Must fall within the restore window.\nUse ISO 8601 format (e.g. 2025-08-05T22:00:00Z). Cannot be used with `lsn`.\n", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "A name for the snapshot.", "required": false, "schema": { "type": "string" } }, { "name": "expires_at", "in": "query", "description": "The time at which the snapshot will be automatically deleted.\nUse ISO 8601 format (e.g. 2025-08-05T22:00:00Z).\n", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully created the snapshot", "content": { "application/json": { "schema": { "required": [ "snapshot", "operations" ], "type": "object", "properties": { "snapshot": { "$ref": "#/components/schemas/Snapshot" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/snapshots": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List project snapshots", "description": "Lists the snapshots for the specified project.\nEach snapshot represents a point-in-time backup of the project data.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "listSnapshots", "responses": { "200": { "description": "Projects snapshots", "content": { "application/json": { "schema": { "required": [ "snapshots" ], "type": "object", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } } } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/snapshots/{snapshot_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "snapshot_id", "in": "path", "description": "The snapshot ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "delete": { "summary": "Delete snapshot", "description": "Deletes the specified snapshot.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "deleteSnapshot", "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update snapshot", "description": "Updates the specified snapshot.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "updateSnapshot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotUpdateRequest" } } } }, "responses": { "200": { "description": "Successfully updated the snapshot", "content": { "application/json": { "schema": { "required": [ "snapshot" ], "type": "object", "properties": { "snapshot": { "$ref": "#/components/schemas/Snapshot" } } } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/snapshots/{snapshot_id}/restore": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "snapshot_id", "in": "path", "description": "The snapshot ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "x-stability-level": "beta", "summary": "Restore snapshot", "description": "Restores the specified snapshot to a new branch,\nand optionally finalizes the restore operation to replace the original branch.\n\n**Note**: This endpoint is currently in Beta.\n", "parameters": [ { "name": "name", "in": "query", "description": "DEPRECATED. Use the `name` field in the request body instead.\nA name for the newly restored branch. If omitted, a default name will be generated.\n", "required": false, "deprecated": true, "x-sunset": "2025-11-29", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A name for the newly restored branch.\nIf omitted, a default name will be generated.\n", "type": "string" }, "target_branch_id": { "description": "The ID of the branch to restore the snapshot into.\nIf not specified, the branch from which the snapshot was originally\ncreated (`snapshot.source_branch_id`) will be used.\n", "type": "string" }, "finalize_restore": { "description": "Set to `true` to finalize the restore operation immediately.\nThis will complete the restore and move any associated computes to the new branch,\nsimilar to the `finalizeRestoreBranch` operation.\nDefaults to `false` to allow previewing the restored snapshot data first.\n", "type": "boolean", "default": false } } } } } }, "tags": [ "Snapshot" ], "operationId": "restoreSnapshot", "responses": { "200": { "$ref": "#/components/responses/RestoredSnapshot" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/backup_schedule": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Retrieve backup schedule", "description": "Returns the backup schedule for the specified branch, including the configured snapshot frequencies.\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "getSnapshotSchedule", "responses": { "200": { "$ref": "#/components/responses/SnapshotSchedule" }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "put": { "summary": "Update backup schedule", "description": "Updates the backup schedule for the specified branch.\nThe schedule defines how often automatic snapshots are created (e.g., `hourly`, `daily`).\n\n**Note**: This endpoint is currently in Beta.\n", "tags": [ "Snapshot" ], "operationId": "setSnapshotSchedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSchedule" } } } }, "responses": { "200": { "$ref": "#/components/responses/EmptyResponse" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Create a bucket on the branch", "description": "Creates a new branchable object-storage bucket on the specified branch.\nBuckets are managed by the Neon Platform branchable-storage service.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "createProjectBranchBucket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketCreateRequest" } } } }, "responses": { "201": { "description": "Bucket created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketResponse" } } } }, "410": { "description": "The project has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "get": { "summary": "List buckets on the branch", "description": "Lists branchable object-storage buckets visible on the specified branch,\nincluding those inherited from ancestor branches.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "listProjectBranchBuckets", "responses": { "200": { "description": "The list of buckets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketsListResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "delete": { "summary": "Delete a bucket on the branch", "description": "Deletes the named bucket from the specified branch.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "deleteProjectBranchBucket", "responses": { "204": { "description": "Bucket deleted" }, "404": { "description": "Bucket not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/storage": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Get branch storage state", "description": "Returns whether branchable object-storage is usable for the specified\nbranch. A 200 response means the branch is registered in the storage\nservice and the S3 data plane will accept requests for it. A 404\nresponse includes a `reason` field indicating why storage is unavailable.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Storage" ], "x-stability-level": "beta", "operationId": "getProjectBranchStorage", "responses": { "200": { "description": "Storage is enabled for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchStorage" } } } }, "404": { "description": "Storage is not enabled for this branch, or the project/branch was not\nfound. The body is always `BranchStorageNotEnabled` \u2014 see `reason` for\nthe exact cause.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchStorageNotEnabled" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/ai_gateway": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "Get branch AI Gateway endpoint", "description": "Returns the AI Gateway endpoint host for the specified branch, used to\nrender code-snippet base URLs. A 200 response means the branch is\nregistered and this region serves the AI gateway. A 404 response\nincludes a `reason` field indicating why the gateway is unavailable.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "AI Gateway" ], "x-stability-level": "beta", "operationId": "getProjectBranchAiGateway", "responses": { "200": { "description": "AI Gateway is enabled for this branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchAiGateway" } } } }, "404": { "description": "AI Gateway is not available for this branch, or the project/branch\nwas not found. The body is always `BranchAiGatewayNotEnabled` \u2014 see\n`reason` for the exact cause.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchAiGatewayNotEnabled" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "get": { "summary": "List objects in a bucket", "description": "Lists objects visible in the named bucket on the specified branch,\nincluding those inherited from ancestor branches. Listing is served by\nthe user's session (no customer S3 credentials required).\n\nWhen `delimiter` is supplied (typically `/`), keys are collapsed into\ncommon prefixes (`folders`) so callers can render a folder-style\nbrowser; keys that do not contain the delimiter after `prefix` are\nreturned as `objects`.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "listProjectBranchBucketObjects", "parameters": [ { "name": "prefix", "in": "query", "description": "Only list objects whose key starts with this prefix.", "required": false, "schema": { "type": "string" } }, { "name": "delimiter", "in": "query", "description": "Collapse keys sharing a common prefix up to the first occurrence of\nthis delimiter (typically `/`) into the `folders` array.\n", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor returned as `next_cursor` by a previous\ncall. Resume listing after the last item of the previous page.\n", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of items (objects + folders) to return.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "responses": { "200": { "description": "The list of objects and folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketObjectsListResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "object_key", "in": "path", "description": "The object key. Keys may contain `/`; the `/` characters of nested\nkeys must be percent-encoded (`%2F`) in the path segment.\n", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "delete": { "summary": "Delete an object in a bucket", "description": "Deletes the named object from the bucket on the specified branch.\nServed by the user's session (no customer S3 credentials required).\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "deleteProjectBranchBucketObject", "responses": { "204": { "description": "Object deleted" }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/download": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "object_key", "in": "path", "description": "The object key. Keys may contain `/`; the `/` characters of nested\nkeys must be percent-encoded (`%2F`) in the path segment.\n", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "get": { "summary": "Download an object's bytes", "description": "Streams the raw bytes of the named object from the bucket on the\nspecified branch, including objects inherited from ancestor branches.\nServed by the user's session (no customer S3 credentials required).\n\nThe body is returned as `application/octet-stream` so a browser treats\nit as a download; the `Content-Length` and `ETag` response headers echo\nthe stored object metadata.\n\nBINARY-STREAM EXCEPTION TO THE BUILD-GENERATED-TYPES RULE (#7029): the\nsuccessful 200 body is the raw object stream, proxied verbatim from the\nplatform storage admin endpoint. It is modeled as an\n`application/octet-stream` binary body (not a JSON response schema) and\nis streamed without buffering the whole object in memory. Error\nresponses still use the generated `GeneralError` shape.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "getProjectBranchBucketObject", "responses": { "200": { "description": "The object's raw bytes, streamed verbatim. `Content-Length` and\n`ETag` headers are set from the stored object metadata;\n`X-Content-Type-Options` and `Content-Disposition` harden the\nbrowser against the caller-controlled bytes.\n", "headers": { "Content-Length": { "description": "The object size in bytes.", "schema": { "type": "integer", "format": "int64" } }, "ETag": { "description": "The object's entity tag (content hash).", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Always `nosniff`. Stops the browser from MIME-sniffing the\ncaller-controlled bytes into an executable type.\n", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Always `attachment`. Forces a download rather than inline\nrendering, neutralizing stored-XSS via the object body.\n", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Object not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects-by-prefix": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "delete": { "summary": "Delete every object under a key prefix (folder) in a bucket", "description": "Soft-deletes every object on the specified branch whose key starts with\n`prefix`, in a single call. Intended to back a \"delete folder\" action in\nan object browser: a `prefix` of `app/avatars/` removes every object\nbeneath that folder. Served by the user's session (no customer S3\ncredentials required).\n\n`prefix` must be non-empty, end with `/`, be at most 1024 bytes, and\ncontain no control characters - a partial-segment prefix cannot\naccidentally delete sibling keys. Returns the number of objects\nsoft-deleted (`deleted`), which may be 0 when no live object matched the\nprefix on this branch.\n\nOnly objects physically present on this branch are tombstoned; objects\ninherited from an ancestor branch via copy-on-write (not materialized on\nthis branch) are out of scope.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "deleteProjectBranchBucketObjectsByPrefix", "parameters": [ { "name": "prefix", "in": "query", "description": "The key prefix (folder) to delete. Must be non-empty and end with\n`/`. Every object on this branch whose key starts with this prefix\nis soft-deleted.\n", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "responses": { "200": { "description": "The prefix was soft-deleted. `deleted` is the number of objects\ntombstoned (may be 0 when nothing live matched on this branch).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketObjectsDeletePrefixResponse" } } } }, "404": { "description": "Bucket not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/presign": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "bucket_name", "in": "path", "description": "The bucket name", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "object_key", "in": "path", "description": "The object key. Keys may contain `/`; the `/` characters of nested\nkeys must be percent-encoded (`%2F`) in the path segment.\n", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "post": { "summary": "Presign an upload or download for an object in a bucket", "description": "Returns a presigned URL that transfers bytes directly to or from the\nobject's bucket on the specified branch, without the caller ever\nhandling S3 credentials. The `operation` field selects the direction:\n\n- `upload` returns a presigned `PUT` URL (the caller `PUT`s the file\n bytes straight to `url` with the returned `headers`). Authorized with\n project write access.\n- `download` returns a presigned `GET` URL (the caller `GET`s the\n bytes straight from `url`). Authorized with project read access.\n\nThe platform mints a short-lived credential and builds the SigV4-signed\nURL against the branch's S3 data-plane host, returning it together with\nthe HTTP method, any headers the caller must echo, and the URL's expiry.\n\nServed by the user's session (no customer S3 credentials required).\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Buckets" ], "x-stability-level": "beta", "operationId": "presignProjectBranchBucketObject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignRequest" } } } }, "responses": { "200": { "description": "A presigned URL valid until `expires_at`. The caller transfers the\nobject bytes by issuing `method url` with the returned `headers`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignResponse" } } } }, "404": { "description": "Bucket or branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/credentials": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "post": { "summary": "Issue a scoped credential on the branch", "description": "Issues a new scoped service credential anchored to the specified\nbranch. The response carries `api_token` and `s3_secret_access_key`\nexactly once \u2014 they are not stored server-side.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Credentials" ], "x-stability-level": "beta", "operationId": "createCredential", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialRequest" } } } }, "responses": { "201": { "description": "Credential issued \u2014 secrets shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "get": { "summary": "List credentials on the branch", "description": "Returns metadata for customer-issued credentials on the branch.\nSecrets are never included.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Credentials" ], "x-stability-level": "beta", "operationId": "listCredentials", "responses": { "200": { "description": "The list of credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCredentialsResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/credentials/{token_id}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "token_id", "in": "path", "description": "The opaque credential id (e.g. nak_live_<32hex>).", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Revoke a credential", "description": "Soft-deletes the credential. Idempotent.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Credentials" ], "x-stability-level": "beta", "operationId": "revokeCredential", "responses": { "204": { "description": "Credential revoked" }, "404": { "description": "Credential not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/functions": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } ], "get": { "summary": "List functions on the branch", "description": "Lists functions on the specified branch.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Functions" ], "x-stability-level": "beta", "operationId": "listProjectBranchFunctions", "parameters": [ { "$ref": "#/components/parameters/CursorParam" }, { "name": "limit", "description": "Specify a value from 1 to 1000 to limit number of functions in the response", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "The list of functions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/NeonFunctionsListResponse" }, { "$ref": "#/components/schemas/CursorPaginationResponse" } ] } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/functions/{slug}": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "slug", "in": "path", "description": "The function slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]{1,20}$" } } ], "get": { "summary": "Get function details", "description": "Returns the function identified by its slug.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Functions" ], "x-stability-level": "beta", "operationId": "getProjectBranchFunction", "responses": { "200": { "description": "The function details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonFunctionResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "patch": { "summary": "Update a function", "description": "Updates the function's mutable metadata \u2014 currently only the display\n`name`. A string sets the display name; `null` clears it, after which\nthe function's `name` falls back to its slug. Leading and trailing\nwhitespace is trimmed; a whitespace-only name is rejected. Acts only\non a function owned by the branch: a slug that is only inherited from\nan ancestor branch returns 404 \u2014 rename it on the branch that owns\nit. Like every other change on a branch, a rename is isolated per\nbranch: a branch forked before the rename keeps the name it had at\nfork time.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Functions" ], "x-stability-level": "beta", "operationId": "updateProjectBranchFunction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonFunctionUpdateRequest" } } } }, "responses": { "200": { "description": "The updated function", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonFunctionResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } }, "delete": { "summary": "Delete a function on the branch", "description": "Deletes the function identified by its slug.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Functions" ], "x-stability-level": "beta", "operationId": "deleteProjectBranchFunction", "responses": { "204": { "description": "Function deleted" }, "default": { "$ref": "#/components/responses/GeneralError" } } } }, "/projects/{project_id}/branches/{branch_id}/functions/{slug}/deployments": { "parameters": [ { "name": "project_id", "in": "path", "description": "The Neon project ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "branch_id", "in": "path", "description": "The Neon branch ID", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "slug", "in": "path", "description": "The function slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]{1,20}$" } } ], "post": { "summary": "Deploy code to a function", "description": "Creates a deployment for the function. Supply any subset of zip,\nenvironment, and runtime; omitted fields inherit the\nfunction's latest version. At least one field must be supplied. The\nfirst deployment of a function must include zip. The newest deployment\nbecomes active.\n\n**Note**: This endpoint is currently in Private Beta.\n", "tags": [ "Functions" ], "x-stability-level": "beta", "operationId": "createProjectBranchFunctionDeployment", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FunctionDeployRequest" } } } }, "responses": { "201": { "description": "The created deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonFunctionDeploymentResponse" } } } }, "default": { "$ref": "#/components/responses/GeneralError" } } } } }, "components": { "responses": { "EmptyResponse": { "description": "Empty response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "ListOperations": { "description": "Returned a list of operations\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OperationsResponse" }, { "$ref": "#/components/schemas/PaginationResponse" } ] } } } }, "CreatedProject": { "description": "Created a project.\nThe project includes a connection URI with a database, password, and role.\nAt least one non-protected role is created with a password.\nWait until the operations are finished before attempting to connect to a project database.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProjectResponse" }, { "$ref": "#/components/schemas/ConnectionURIsResponse" }, { "$ref": "#/components/schemas/RolesResponse" }, { "$ref": "#/components/schemas/DatabasesResponse" }, { "$ref": "#/components/schemas/OperationsResponse" }, { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/EndpointsResponse" } ] } } } }, "CreatedBranch": { "description": "Created a branch. An endpoint is only created if it was specified in the request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/EndpointsResponse" }, { "$ref": "#/components/schemas/OperationsResponse" }, { "$ref": "#/components/schemas/RolesResponse" }, { "$ref": "#/components/schemas/DatabasesResponse" }, { "$ref": "#/components/schemas/ConnectionURIsOptionalResponse" } ] } } } }, "RestoredSnapshot": { "description": "Branch restored from snapshot and its operations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/EndpointsOptionalResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] } } } }, "SnapshotSchedule": { "description": "Schedule of frequencies to create snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSchedule" } } } }, "GeneralError": { "description": "General Error.\n\nThe request may or may not be safe to retry, depending on the HTTP method, response status code,\nand whether a response was received.\n\n- If no response is returned from the API, a network error or timeout likely occurred.\n- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.\n\nThe following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.\nThe following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.\n\nAny request that returns a `503 Service Unavailable` response is always safe to retry.\n\nAny request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The Neon API requires an API key to authorize your requests, which you can enter below.\nRefer to our documentation to find out how to generate and use [API keys](https://neon.com/docs/manage/api-keys).\n" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "zenith" }, "TokenCookieAuth": { "type": "apiKey", "in": "cookie", "name": "keycloak_token" } }, "schemas": { "ComputeUnit": { "type": "number", "minimum": 0.25 }, "Provisioner": { "type": "string", "description": "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n* serverless-platform\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n" }, "PaginationResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "description": "Cursor based pagination is used. The user must pass the cursor as is to the backend.\nFor more information about cursor based pagination, see\nhttps://learn.microsoft.com/en-us/ef/core/querying/pagination#keyset-pagination\n", "type": "object", "required": [ "cursor" ], "properties": { "cursor": { "type": "string", "minLength": 1 } }, "example": { "cursor": "2022-12-07T00:45:05.262011Z" } }, "EmptyResponse": { "type": "object", "description": "Empty response.", "properties": {} }, "PlanDetails": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "version": { "$ref": "#/components/schemas/PlanVersion" } } }, "PlanVersion": { "type": "object", "required": [ "major", "minor" ], "properties": { "major": { "type": "integer" }, "minor": { "type": "integer" } } }, "AddProjectJWKSRequest": { "description": "Add a new JWKS to a specific endpoint of a project", "type": "object", "required": [ "jwks_url", "provider_name" ], "properties": { "jwks_url": { "description": "The URL that lists the JWKS", "type": "string" }, "provider_name": { "description": "The name of the authentication provider (e.g., Clerk, Stytch, Auth0)", "type": "string" }, "branch_id": { "description": "Branch ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "jwt_audience": { "description": "The name of the required JWT Audience to be used", "type": "string" }, "role_names": { "type": "array", "description": "DEPRECATED. This field should only be used when using Neon RLS. The roles the JWKS should be mapped to. By default, the JWKS is mapped to the `authenticator`, `authenticated` and `anonymous` roles.", "deprecated": true, "minItems": 0, "maxItems": 10, "items": { "type": "string" } }, "skip_role_creation": { "type": "boolean", "description": "DEPRECATED. This field should only be used when using Neon RLS. If true, the role creation will be skipped.", "default": false } } }, "JWKS": { "type": "object", "required": [ "id", "project_id", "jwks_url", "provider_name", "created_at", "updated_at" ], "properties": { "id": { "description": "JWKS ID", "type": "string" }, "project_id": { "description": "Project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "description": "Branch ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "jwks_url": { "description": "The URL that lists the JWKS", "type": "string" }, "provider_name": { "description": "The name of the authentication provider (e.g., Clerk, Stytch, Auth0)", "type": "string" }, "created_at": { "description": "The date and time when the JWKS was created", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date and time when the JWKS was last modified", "type": "string", "format": "date-time" }, "jwt_audience": { "description": "The name of the required JWT Audience to be used", "type": "string" }, "role_names": { "type": "array", "items": { "type": "string" } } } }, "ProjectJWKSResponse": { "description": "The list of configured JWKS definitions for a project", "type": "object", "required": [ "jwks" ], "properties": { "jwks": { "type": "array", "items": { "$ref": "#/components/schemas/JWKS" } } } }, "AdvisorCategory": { "type": "string", "description": "Category of an advisor issue", "enum": [ "SECURITY", "PERFORMANCE" ] }, "AdvisorIssue": { "type": "object", "required": [ "name", "title", "level", "facing", "categories", "description", "detail", "remediation", "metadata", "cache_key" ], "properties": { "name": { "type": "string", "description": "Unique identifier for the issue type", "example": "rls_disabled_in_public" }, "title": { "type": "string", "description": "Human-readable title", "example": "RLS Disabled in Public" }, "level": { "type": "string", "description": "Severity level of the issue", "example": "ERROR" }, "facing": { "type": "string", "description": "Whether this issue affects external API exposure or is internal only", "enum": [ "EXTERNAL", "INTERNAL" ], "example": "EXTERNAL" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/AdvisorCategory" }, "description": "Categories this issue belongs to", "example": [ "SECURITY" ] }, "description": { "type": "string", "description": "Detailed description of what this check detects" }, "detail": { "type": "string", "description": "Specific details about this instance of the issue", "example": "Table `public.users` is public, but RLS has not been enabled." }, "remediation": { "type": "string", "description": "URL to documentation on how to fix this issue", "example": "https://neon.com/docs/data-api/database-advisor" }, "metadata": { "type": "object", "description": "Additional context-specific metadata", "additionalProperties": true }, "cache_key": { "type": "string", "description": "Unique key for caching this issue result" } } }, "ApiKeyCreateRequest": { "type": "object", "required": [ "key_name" ], "properties": { "key_name": { "type": "string", "description": "A user-specified API key name. This value is required when creating an API key.", "maxLength": 64 } } }, "OrgApiKeyCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyCreateRequest" }, { "type": "object", "properties": { "project_id": { "description": "If set, the API key can access only this project", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } ] }, "ApiKeyCreateResponse": { "type": "object", "required": [ "key", "id", "name", "created_at", "created_by" ], "x-sensitive": [ "key", "name" ], "properties": { "id": { "description": "The API key ID", "type": "integer", "format": "int64" }, "key": { "description": "The generated 64-bit token required to access the Neon API", "type": "string" }, "name": { "description": "The user-specified API key name", "type": "string" }, "created_at": { "description": "A timestamp indicating when the API key was created", "type": "string", "format": "date-time" }, "created_by": { "description": "ID of the user who created this API key", "type": "string", "format": "uuid" } } }, "OrgApiKeyCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyCreateResponse" }, { "type": "object", "properties": { "project_id": { "description": "If set, the API key can access only this project", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } ] }, "ApiKeyRevokeResponse": { "type": "object", "required": [ "id", "name", "created_at", "created_by", "last_used_from_addr", "revoked" ], "properties": { "id": { "description": "The API key ID", "type": "integer", "format": "int64" }, "name": { "description": "The user-specified API key name", "type": "string" }, "created_at": { "description": "A timestamp indicating when the API key was created", "type": "string", "format": "date-time" }, "created_by": { "description": "ID of the user who created this API key", "type": "string", "format": "uuid" }, "last_used_at": { "description": "A timestamp indicating when the API was last used", "type": "string", "format": "date-time", "nullable": true }, "last_used_from_addr": { "description": "The IP address from which the API key was last used", "type": "string" }, "revoked": { "description": "A `true` or `false` value indicating whether the API key is revoked", "type": "boolean" } } }, "OrgApiKeyRevokeResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyRevokeResponse" }, { "type": "object", "properties": { "project_id": { "description": "If set, the API key can access only this project", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } ] }, "ApiKeysListResponseItem": { "type": "object", "required": [ "id", "name", "created_at", "created_by", "last_used_from_addr" ], "properties": { "id": { "description": "The API key ID", "type": "integer", "format": "int64" }, "name": { "description": "The user-specified API key name", "type": "string" }, "created_at": { "description": "A timestamp indicating when the API key was created", "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/ApiKeyCreatorData" }, "last_used_at": { "description": "A timestamp indicating when the API was last used", "type": "string", "format": "date-time", "nullable": true }, "last_used_from_addr": { "description": "The IP address from which the API key was last used", "type": "string" } } }, "OrgApiKeysListResponseItem": { "allOf": [ { "$ref": "#/components/schemas/ApiKeysListResponseItem" }, { "type": "object", "properties": { "project_id": { "description": "If set, the API key can access only this project", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } ] }, "ApiKeyCreatorData": { "description": "The user data of the user that created this API key.", "type": "object", "required": [ "id", "name", "image" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the user who created this API key" }, "name": { "type": "string", "description": "The name of the user." }, "image": { "type": "string", "description": "The URL to the user's avatar image." } } }, "Operation": { "type": "object", "required": [ "id", "project_id", "action", "status", "failures_count", "created_at", "updated_at", "total_duration_ms" ], "properties": { "id": { "description": "The operation ID", "type": "string", "format": "uuid" }, "project_id": { "description": "The Neon project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "description": "The branch ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "endpoint_id": { "description": "The endpoint ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "action": { "$ref": "#/components/schemas/OperationAction" }, "status": { "$ref": "#/components/schemas/OperationStatus" }, "error": { "description": "The error that occurred", "type": "string" }, "failures_count": { "description": "The number of times the operation failed", "type": "integer", "format": "int32" }, "retry_at": { "description": "A timestamp indicating when the operation was last retried", "type": "string", "format": "date-time" }, "created_at": { "description": "A timestamp indicating when the operation was created", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the operation status was last updated", "type": "string", "format": "date-time" }, "total_duration_ms": { "description": "The total duration of the operation in milliseconds", "type": "integer", "format": "int32" } }, "example": { "id": "d8ac46eb-a757-42b1-9907-f78322ee394e", "project_id": "spring-example-302709", "branch_id": "br-wispy-meadow-118737", "endpoint_id": "ep-silent-smoke-806639", "action": "start_compute", "status": "finished", "failures_count": 0, "created_at": "2022-11-15T20:02:00Z", "updated_at": "2022-11-15T20:02:02Z", "total_duration_ms": 200 } }, "OperationResponse": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } } }, "OperationsResponse": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } } }, "OperationAction": { "description": "The action performed by the operation", "type": "string", "enum": [ "create_compute", "create_timeline", "start_compute", "suspend_compute", "apply_config", "check_availability", "delete_timeline", "create_branch", "import_data", "tenant_ignore", "tenant_attach", "tenant_detach", "tenant_reattach", "replace_safekeeper", "disable_maintenance", "apply_storage_config", "prepare_secondary_pageserver", "switch_pageserver", "detach_parent_branch", "timeline_archive", "timeline_unarchive", "start_reserved_compute", "sync_dbs_and_roles_from_compute", "apply_schema_from_branch", "timeline_mark_invisible", "timeline_update_protected_config", "prewarm_replica", "promote_replica", "set_storage_non_dirty", "swap_binding_id", "finalize_migration", "mark_migration_prepared", "update_catalog" ] }, "OperationStatus": { "description": "The status of the operation", "type": "string", "enum": [ "scheduling", "running", "finished", "failed", "error", "cancelling", "cancelled", "skipped" ] }, "ProjectListItem": { "description": "Essential data about the project. Full data is available at the getProject endpoint.\n", "type": "object", "required": [ "active_time", "id", "platform_id", "region_id", "name", "pg_version", "proxy_host", "branch_logical_size_limit", "branch_logical_size_limit_bytes", "provisioner", "store_passwords", "cpu_used_sec", "creation_source", "created_at", "updated_at", "owner_id" ], "properties": { "id": { "description": "The project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "platform_id": { "description": "The cloud platform identifier. Currently, only AWS is supported, for which the identifier is `aws`.\n", "type": "string" }, "region_id": { "description": "The region identifier\n", "type": "string" }, "name": { "description": "The project name\n", "type": "string" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "default_endpoint_settings": { "$ref": "#/components/schemas/DefaultEndpointSettings" }, "settings": { "$ref": "#/components/schemas/ProjectSettingsData" }, "pg_version": { "$ref": "#/components/schemas/PgVersion" }, "proxy_host": { "description": "The proxy host for the project. This value combines the `region_id`, the `platform_id`, and the Neon domain (`neon.tech`).\n", "type": "string" }, "branch_logical_size_limit": { "description": "The logical size limit for a branch. The value is in MiB.\n", "type": "integer", "format": "int64" }, "branch_logical_size_limit_bytes": { "description": "The logical size limit for a branch. The value is in B.\n", "type": "integer", "format": "int64" }, "store_passwords": { "description": "Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.\n", "type": "boolean" }, "active_time": { "description": "Control plane observed endpoints of this project being active this amount of wall-clock time.\n", "type": "integer", "format": "int64", "minimum": 0 }, "cpu_used_sec": { "deprecated": true, "description": "DEPRECATED. Use data from the getProject endpoint instead.\n", "type": "integer", "format": "int64" }, "maintenance_starts_at": { "description": "A timestamp indicating when project maintenance begins. If set, the project is placed into maintenance mode at this time.\n", "type": "string", "format": "date-time" }, "creation_source": { "description": "The project creation source\n", "type": "string" }, "created_at": { "description": "A timestamp indicating when the project was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the project was last updated\n", "type": "string", "format": "date-time" }, "synthetic_storage_size": { "description": "The current space occupied by the project in storage, in bytes. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches in a project.\n", "type": "integer", "format": "int64" }, "quota_reset_at": { "deprecated": true, "description": "DEPRECATED. Use `consumption_period_end` from the getProject endpoint instead.\nA timestamp indicating when the project quota resets\n", "type": "string", "format": "date-time" }, "owner_id": { "type": "string" }, "compute_last_active_at": { "description": "The most recent time when any endpoint of this project was active.\n\nOmitted when observed no activity for endpoints of this project.\n", "type": "string", "format": "date-time" }, "org_id": { "description": "Organization id if the project belongs to an organization.\nPermissions for the project will be given to organization members as defined by the organization admins.\nThe permissions of the project do not depend on the user that created the project if a project belongs to an organization.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "org_name": { "type": "string", "description": "Organization name if the project belongs to an organization.\n" }, "history_retention_seconds": { "description": "The number of seconds to retain the shared history for all branches in this project.\n", "type": "integer", "format": "int32" }, "hipaa_enabled_at": { "description": "A timestamp indicating when HIPAA was enabled for this project", "type": "string", "format": "date-time" }, "deleted_at": { "description": "A timestamp indicating when the project was deleted", "type": "string", "format": "date-time" }, "recoverable_until": { "description": "A timestamp indicating the project will be recoverable until this date and time.", "type": "string", "format": "date-time" }, "effective_project_permission": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/ProjectPermissionLevel" } ], "nullable": true } }, "example": { "active_time": 750111, "branch_logical_size_limit": 10, "branch_logical_size_limit_bytes": 10485760, "cpu_used_sec": 523011, "id": "spring-example-302709", "owner_id": "629982cc-de05-43db-ae16-28f2399c4910", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "spring-example-302709", "provisioner": "k8s-pod", "pg_version": 15, "proxy_host": "us-east-2.aws.neon.tech", "store_passwords": true, "creation_source": "console", "created_at": "2022-12-13T01:30:55Z", "updated_at": "2022-12-13T01:30:55Z" } }, "Project": { "type": "object", "required": [ "consumption_period_end", "consumption_period_start", "active_time_seconds", "compute_time_seconds", "written_data_bytes", "data_transfer_bytes", "data_storage_bytes_hour", "id", "platform_id", "region_id", "name", "pg_version", "proxy_host", "branch_logical_size_limit", "branch_logical_size_limit_bytes", "store_passwords", "cpu_used_sec", "provisioner", "creation_source", "history_retention_seconds", "created_at", "updated_at", "owner_id" ], "properties": { "data_storage_bytes_hour": { "description": "Bytes-Hour. Project consumed that much storage hourly during the billing period. The value has some lag.\nThe value is reset at the beginning of each billing period.\n", "type": "integer", "format": "int64", "minimum": 0 }, "data_transfer_bytes": { "description": "Bytes. Egress traffic from the Neon cloud to the client for given project over the billing period.\nIncludes deleted endpoints. The value has some lag. The value is reset at the beginning of each billing period.\n", "type": "integer", "format": "int64", "minimum": 0 }, "written_data_bytes": { "description": "Bytes. Amount of WAL that travelled through storage for given project across all branches.\nThe value has some lag. The value is reset at the beginning of each billing period.\n", "type": "integer", "format": "int64", "minimum": 0 }, "compute_time_seconds": { "description": "Seconds. The number of CPU seconds used by the project's compute endpoints, including compute endpoints that have been deleted.\nThe value has some lag. The value is reset at the beginning of each billing period.\nExamples:\n1. An endpoint that uses 1 CPU for 1 second is equal to `compute_time=1`.\n2. An endpoint that uses 2 CPUs simultaneously for 1 second is equal to `compute_time=2`.\n", "type": "integer", "format": "int64", "minimum": 0 }, "active_time_seconds": { "description": "Seconds. Control plane observed endpoints of this project being active this amount of wall-clock time.\nThe value has some lag.\nThe value is reset at the beginning of each billing period.\n", "type": "integer", "format": "int64", "minimum": 0 }, "cpu_used_sec": { "description": "DEPRECATED, use compute_time instead.\n", "type": "integer", "format": "int64", "deprecated": true }, "id": { "description": "The project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "platform_id": { "description": "The cloud platform identifier. Currently, only AWS is supported, for which the identifier is `aws`.\n", "type": "string" }, "region_id": { "description": "The region identifier\n", "type": "string" }, "name": { "description": "The project name\n", "type": "string" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "default_endpoint_settings": { "$ref": "#/components/schemas/DefaultEndpointSettings" }, "settings": { "$ref": "#/components/schemas/ProjectSettingsData" }, "pg_version": { "$ref": "#/components/schemas/PgVersion" }, "proxy_host": { "description": "The proxy host for the project. This value combines the `region_id`, the `platform_id`, and the Neon domain (`neon.tech`).\n", "type": "string" }, "branch_logical_size_limit": { "description": "The logical size limit for a branch. The value is in MiB.\n", "type": "integer", "format": "int64" }, "branch_logical_size_limit_bytes": { "description": "The logical size limit for a branch. The value is in B.\n", "type": "integer", "format": "int64" }, "store_passwords": { "description": "Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.\n", "type": "boolean" }, "maintenance_starts_at": { "description": "A timestamp indicating when project maintenance begins. If set, the project is placed into maintenance mode at this time.\n", "type": "string", "format": "date-time" }, "creation_source": { "description": "The project creation source\n", "type": "string" }, "history_retention_seconds": { "description": "The number of seconds to retain the shared history for all branches in this project.\n", "type": "integer", "format": "int32" }, "created_at": { "description": "A timestamp indicating when the project was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the project was last updated\n", "type": "string", "format": "date-time" }, "synthetic_storage_size": { "description": "The current space occupied by the project in storage, in bytes. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches in a project.\n", "type": "integer", "format": "int64" }, "consumption_period_start": { "description": "A date-time indicating when Neon Cloud started measuring consumption for current consumption period.\n", "type": "string", "format": "date-time" }, "consumption_period_end": { "description": "A date-time indicating when Neon Cloud plans to stop measuring consumption for current consumption period.\n", "type": "string", "format": "date-time" }, "quota_reset_at": { "deprecated": true, "description": "DEPRECATED. Use `consumption_period_end` from the getProject endpoint instead.\nA timestamp indicating when the project quota resets.\n", "type": "string", "format": "date-time" }, "owner_id": { "type": "string" }, "owner": { "$ref": "#/components/schemas/ProjectOwnerData" }, "compute_last_active_at": { "description": "The most recent time when any endpoint of this project was active.\n\nOmitted when observed no activity for endpoints of this project.\n", "type": "string", "format": "date-time" }, "org_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "maintenance_scheduled_for": { "description": "A timestamp indicating when project update begins. If set, computes might experience a brief restart around this time.\n", "type": "string", "format": "date-time" }, "hipaa_enabled_at": { "description": "A timestamp indicating when HIPAA was enabled for this project", "type": "string", "format": "date-time" }, "effective_project_permission": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/ProjectPermissionLevel" } ], "nullable": true } }, "example": { "id": "spring-example-302709", "platform_id": "aws", "region_id": "aws-us-east-2", "name": "spring-example-302709", "provisioner": "k8s-pod", "pg_version": 15, "proxy_host": "us-east-2.aws.neon.tech", "store_passwords": true, "creation_source": "console", "history_retention_seconds": 604800, "created_at": "2022-12-13T01:30:55Z", "updated_at": "2022-12-13T01:30:55Z", "owner": { "name": "John Smith", "email": "some@email.com", "branches_limit": 10, "subscription_type": "scale" }, "org_id": "org-morning-bread-81040908", "owner_id": "629982cc-de05-43db-ae16-28f2399c4910", "data_storage_bytes_hour": 2831928, "branch_logical_size_limit": 10, "branch_logical_size_limit_bytes": 10485760, "data_transfer_bytes": 1000, "written_data_bytes": 193990002, "compute_time_seconds": 2485760, "active_time_seconds": 621440, "cpu_used_sec": 155350, "consumption_period_start": "2022-11-01T00:00:00Z", "consumption_period_end": "2022-12-01T00:00:00Z" } }, "ProjectCreateRequest": { "type": "object", "required": [ "project" ], "properties": { "project": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/ProjectSettingsData" }, "name": { "description": "The project name. If not specified, the name will be identical to the generated project ID", "type": "string", "minLength": 1, "maxLength": 256 }, "branch": { "type": "object", "properties": { "name": { "description": "The default branch name. If not specified, the default branch name, `main`, will be used.\n", "type": "string", "minLength": 1, "maxLength": 256 }, "role_name": { "description": "The role name. If not specified, the default role name, `{database_name}_owner`, will be used.\n", "type": "string" }, "database_name": { "description": "The database name. If not specified, the default database name, `neondb`, will be used.\n", "type": "string" }, "annotations": { "description": "The annotations for the branch.\n", "$ref": "#/components/schemas/AnnotationValueData" } } }, "autoscaling_limit_min_cu": { "deprecated": true, "description": "DEPRECATED, use default_endpoint_settings.autoscaling_limit_min_cu instead.\n\nThe minimum number of Compute Units. The minimum value is `0.25`.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "deprecated": true, "description": "DEPRECATED, use default_endpoint_settings.autoscaling_limit_max_cu instead.\n\nThe maximum number of Compute Units. See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "region_id": { "description": "The region identifier. Refer to our [Regions](https://neon.com/docs/introduction/regions) documentation for supported regions. Values are specified in this format: `aws-us-east-1`\n", "type": "string" }, "default_endpoint_settings": { "$ref": "#/components/schemas/DefaultEndpointSettings" }, "pg_version": { "$ref": "#/components/schemas/PgVersion" }, "store_passwords": { "description": "Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.\n", "type": "boolean" }, "history_retention_seconds": { "description": "The number of seconds to retain the shared history for all branches in this project.\nThe default is 1 day (86400 seconds).\n", "type": "integer", "format": "int32", "minimum": 0, "maximum": 2592000 }, "org_id": { "description": "Organization id in case the project created belongs to an organization.\nIf not present, project is owned by a user and not by org.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } } }, "ProjectUpdateRequest": { "type": "object", "required": [ "project" ], "properties": { "project": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/ProjectSettingsData" }, "name": { "description": "The project name", "type": "string", "minLength": 1, "maxLength": 256 }, "default_endpoint_settings": { "$ref": "#/components/schemas/DefaultEndpointSettings" }, "history_retention_seconds": { "description": "The number of seconds to retain the shared history for all branches in this project.\nThe default is 1 day (604800 seconds).\n", "type": "integer", "format": "int32", "minimum": 0, "maximum": 2592000 } } } } }, "ProjectTransferRequestResponse": { "type": "object", "required": [ "id", "project_id", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the transfer request" }, "project_id": { "description": "The ID of the project that is being transferred", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the transfer request was created" }, "expires_at": { "type": "string", "format": "date-time", "description": "The timestamp when the transfer request will expire" } } }, "AcceptProjectTransferRequestSatisfiesPlanError": { "type": "object", "required": [ "reasons" ], "properties": { "reasons": { "type": "array", "items": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "Description of why the plan is not satisfied" }, "code": { "type": "string", "description": "A short code identifying the reason" } } } } } }, "ProjectSettingsData": { "type": "object", "properties": { "quota": { "$ref": "#/components/schemas/ProjectQuota" }, "allowed_ips": { "$ref": "#/components/schemas/AllowedIps" }, "enable_logical_replication": { "description": "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n", "type": "boolean" }, "maintenance_window": { "$ref": "#/components/schemas/MaintenanceWindow" }, "block_public_connections": { "description": "When set, connections from the public internet\nare disallowed. This supersedes the AllowedIPs list.\nThis parameter is under active development and its semantics may change in the future.\n", "type": "boolean" }, "block_vpc_connections": { "description": "When set, connections using VPC endpoints are disallowed.\nThis parameter is under active development and its semantics may change in the future.\n", "type": "boolean" }, "audit_log_level": { "$ref": "#/components/schemas/ProjectAuditLogLevel" }, "hipaa": { "type": "boolean" }, "preload_libraries": { "$ref": "#/components/schemas/PreloadLibraries" } } }, "ProjectResponse": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/Project" } } }, "ProjectRecoverResponse": { "allOf": [ { "$ref": "#/components/schemas/ProjectResponse" }, { "$ref": "#/components/schemas/BranchesResponse" } ] }, "ProjectsResponse": { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectListItem" } }, "unavailable_project_ids": { "description": "A list of project IDs indicating which projects are known to exist, but whose details could not\nbe fetched within the requested (or implicit) time limit\n", "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } } } }, "ProjectPermission": { "type": "object", "required": [ "id", "granted_to_email", "granted_at" ], "x-sensitive": [ "granted_to_email" ], "properties": { "id": { "type": "string" }, "granted_to_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "granted_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" } } }, "ProjectPermissions": { "type": "object", "required": [ "project_permissions" ], "properties": { "project_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectPermission" } } } }, "GrantPermissionToProjectRequest": { "type": "object", "required": [ "email" ], "x-sensitive": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 } } }, "ProjectPermissionLevel": { "type": "string", "enum": [ "VIEWER", "EDITOR", "ADMIN" ], "description": "The caller's effective permission for a project when\nper-project permissions are enabled. `VIEWER` grants read access,\n`EDITOR` adds update access, and `ADMIN` grants full management.\nOmitted for personal projects, flag-off organizations, and non-user\nsubjects.\n" }, "ConsumptionHistoryPerProjectResponse": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerProject" } } }, "required": [ "projects" ] }, "ConsumptionHistoryPerProjectV2Response": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerProjectV2" } } }, "required": [ "projects" ] }, "ConsumptionHistoryPerProject": { "type": "object", "properties": { "project_id": { "description": "The project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerPeriod" } } }, "required": [ "project_id", "periods" ] }, "ConsumptionHistoryPerProjectV2": { "type": "object", "properties": { "project_id": { "description": "The project ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerPeriodV2" } } }, "required": [ "project_id", "periods" ] }, "ConsumptionHistoryPerBranchV2Response": { "type": "object", "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerBranchV2" } } }, "required": [ "branches" ] }, "ConsumptionHistoryPerBranchV2": { "type": "object", "properties": { "project_id": { "description": "The project that owns the branch", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "description": "The branch ID", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerPeriodV2" } } }, "required": [ "project_id", "branch_id", "periods" ] }, "ConsumptionHistoryPerPeriod": { "type": "object", "properties": { "period_id": { "description": "The ID assigned to the specified billing period.", "type": "string", "format": "uuid" }, "period_plan": { "description": "The billing plan applicable during the billing period.", "type": "string" }, "period_start": { "description": "The start date-time of the billing period.\n", "type": "string", "format": "date-time" }, "period_end": { "description": "The end date-time of the billing period, available for the past periods only.\n", "type": "string", "format": "date-time" }, "consumption": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerTimeframe" } } }, "required": [ "period_id", "period_plan", "period_start", "consumption" ], "example": { "period_id": "79ec829f-1828-4006-ac82-9f1828a0067d", "period_plan": "scale", "period_start": "2024-03-01T00:00:00Z", "consumption": [ { "timeframe_start": "2024-03-22T00:00:00Z", "timeframe_end": "2024-03-23T00:00:00Z", "active_time_seconds": 27853, "compute_time_seconds": 18346, "written_data_bytes": 1073741824, "synthetic_storage_size_bytes": 5368709120 }, { "timeframe_start": "2024-03-23T00:00:00Z", "timeframe_end": "2024-03-24T00:00:00Z", "active_time_seconds": 17498, "compute_time_seconds": 3378, "written_data_bytes": 5741824, "synthetic_storage_size_bytes": 2370912 } ] } }, "ConsumptionHistoryPerPeriodV2": { "type": "object", "properties": { "period_id": { "description": "The ID assigned to the specified billing period.", "type": "string", "format": "uuid" }, "period_plan": { "description": "The billing plan applicable during the billing period.", "type": "string" }, "period_start": { "description": "The start date-time of the billing period.\n", "type": "string", "format": "date-time" }, "period_end": { "description": "The end date-time of the billing period, available for the past periods only.\n", "type": "string", "format": "date-time" }, "consumption": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionHistoryPerTimeframeV2" } } }, "required": [ "period_id", "period_plan", "period_start", "consumption" ], "example": { "period_id": "79ec829f-1828-4006-ac82-9f1828a0067d", "period_plan": "scale", "period_start": "2024-03-01T00:00:00Z", "consumption": [ { "timeframe_start": "2024-03-22T00:00:00Z", "timeframe_end": "2024-03-23T00:00:00Z", "metrics": [ { "metric_name": "compute_unit_seconds", "value": 100 }, { "metric_name": "root_branch_bytes_month", "value": 1000000 }, { "metric_name": "child_branch_bytes_month", "value": 1000000 } ] } ] } }, "ConsumptionHistoryPerTimeframe": { "type": "object", "properties": { "timeframe_start": { "description": "The specified start date-time for the reported consumption.\n", "type": "string", "format": "date-time" }, "timeframe_end": { "description": "The specified end date-time for the reported consumption.\n", "type": "string", "format": "date-time" }, "active_time_seconds": { "description": "Seconds. The amount of time the compute endpoints have been active.\n", "type": "integer", "format": "uint64" }, "compute_time_seconds": { "description": "Seconds. The number of CPU seconds used by compute endpoints, including compute endpoints that have been deleted.\n", "type": "integer", "format": "uint64" }, "written_data_bytes": { "description": "Bytes. The amount of written data for all branches.\n", "type": "integer", "format": "uint64" }, "synthetic_storage_size_bytes": { "description": "Bytes. The space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches.\n", "type": "integer", "format": "uint64" }, "data_storage_bytes_hour": { "description": "Bytes-Hour. The amount of storage consumed hourly.\n", "type": "integer", "format": "uint64" }, "logical_size_bytes": { "description": "Bytes. The amount of logical size consumed.\n", "type": "integer", "format": "uint64" }, "logical_size_bytes_hour": { "description": "Bytes-Hour. The amount of logical size consumed hourly.\n", "type": "integer", "format": "uint64" } }, "required": [ "timeframe_start", "timeframe_end", "active_time_seconds", "compute_time_seconds", "written_data_bytes", "synthetic_storage_size_bytes" ] }, "ConsumptionHistoryPerTimeframeV2": { "type": "object", "properties": { "timeframe_start": { "description": "The specified start date-time for the reported consumption.\n", "type": "string", "format": "date-time" }, "timeframe_end": { "description": "The specified end date-time for the reported consumption.\n", "type": "string", "format": "date-time" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionMetricValue" } } } }, "ConsumptionMetricValue": { "type": "object", "properties": { "metric_name": { "type": "string" }, "value": { "type": "integer" } }, "required": [ "metric_name", "value" ] }, "ConsumptionHistoryGranularity": { "type": "string", "enum": [ "hourly", "daily", "monthly" ] }, "ConsumptionHistoryQueryMetrics": { "type": "array", "items": { "type": "string" } }, "ProjectAuditLogLevel": { "type": "string", "enum": [ "base", "extended", "full" ] }, "AvailablePreloadLibrary": { "type": "object", "required": [ "library_name", "description", "is_default", "is_experimental", "version" ], "properties": { "library_name": { "type": "string" }, "description": { "type": "string" }, "is_default": { "type": "boolean" }, "is_experimental": { "type": "boolean" }, "version": { "type": "string" } } }, "AvailablePreloadLibraries": { "type": "object", "properties": { "libraries": { "type": "array", "items": { "$ref": "#/components/schemas/AvailablePreloadLibrary" } } } }, "Branch": { "type": "object", "required": [ "id", "project_id", "name", "current_state", "state_changed_at", "creation_source", "created_at", "updated_at", "default", "protected", "cpu_used_sec", "active_time_seconds", "compute_time_seconds", "written_data_bytes", "data_transfer_bytes" ], "properties": { "id": { "description": "The branch ID. This value is generated when a branch is created. A `branch_id` value has a `br` prefix. For example: `br-small-term-683261`.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "project_id": { "description": "The ID of the project to which the branch belongs\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "parent_id": { "description": "The `branch_id` of the parent branch\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "parent_lsn": { "description": "The Log Sequence Number (LSN) on the parent branch from which this branch was created.\nWhen restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint,\nthis value isn\u2019t finalized until all operations related to the restore have completed successfully.\n", "type": "string" }, "parent_timestamp": { "description": "The point in time on the parent branch from which this branch was created.\nWhen restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint,\nthis value isn\u2019t finalized until all operations related to the restore have completed successfully.\nAfter all the operations completed, this value might stay empty.\n", "type": "string", "format": "date-time" }, "name": { "description": "The branch name\n", "type": "string" }, "current_state": { "$ref": "#/components/schemas/BranchState" }, "pending_state": { "$ref": "#/components/schemas/BranchState" }, "state_changed_at": { "description": "A UTC timestamp indicating when the `current_state` began\n", "type": "string", "format": "date-time" }, "logical_size": { "description": "The logical size of the branch, in bytes\n", "type": "integer", "format": "int64" }, "creation_source": { "description": "The branch creation source\n", "type": "string" }, "primary": { "deprecated": true, "description": "DEPRECATED. Use `default` field.\nWhether the branch is the project's primary branch\n", "type": "boolean" }, "default": { "description": "Whether the branch is the project's default branch\n", "type": "boolean" }, "protected": { "description": "Whether the branch is protected\n", "type": "boolean" }, "cpu_used_sec": { "deprecated": true, "description": "CPU seconds used by all of the branch's compute endpoints, including deleted ones.\nThis value is reset at the beginning of each billing period.\nExamples:\n1. A branch that uses 1 CPU for 1 second is equal to `cpu_used_sec=1`.\n2. A branch that uses 2 CPUs simultaneously for 1 second is equal to `cpu_used_sec=2`.\n", "type": "integer", "format": "int64" }, "compute_time_seconds": { "type": "integer", "format": "int64" }, "active_time_seconds": { "type": "integer", "format": "int64" }, "written_data_bytes": { "type": "integer", "format": "int64" }, "data_transfer_bytes": { "type": "integer", "format": "int64" }, "created_at": { "description": "A timestamp indicating when the branch was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the branch was last updated\n", "type": "string", "format": "date-time" }, "ttl_interval_seconds": { "description": "The time-to-live (TTL) duration originally configured for the branch, in seconds. This read-only value represents the interval between the time `expires_at` was set and the expiration timestamp itself. It is preserved to ensure the same TTL duration is reapplied when resetting the branch from its parent, and only updates when a new `expires_at` value is set.\n\nAccess to this feature is currently limited to participants in the Early Access Program.\n", "type": "integer", "example": 3600 }, "expires_at": { "description": "The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set by the client following the [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) format with precision up to seconds (such as 2025-06-09T18:02:16Z). Deletion is performed by a background job and may not occur exactly at the specified time.\n\nAccess to this feature is currently limited to participants in the Early Access Program.\n", "type": "string", "format": "date-time", "example": "2025-06-09T18:02:16Z" }, "last_reset_at": { "description": "A timestamp indicating when the branch was last reset\n", "type": "string", "format": "date-time" }, "created_by": { "description": "The resolved user model that contains details of the user/org/integration/api_key used for branch creation. This field is filled only in listing/get/create/get/update/delete methods, if it is empty when calling other handlers, it does not mean that it is empty in the system.\n", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the user." }, "image": { "type": "string", "description": "The URL to the user's avatar image." } } }, "init_source": { "description": "The source of initialization for the branch. Valid values are `schema-only` and `parent-data` (default).\n * `schema-only` - creates a new root branch containing only the schema. Use `parent_id` to specify the source branch. Optionally, you can provide `parent_lsn` or `parent_timestamp` to branch from a specific point in time or LSN. These fields define which branch to copy the schema from and at what point\u2014they do not establish a parent-child relationship between the `parent_id` branch and the new schema-only branch.\n * `parent-data` - creates the branch with both schema and data from the parent.\n", "type": "string" }, "restore_status": { "$ref": "#/components/schemas/BranchRestoreStatus" }, "restored_from": { "description": "ID of the snapshot that was the restore source for this branch\n", "type": "string" }, "restored_as": { "description": "ID of the target branch which was replaced when this branch was restored\n", "type": "string" }, "restricted_actions": { "description": "A list of actions that are currently restricted for this branch and the reason why.\n", "type": "array", "items": { "$ref": "#/components/schemas/BranchRestrictedAction" } }, "recovery": { "$ref": "#/components/schemas/BranchRecoveryInfo" } }, "example": { "id": "br-wispy-meadow-118737", "project_id": "spring-example-302709", "parent_id": "br-aged-salad-637688", "parent_lsn": "0/1DE2850", "name": "dev2", "protected": false, "current_state": "ready", "state_changed_at": "2022-11-30T20:09:48Z", "creation_source": "console", "created_at": "2022-11-30T19:09:48Z", "updated_at": "2022-12-01T19:53:05Z", "default": true, "init_source": "parent-data", "data_transfer_bytes": 72911987, "written_data_bytes": 542998300, "compute_time_seconds": 823880990, "active_time_seconds": 922200, "cpu_used_sec": 461100 } }, "BranchState": { "description": "The branch\u2019s state, indicating if it is initializing, ready for use, or archived.\n * 'init' - the branch is being created but is not available for querying.\n * 'resetting' - the branch is being reset to a specific point in time or LSN and is not yet available for querying.\n * 'ready' - the branch is fully operational and ready for querying. Expect normal query response times.\n * 'archived' - the branch is stored in cost-effective archival storage. Expect slow query response times.\n", "type": "string" }, "BranchRestoreStatus": { "description": "Could be `restored`, `finalized` or `detaching`.\nA `restored` branch becomes permanently `finalized` when you call `finalizeRestoreBranch`\nA `restored` or `finalized` branch may begin `detaching` as a one-time performance optimisation, after which it will continue in its original state\n", "type": "string" }, "BranchRestrictedAction": { "description": "An action that is currently restricted for the branch and the reason why.\n", "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "description": "The name of a restricted action. Possible values include `restore`, `delete-rw-endpoint`.\n", "type": "string" }, "reason": { "description": "A human-readable explanation of why the action is restricted.\n", "type": "string" } } }, "BranchRecoveryInfo": { "description": "Recovery information for a deleted branch. Only present when listing deleted branches\nwith `include_deleted=true`.\n\nThis is part of the Branch Recovery feature, which is in preview and not available to all users.\n", "type": "object", "required": [ "deleted_at", "recoverable_until", "deletion_method" ], "properties": { "deleted_at": { "description": "Timestamp when the branch was deleted\n", "type": "string", "format": "date-time" }, "recoverable_until": { "description": "Timestamp when the recovery window expires and the branch will be permanently deleted\n", "type": "string", "format": "date-time" }, "deletion_method": { "description": "How the branch was deleted: 'user' for manual deletion, 'ttl' for TTL expiration\n", "type": "string", "enum": [ "user", "ttl" ] } } }, "BranchCreateRequestEndpointOptions": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/EndpointType" }, "settings": { "$ref": "#/components/schemas/EndpointSettingsData" }, "autoscaling_limit_min_cu": { "description": "The minimum number of Compute Units. The minimum value is `0.25`.\n See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\n for more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "description": "The maximum number of Compute Units.\n See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\n for more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "suspend_timeout_seconds": { "$ref": "#/components/schemas/SuspendTimeoutSeconds" } } }, "BranchAnonymizedCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/AnnotationCreateValueRequest" }, { "type": "object", "properties": { "branch_create": { "$ref": "#/components/schemas/BranchCreateRequest" }, "masking_rules": { "type": "array", "items": { "$ref": "#/components/schemas/MaskingRule" }, "description": "List of masking rules to apply to the branch.\n" }, "start_anonymization": { "description": "If true, automatically start anonymization after the branch is created.\nDefaults to false.\n", "type": "boolean" } } } ] }, "BranchCreateRequest": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/BranchCreateRequestEndpointOptions" } }, "branch": { "type": "object", "properties": { "parent_id": { "description": "The `branch_id` of the parent branch. If omitted or empty, the branch will be created from the project's default branch.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "description": "The branch name\n", "type": "string", "minLength": 1, "maxLength": 256 }, "parent_lsn": { "description": "A Log Sequence Number (LSN) on the parent branch. The branch will be created with data from this LSN.\n", "type": "string" }, "parent_timestamp": { "description": "A timestamp identifying a point in time on the parent branch. The branch will be created with data starting from this point in time.\nThe timestamp must be provided in ISO 8601 format; for example: `2024-02-26T12:00:00Z`.\n", "type": "string", "format": "date-time" }, "protected": { "description": "Whether the branch is protected\n", "type": "boolean" }, "archived": { "description": "Whether to create the branch as archived\n", "type": "boolean" }, "init_source": { "description": "The source of initialization for the branch. Valid values are `schema-only` and `parent-data` (default).\n * `schema-only` - creates a new root branch containing only the schema. Use `parent_id` to specify the source branch. Optionally, you can provide `parent_lsn` or `parent_timestamp` to branch from a specific point in time or LSN. These fields define which branch to copy the schema from and at what point\u2014they do not establish a parent-child relationship between the `parent_id` branch and the new schema-only branch.\n * `parent-data` - creates the branch with both schema and data from the parent.\n", "type": "string" }, "expires_at": { "description": "The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set by the client following the [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) format with precision up to seconds (such as 2025-06-09T18:02:16Z). Deletion is performed by a background job and may not occur exactly at the specified time.\n\nAccess to this feature is currently limited to participants in the Early Access Program.\n", "type": "string", "format": "date-time", "example": "2025-06-09T18:02:16Z" } } } } }, "BranchUpdateRequest": { "type": "object", "required": [ "branch" ], "properties": { "branch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "protected": { "type": "boolean" }, "expires_at": { "description": "The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set by the client following the [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) format with precision up to seconds (such as 2025-06-09T18:02:16Z). Deletion is performed by a background job and may not occur exactly at the specified time. If this field is set to null, the expiration timestamp is removed.\n\nAccess to this feature is currently limited to participants in the Early Access Program.\n", "type": "string", "format": "date-time", "nullable": true, "example": "2025-06-09T18:02:16Z" } } } } }, "BranchRestoreRequest": { "type": "object", "required": [ "source_branch_id" ], "properties": { "source_branch_id": { "description": "The `branch_id` of the restore source branch.\nIf `source_timestamp` and `source_lsn` are omitted, the branch will be restored to head.\nIf `source_branch_id` is equal to the branch's id, `source_timestamp` or `source_lsn` is required.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "source_lsn": { "description": "A Log Sequence Number (LSN) on the source branch. The branch will be restored with data from this LSN.\n", "type": "string" }, "source_timestamp": { "description": "A timestamp identifying a point in time on the source branch. The branch will be restored with data starting from this point in time.\nThe timestamp must be provided in ISO 8601 format; for example: `2024-02-26T12:00:00Z`.\n", "type": "string", "format": "date-time" }, "preserve_under_name": { "description": "If not empty, the previous state of the branch will be saved to a branch with this name.\nIf the branch has children or the `source_branch_id` is equal to the branch id, this field is required. All existing child branches will be moved to the newly created branch under the name `preserve_under_name`.\n", "type": "string" } } }, "BranchResponse": { "type": "object", "required": [ "branch" ], "properties": { "branch": { "$ref": "#/components/schemas/Branch" } } }, "BranchSchemaResponse": { "type": "object", "properties": { "sql": { "type": "string" }, "json": { "$ref": "#/components/schemas/BranchSchemaJSON" } } }, "BranchSchemaCompareResponse": { "type": "object", "properties": { "diff": { "type": "string" } } }, "BranchesResponse": { "type": "object", "required": [ "branches" ], "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } } } }, "BranchesCountResponse": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int" } } }, "MaskingRule": { "type": "object", "required": [ "database_name", "schema_name", "table_name", "column_name" ], "x-sensitive": [ "database_name", "schema_name", "table_name", "column_name", "masking_function", "masking_value" ], "properties": { "database_name": { "description": "The name of the database containing the table to be masked\n", "type": "string" }, "schema_name": { "description": "The name of the schema containing the table to be masked\n", "type": "string" }, "table_name": { "description": "The name of the table containing the column to be masked\n", "type": "string" }, "column_name": { "description": "The name of the column to be masked\n", "type": "string" }, "masking_function": { "description": "The PostgreSQL Anonymizer masking function to apply.\nCan be a predefined function (e.g., 'anon.random_string(10)', 'anon.fake_email()')\nor a custom function definition (e.g., 'anon.hash(column_name)')\n", "type": "string" }, "masking_value": { "description": "A literal value to set on the column when masking.\n", "type": "string" } }, "example": { "database_name": "neondb", "schema_name": "public", "table_name": "users", "column_name": "email", "masking_function": "anon.fake_email()" } }, "MaskingRulesResponse": { "type": "object", "required": [ "masking_rules" ], "properties": { "masking_rules": { "type": "array", "items": { "$ref": "#/components/schemas/MaskingRule" }, "description": "List of masking rules for the branch\n" } } }, "MaskingRulesUpdateRequest": { "type": "object", "required": [ "masking_rules" ], "properties": { "masking_rules": { "type": "array", "items": { "$ref": "#/components/schemas/MaskingRule" }, "description": "List of masking rules to apply to the branch.\nThis will replace all existing masking rules for the branch.\n" } } }, "AnonymizedBranchStatusResponse": { "type": "object", "required": [ "project_id", "branch_id", "state", "created_at", "updated_at" ], "x-sensitive": [ "state" ], "properties": { "project_id": { "description": "The ID of the project\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "description": "The ID of the anonymized branch\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "state": { "description": "The current state of the anonymized branch. Possible values: created, initialized, initialization_error, anonymizing, anonymized, error\n", "type": "string" }, "status_message": { "description": "A descriptive message about the current status or any errors\n", "type": "string" }, "created_at": { "description": "A timestamp indicating when the anonymized branch was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the anonymized branch status was last updated\n", "type": "string", "format": "date-time" }, "failed_at": { "description": "A timestamp indicating when the anonymized branch operation failed (if applicable)\n", "type": "string", "format": "date-time" }, "last_run": { "$ref": "#/components/schemas/AnonymizationRunMetadata" } }, "example": { "branch_id": "br-aged-salad-637688", "project_id": "simple-truth-637688", "state": "anonymizing", "status_message": "Anonymizing table mydb.public.users (3/5)", "created_at": "2022-11-30T18:25:15Z", "updated_at": "2022-11-30T18:30:22Z", "last_run": { "started_at": "2022-11-30T18:25:15Z", "completed_at": "2022-11-30T18:30:22Z", "triggered_by": "df6c5f70-6cbf-4c8c-9e7a-74c3ddbd8f9f", "masked_columns": 12 } } }, "AnonymizationRunMetadata": { "type": "object", "description": "Metadata about the most recent anonymization attempt for the branch.", "properties": { "started_at": { "description": "Timestamp indicating when the latest anonymization attempt started.\n", "type": "string", "format": "date-time" }, "completed_at": { "description": "Timestamp indicating when the latest anonymization attempt completed.\nPopulated even if the attempt failed.\n", "type": "string", "format": "date-time" }, "triggered_by": { "description": "UUID of the user who triggered the latest anonymization attempt.\n", "type": "string", "format": "uuid" }, "triggered_by_username": { "description": "Username of the user who triggered the latest anonymization attempt.\n", "type": "string" }, "masked_columns": { "description": "Number of columns that had masking rules applied during the attempt.\n", "type": "integer" } } }, "ConnectionParameters": { "type": "object", "required": [ "database", "password", "role", "host", "pooler_host" ], "x-sensitive": [ "database", "host", "pooler_host", "password" ], "properties": { "database": { "description": "Database name\n", "type": "string" }, "password": { "description": "Password for the role\n", "type": "string" }, "role": { "description": "Role name\n", "type": "string" }, "host": { "description": "Hostname\n", "type": "string" }, "pooler_host": { "description": "Pooler hostname\n", "type": "string" } } }, "ConnectionDetails": { "type": "object", "required": [ "connection_uri", "connection_parameters" ], "x-sensitive": [ "connection_uri" ], "properties": { "connection_uri": { "description": "The connection URI is defined as specified here: [Connection URIs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS)\nThe connection URI can be used to connect to a Postgres database with psql or defined in a DATABASE_URL environment variable.\nWhen creating a branch from a parent with more than one role or database, the response body does not include a connection URI.\n", "type": "string" }, "connection_parameters": { "$ref": "#/components/schemas/ConnectionParameters" } } }, "ConnectionURIResponse": { "type": "object", "required": [ "uri" ], "properties": { "uri": { "description": "The connection URI.\n", "type": "string" } } }, "Endpoint": { "type": "object", "required": [ "host", "id", "project_id", "branch_id", "region_id", "autoscaling_limit_max_cu", "autoscaling_limit_min_cu", "type", "current_state", "pooler_enabled", "pooler_mode", "disabled", "passwordless_access", "creation_source", "created_at", "updated_at", "settings", "proxy_host", "suspend_timeout_seconds", "provisioner" ], "x-sensitive": [ "host" ], "properties": { "host": { "description": "The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.\n", "type": "string" }, "id": { "description": "The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "type": "string", "description": "Optional name of the compute endpoint\n" }, "project_id": { "description": "The ID of the project to which the compute endpoint belongs\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "description": "The ID of the branch that the compute endpoint is associated with\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "autoscaling_limit_min_cu": { "description": "The minimum number of Compute Units\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "description": "The maximum number of Compute Units\n", "$ref": "#/components/schemas/ComputeUnit" }, "region_id": { "type": "string", "description": "The region identifier\n" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "current_state": { "$ref": "#/components/schemas/EndpointState" }, "pending_state": { "$ref": "#/components/schemas/EndpointState" }, "settings": { "$ref": "#/components/schemas/EndpointSettingsData" }, "pooler_enabled": { "deprecated": true, "description": "DEPRECATED. Whether to enable connection pooling for the compute endpoint.\nThe recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.\nSee [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)\n", "type": "boolean" }, "pooler_mode": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.\n", "$ref": "#/components/schemas/EndpointPoolerMode" }, "disabled": { "description": "Whether to restrict connections to the compute endpoint.\nEnabling this option schedules a suspend compute operation.\nA disabled compute endpoint cannot be enabled by a connection or\nconsole action.\n", "type": "boolean" }, "passwordless_access": { "description": "Whether to permit passwordless access to the compute endpoint\n", "type": "boolean" }, "last_active": { "description": "A timestamp indicating when the compute endpoint was last active\n", "type": "string", "format": "date-time" }, "creation_source": { "description": "The compute endpoint creation source\n", "type": "string" }, "created_at": { "description": "A timestamp indicating when the compute endpoint was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the compute endpoint was last updated\n", "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "description": "A timestamp indicating when the compute endpoint was last started\n" }, "suspended_at": { "type": "string", "format": "date-time", "description": "A timestamp indicating when the compute endpoint was last suspended\n" }, "proxy_host": { "description": "DEPRECATED. Use the \"host\" property instead.\n", "type": "string" }, "suspend_timeout_seconds": { "$ref": "#/components/schemas/SuspendTimeoutSeconds" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "compute_release_version": { "description": "Attached compute's release version number.\n", "type": "string" } }, "example": { "host": "ep-silent-smoke-806639.us-east-2.aws.neon.tech", "id": "ep-silent-smoke-806639", "name": "My cool compute", "project_id": "spring-example-302709", "branch_id": "br-wispy-meadow-118737", "autoscaling_limit_min_cu": 1, "autoscaling_limit_max_cu": 1, "region_id": "aws-us-east-2", "type": "read_write", "current_state": "init", "pending_state": "active", "settings": { "pg_settings": {} }, "pooler_enabled": false, "pooler_mode": "transaction", "disabled": false, "passwordless_access": true, "creation_source": "console", "created_at": "2022-12-03T15:37:07Z", "updated_at": "2022-12-03T15:37:07Z", "proxy_host": "us-east-2.aws.neon.tech", "suspend_timeout_seconds": 0, "provisioner": "k8s-neonvm" } }, "EndpointState": { "description": "The state of the compute endpoint\n", "type": "string", "enum": [ "init", "active", "idle" ] }, "EndpointType": { "description": "The compute endpoint type. Either `read_write` or `read_only`.\n", "type": "string", "enum": [ "read_only", "read_write" ] }, "EndpointPoolerMode": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. This schema is deprecated and will be removed after 2026-06-20.\n", "type": "string", "enum": [ "transaction" ] }, "SuspendTimeoutSeconds": { "description": "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n", "type": "integer", "format": "int64", "minimum": -1, "maximum": 604800 }, "AllowedIps": { "description": "A list of IP addresses that are allowed to connect to the compute endpoint.\nIf the list is empty or not set, all IP addresses are allowed.\nIf protected_branches_only is true, the list will be applied only to protected branches.\n", "type": "object", "properties": { "ips": { "description": "A list of IP addresses that are allowed to connect to the endpoint.", "type": "array", "items": { "type": "string" } }, "protected_branches_only": { "description": "If true, the list will be applied only to protected branches.", "type": "boolean" } } }, "MaintenanceWindow": { "description": "A maintenance window is a time period during which Neon may perform maintenance on the project's infrastructure.\nDuring this time, the project's compute endpoints may be unavailable and existing connections can be\ninterrupted.\n", "type": "object", "required": [ "weekdays", "start_time", "end_time" ], "properties": { "weekdays": { "description": "A list of weekdays when the maintenance window is active.\nEncoded as ints, where 1 - Monday, and 7 - Sunday.\n", "type": "array", "items": { "type": "integer" } }, "start_time": { "description": "Start time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n", "type": "string" }, "end_time": { "description": "End time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n", "type": "string" } } }, "PreloadLibraries": { "description": "The shared libraries to preload into the project's compute instances.\n", "type": "object", "properties": { "use_defaults": { "type": "boolean" }, "enabled_libraries": { "type": "array", "items": { "type": "string" } } } }, "EndpointCreateRequest": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "object", "required": [ "branch_id", "type" ], "properties": { "branch_id": { "description": "The ID of the branch the compute endpoint will be associated with\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "region_id": { "description": "The region where the compute endpoint will be created. Only the project's `region_id` is permitted.\n", "type": "string" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "settings": { "$ref": "#/components/schemas/EndpointSettingsData" }, "autoscaling_limit_min_cu": { "description": "The minimum number of Compute Units. The minimum value is `0.25`.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "description": "The maximum number of Compute Units.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "pooler_enabled": { "deprecated": true, "description": "DEPRECATED. Whether to enable connection pooling for the compute endpoint.\nThe recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.\nSee [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)\n", "type": "boolean" }, "pooler_mode": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.\n", "$ref": "#/components/schemas/EndpointPoolerMode" }, "disabled": { "type": "boolean", "description": "Whether to restrict connections to the compute endpoint.\nEnabling this option schedules a suspend compute operation.\nA disabled compute endpoint cannot be enabled by a connection or\nconsole action. However, the compute endpoint is periodically\nenabled by check_availability operations.\n" }, "passwordless_access": { "type": "boolean", "description": "NOT YET IMPLEMENTED. Whether to permit passwordless access to the compute endpoint.\n" }, "suspend_timeout_seconds": { "$ref": "#/components/schemas/SuspendTimeoutSeconds" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optional name of the compute endpoint\n" } } } } }, "EndpointUpdateRequest": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "object", "properties": { "branch_id": { "deprecated": true, "description": "DEPRECATED: This field will be removed in a future release.\nThe destination branch ID. The destination branch must not have an existing read-write endpoint.\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "autoscaling_limit_min_cu": { "description": "The minimum number of Compute Units. The minimum value is `0.25`.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "description": "The maximum number of Compute Units.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "provisioner": { "$ref": "#/components/schemas/Provisioner" }, "settings": { "$ref": "#/components/schemas/EndpointSettingsData" }, "pooler_enabled": { "deprecated": true, "description": "DEPRECATED. Whether to enable connection pooling for the compute endpoint.\nThe recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.\nSee [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)\n", "type": "boolean" }, "pooler_mode": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.\n", "$ref": "#/components/schemas/EndpointPoolerMode" }, "disabled": { "description": "Whether to restrict connections to the compute endpoint.\nEnabling this option schedules a suspend compute operation.\nA disabled compute endpoint cannot be enabled by a connection or\nconsole action. However, the compute endpoint is periodically\nenabled by check_availability operations.\n", "type": "boolean" }, "passwordless_access": { "description": "NOT YET IMPLEMENTED. Whether to permit passwordless access to the compute endpoint.\n", "type": "boolean" }, "suspend_timeout_seconds": { "$ref": "#/components/schemas/SuspendTimeoutSeconds" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optional name of the compute endpoint\n" } } } } }, "EndpointResponse": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" } } }, "ConnectionURIsResponse": { "type": "object", "required": [ "connection_uris" ], "x-sensitive": [ "connection_uris" ], "properties": { "connection_uris": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionDetails" } } } }, "ConnectionURIsOptionalResponse": { "type": "object", "properties": { "connection_uris": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionDetails" } } } }, "VPCEndpointsResponse": { "type": "object", "required": [ "endpoints" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/VPCEndpoint" } } } }, "VPCEndpointsWithRegionResponse": { "type": "object", "required": [ "endpoints" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/VPCEndpointWithRegion" } } } }, "VPCEndpoint": { "type": "object", "required": [ "vpc_endpoint_id", "label" ], "properties": { "vpc_endpoint_id": { "description": "The VPC endpoint ID", "type": "string" }, "label": { "description": "A descriptive label for the VPC endpoint", "type": "string" } } }, "VPCEndpointWithRegion": { "allOf": [ { "$ref": "#/components/schemas/VPCEndpoint" }, { "type": "object", "required": [ "region_id" ], "properties": { "region_id": { "description": "The region where the VPC endpoint is located", "type": "string" } } } ] }, "VPCEndpointDetails": { "type": "object", "required": [ "vpc_endpoint_id", "label", "state", "num_restricted_projects", "example_restricted_projects" ], "x-sensitive": [ "state" ], "properties": { "vpc_endpoint_id": { "description": "The VPC endpoint ID", "type": "string" }, "label": { "description": "A descriptive label for the VPC endpoint", "type": "string" }, "state": { "description": "The current state of the VPC endpoint. Possible values are\n`new` (just configured, pending acceptance) or `accepted`\n(VPC connection was accepted by Neon).\n", "type": "string" }, "num_restricted_projects": { "description": "The number of projects that are restricted to use this VPC endpoint.\n", "type": "integer" }, "example_restricted_projects": { "description": "A list of example projects that are restricted to use this VPC endpoint.\nThere are at most 3 projects in the list, even if more projects are restricted.\n", "type": "array", "items": { "type": "string" } } } }, "VPCEndpointAssignment": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" } } }, "EndpointsResponse": { "type": "object", "required": [ "endpoints" ], "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "EndpointsOptionalResponse": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "Role": { "type": "object", "required": [ "branch_id", "name", "created_at", "updated_at" ], "x-sensitive": [ "password" ], "properties": { "branch_id": { "description": "The ID of the branch to which the role belongs\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "description": "The role name\n", "type": "string" }, "password": { "description": "The role password\n", "type": "string" }, "protected": { "description": "Whether or not the role is system-protected\n", "type": "boolean" }, "authentication_method": { "description": "Authentication method configured for this role. Valid options: `password`, `oauth`, `no_login`\n", "type": "string" }, "created_at": { "description": "A timestamp indicating when the role was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the role was last updated\n", "type": "string", "format": "date-time" } }, "example": { "branch_id": "br-wispy-meadow-118737", "name": "casey", "protected": false, "created_at": "2022-11-23T17:42:25Z", "updated_at": "2022-11-23T17:42:25Z" } }, "RoleCreateRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The role name. Cannot exceed 63 bytes in length.\n", "type": "string" }, "no_login": { "description": "Whether to create a role that cannot login.\n", "type": "boolean" } } } } }, "RoleResponse": { "type": "object", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/Role" } } }, "JWKSResponse": { "type": "object", "required": [ "jwks" ], "properties": { "jwks": { "$ref": "#/components/schemas/JWKS" } } }, "RolesResponse": { "type": "object", "required": [ "roles" ], "x-sensitive": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } }, "RolePasswordResponse": { "type": "object", "required": [ "password" ], "x-sensitive": [ "password" ], "properties": { "password": { "description": "The role password\n", "type": "string" } } }, "PaymentSourceBankCard": { "type": "object", "required": [ "last4" ], "properties": { "last4": { "type": "string", "description": "Last 4 digits of the card.\n" }, "brand": { "type": "string", "description": "Brand of credit card.\n", "enum": [ "amex", "diners", "discover", "jcb", "mastercard", "unionpay", "unknown", "visa" ] }, "exp_month": { "type": "integer", "format": "int64", "description": "Credit card expiration month\n" }, "exp_year": { "type": "integer", "format": "int64", "description": "Credit card expiration year\n" } } }, "PaymentSource": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of payment source. E.g. \"card\".\n" }, "card": { "$ref": "#/components/schemas/PaymentSourceBankCard" } } }, "BillingAccount": { "type": "object", "required": [ "state", "payment_source", "subscription_type", "payment_method", "quota_reset_at_last", "name", "email", "address_city", "address_country", "address_line1", "address_line2", "address_postal_code", "address_state" ], "x-sensitive": [ "name", "email", "state", "tax_id", "address_city", "address_country", "address_line1", "address_line2", "address_postal_code", "address_state" ], "properties": { "state": { "$ref": "#/components/schemas/BillingAccountState" }, "payment_source": { "$ref": "#/components/schemas/PaymentSource" }, "subscription_type": { "$ref": "#/components/schemas/BillingSubscriptionType" }, "payment_method": { "$ref": "#/components/schemas/BillingPaymentMethod" }, "quota_reset_at_last": { "description": "The last time the quota was reset. Defaults to the date-time the account is created.\n", "type": "string", "format": "date-time" }, "name": { "description": "The full name of the individual or entity that owns the billing account. This name appears on invoices.", "type": "string" }, "email": { "description": "Billing email, to receive emails related to invoices and subscriptions.\n", "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "address_city": { "description": "Billing address city.\n", "type": "string" }, "address_country": { "description": "Billing address country code defined by ISO 3166-1 alpha-2.\n", "type": "string" }, "address_country_name": { "description": "Billing address country name.\n", "type": "string" }, "address_line1": { "description": "Billing address line 1.\n", "type": "string" }, "address_line2": { "description": "Billing address line 2.\n", "type": "string" }, "address_postal_code": { "description": "Billing address postal code.\n", "type": "string" }, "address_state": { "description": "Billing address state or region.\n", "type": "string" }, "orb_portal_url": { "description": "Orb user portal url\n", "type": "string" }, "tax_id": { "description": "The tax identification number for the billing account, displayed on invoices.\n", "type": "string" }, "tax_id_type": { "description": "The type of the tax identification number based on the country.\n", "type": "string" }, "plan_details": { "$ref": "#/components/schemas/PlanDetails" }, "spending_limit_cents": { "description": "Monthly spending cap in cents for V3 paid plans. When set,\nnotifications are sent at 80% and 100% of this limit. `null`\nmeans no limit is configured.\n", "type": "integer", "format": "int64", "nullable": true } } }, "SpendingLimitUpdateRequest": { "type": "object", "required": [ "spending_limit_cents" ], "properties": { "spending_limit_cents": { "description": "Monthly spending cap in cents. Must be positive. To remove a\npreviously configured limit, send a DELETE request to the\nspending_limit endpoint \u2014 `0` and `null` are rejected here.\nThe cap is alert-only: notifications fire at 80% and 100%, but\ncomputes are not suspended. Setting a cap below the period's\nalready-accrued spend is permitted and will trigger the\nover-limit notification on the next worker run.\n", "type": "integer", "format": "int64", "minimum": 1 } } }, "SpendingLimitResponse": { "type": "object", "required": [ "spending_limit_cents" ], "properties": { "spending_limit_cents": { "description": "Monthly spending cap in cents. `null` indicates that no limit\nis currently configured.\n", "type": "integer", "format": "int64", "nullable": true } } }, "BillingAccountState": { "type": "string", "description": "State of the billing account.\n", "enum": [ "UNKNOWN", "active", "suspended", "deactivated", "deleted" ] }, "BillingSubscriptionType": { "type": "string", "description": "Type of subscription to Neon Cloud.\nNotice that for users without billing account this will be \"UNKNOWN\"\n", "enum": [ "UNKNOWN", "direct_sales", "direct_sales_v3", "aws_marketplace", "free_v2", "free_v3", "launch", "launch_v3", "scale", "scale_v3", "business", "vercel_pg_legacy" ] }, "BillingPaymentMethod": { "type": "string", "description": "Indicates whether and how an account makes payments.\n", "enum": [ "UNKNOWN", "none", "stripe", "direct_payment", "aws_mp", "azure_mp", "vercel_mp", "staff", "trial", "sponsorship", "shared_payment_token" ] }, "Database": { "type": "object", "required": [ "id", "branch_id", "name", "owner_name", "created_at", "updated_at" ], "properties": { "id": { "description": "The database ID\n", "type": "integer", "format": "int64" }, "branch_id": { "description": "The ID of the branch to which the database belongs\n", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "description": "The database name\n", "type": "string" }, "owner_name": { "description": "The name of role that owns the database\n", "type": "string" }, "created_at": { "description": "A timestamp indicating when the database was created\n", "type": "string", "format": "date-time" }, "updated_at": { "description": "A timestamp indicating when the database was last updated\n", "type": "string", "format": "date-time" } }, "example": { "id": 834686, "branch_id": "br-wispy-meadow-118737", "name": "neondb", "owner_name": "casey", "created_at": "2022-11-30T18:25:15Z", "updated_at": "2022-11-30T18:25:15Z" } }, "DatabaseCreateRequest": { "type": "object", "required": [ "database" ], "x-sensitive": [ "database" ], "properties": { "database": { "type": "object", "required": [ "name", "owner_name" ], "properties": { "name": { "description": "The name of the database\n", "type": "string" }, "owner_name": { "description": "The name of the role that owns the database\n", "type": "string" } } } } }, "DatabaseUpdateRequest": { "type": "object", "required": [ "database" ], "x-sensitive": [ "database" ], "properties": { "database": { "type": "object", "properties": { "name": { "description": "The name of the database\n", "type": "string" }, "owner_name": { "description": "The name of the role that owns the database\n", "type": "string" } } } } }, "DatabaseResponse": { "type": "object", "required": [ "database" ], "x-sensitive": [ "database" ], "properties": { "database": { "$ref": "#/components/schemas/Database" } } }, "DatabasesResponse": { "type": "object", "required": [ "databases" ], "properties": { "databases": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } } } }, "Invitation": { "type": "object", "required": [ "id", "email", "org_id", "invited_by", "invited_at", "role" ], "x-sensitive": [ "email" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "description": "Email of the invited user", "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "org_id": { "description": "Organization id as it is stored in Neon", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "invited_by": { "description": "UUID for the user_id who extended the invitation", "type": "string", "format": "uuid" }, "invited_at": { "description": "Timestamp when the invitation was created", "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/MemberRole" } } }, "MemberRole": { "description": "The role of the organization member. Some role values may not be\navailable for all organizations.\n", "type": "string", "enum": [ "admin", "member", "editor", "viewer", "collaborator" ] }, "Member": { "type": "object", "required": [ "id", "user_id", "org_id", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "role": { "$ref": "#/components/schemas/MemberRole" }, "joined_at": { "type": "string", "format": "date-time" } } }, "MemberUserInfo": { "type": "object", "required": [ "email" ], "x-sensitive": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "has_mfa": { "type": "boolean", "description": "Whether the member has MFA (TOTP) enabled" }, "deactivated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the user account was deactivated.\nAbsent for active users. When present, the UI should render a\n\"Deactivated\" badge inline next to the member.\n" } } }, "MemberWithUser": { "type": "object", "required": [ "member", "user" ], "properties": { "member": { "$ref": "#/components/schemas/Member" }, "user": { "$ref": "#/components/schemas/MemberUserInfo" } } }, "Organization": { "type": "object", "required": [ "id", "name", "handle", "plan", "created_at", "updated_at", "managed_by" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "type": "string" }, "handle": { "type": "string" }, "plan": { "type": "string" }, "created_at": { "description": "A timestamp indicting when the organization was created\n", "type": "string", "format": "date-time" }, "managed_by": { "description": "Organizations created via the Console or the API are managed by `console`.\nOrganizations created by other methods can't be deleted via the Console or the API.\n", "type": "string" }, "updated_at": { "description": "A timestamp indicating when the organization was updated\n", "type": "string", "format": "date-time" }, "allow_hipaa_projects": { "description": "If true, allow account to mark projects as HIPAA", "type": "boolean" }, "require_mfa": { "description": "If true, all members must have MFA enabled to access this organization", "type": "boolean" } } }, "OrganizationsResponse": { "type": "object", "required": [ "organizations" ], "properties": { "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } } }, "OrganizationInvitationsResponse": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } } } }, "OrganizationInviteCreateRequest": { "type": "object", "required": [ "email", "role" ], "x-sensitive": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "role": { "$ref": "#/components/schemas/MemberRole" } } }, "OrganizationInvitesCreateRequest": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInviteCreateRequest" } } } }, "OrganizationMemberUpdateRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/MemberRole" } } }, "OrganizationMembersResponse": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/MemberWithUser" } } } }, "ActiveRegionsResponse": { "type": "object", "required": [ "regions" ], "properties": { "regions": { "type": "array", "description": "The list of active regions", "items": { "$ref": "#/components/schemas/RegionResponse" } } } }, "RegionResponse": { "type": "object", "required": [ "region_id", "name", "default", "geo_lat", "geo_long" ], "properties": { "region_id": { "type": "string", "description": "The region ID as used in other API endpoints" }, "name": { "type": "string", "description": "A short description of the region." }, "default": { "type": "boolean", "description": "Whether this region is used by default in new projects." }, "geo_lat": { "type": "string", "description": "The geographical latitude (approximate) for the region. Empty if unknown." }, "geo_long": { "type": "string", "description": "The geographical longitude (approximate) for the region. Empty if unknown." } } }, "CurrentUserAuthAccount": { "type": "object", "required": [ "provider", "email", "name", "login", "image" ], "x-sensitive": [ "email", "name", "login" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "image": { "type": "string" }, "login": { "type": "string", "deprecated": true, "description": "DEPRECATED. Use `email` field.\n" }, "name": { "type": "string" }, "provider": { "$ref": "#/components/schemas/IdentityProviderId" } } }, "CurrentUserInfoResponse": { "type": "object", "required": [ "active_seconds_limit", "id", "email", "login", "name", "last_name", "image", "projects_limit", "branches_limit", "max_autoscaling_limit", "auth_accounts", "plan" ], "x-sensitive": [ "email", "name", "last_name", "login" ], "properties": { "active_seconds_limit": { "description": "Control plane observes active endpoints of a user this amount of wall-clock time.\n", "type": "integer", "format": "int64" }, "billing_account": { "$ref": "#/components/schemas/BillingAccount" }, "auth_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentUserAuthAccount" } }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "id": { "type": "string" }, "image": { "type": "string" }, "login": { "type": "string", "deprecated": true, "description": "DEPRECATED. Use `email` field.\n" }, "name": { "type": "string" }, "last_name": { "type": "string" }, "projects_limit": { "type": "integer", "format": "int64" }, "branches_limit": { "type": "integer", "format": "int64" }, "max_autoscaling_limit": { "type": "number", "format": "double", "description": "The maximum autoscaling limit in Compute Units.\nA value of 0 indicates no limit is configured.\n" }, "compute_seconds_limit": { "type": "integer", "format": "int64" }, "plan": { "type": "string" } } }, "AuthDetailsResponse": { "type": "object", "required": [ "account_id", "auth_method" ], "properties": { "account_id": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "keycloak", "session_cookie", "api_key_user", "api_key_org", "oauth" ] }, "auth_data": { "type": "string" } } }, "TransferProjectsToOrganizationRequest": { "type": "object", "required": [ "destination_org_id", "project_ids" ], "properties": { "destination_org_id": { "description": "The destination organization identifier", "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "project_ids": { "type": "array", "minItems": 1, "maxItems": 400, "items": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "description": "The list of projects ids to transfer. Maximum of 400 project ids" } } }, "IdentityProviderId": { "description": "Identity provider id from keycloak", "type": "string", "enum": [ "github", "google", "hasura", "microsoft", "microsoftv2", "vercelmp", "keycloak" ] }, "EndpointSettingsData": { "type": "object", "description": "A collection of settings for a compute endpoint", "properties": { "pg_settings": { "$ref": "#/components/schemas/PgSettingsData" }, "pgbouncer_settings": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. PgBouncer settings for the compute endpoint. This field is deprecated and will be removed after 2026-06-20.\n", "$ref": "#/components/schemas/PgbouncerSettingsData" }, "preload_libraries": { "$ref": "#/components/schemas/PreloadLibraries" } } }, "ProjectQuota": { "type": "object", "description": "Per-project consumption quotas. If a quota is exceeded, all active computes\nare automatically suspended and cannot be started via API calls or incoming connections.\n\nThe exception is `logical_size_bytes`, which is enforced per branch.\nIf a branch exceeds its `logical_size_bytes` quota, computes can still be started,\nbut write operations will fail\u2014allowing data to be deleted to free up space.\nComputes on other branches are not affected.\n\nSetting `logical_size_bytes` overrides any lower value set by the `neon.max_cluster_size` Postgres setting.\n\nQuotas are enforced using per-project consumption metrics with the same names.\nThese metrics reset at the start of each billing period. `logical_size_bytes`\nis also an exception\u2014it reflects the total data stored in a branch and does not reset.\n\nA zero or empty quota value means \u201cunlimited.\u201d\n", "properties": { "active_time_seconds": { "description": "The total amount of wall-clock time allowed to be spent by the project's compute endpoints.\n", "type": "integer", "format": "int64", "minimum": 0 }, "compute_time_seconds": { "description": "The total amount of CPU seconds allowed to be spent by the project's compute endpoints.\n", "type": "integer", "format": "int64", "minimum": 0 }, "written_data_bytes": { "description": "Total amount of data written to all of a project's branches.\n", "type": "integer", "format": "int64", "minimum": 0 }, "data_transfer_bytes": { "description": "Total amount of data transferred from all of a project's branches using the proxy.\n", "type": "integer", "format": "int64", "minimum": 0 }, "logical_size_bytes": { "description": "Limit on the logical size of every project's branch.\n\nIf a branch exceeds its `logical_size_bytes` quota, computes can still be started,\nbut write operations will fail\u2014allowing data to be deleted to free up space.\nComputes on other branches are not affected.\n\nSetting `logical_size_bytes` overrides any lower value set by the `neon.max_cluster_size` Postgres setting.\n", "type": "integer", "format": "int64", "minimum": 0 } } }, "DefaultEndpointSettings": { "type": "object", "description": "A collection of settings for a Neon endpoint", "properties": { "pg_settings": { "$ref": "#/components/schemas/PgSettingsData" }, "pgbouncer_settings": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. PgBouncer settings for the compute endpoint. This field is deprecated and will be removed after 2026-06-20.\n", "$ref": "#/components/schemas/PgbouncerSettingsData" }, "autoscaling_limit_min_cu": { "description": "The minimum number of Compute Units. The minimum value is `0.25`.\nSee [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "autoscaling_limit_max_cu": { "description": "The maximum number of Compute Units. See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration)\nfor more information.\n", "$ref": "#/components/schemas/ComputeUnit" }, "suspend_timeout_seconds": { "$ref": "#/components/schemas/SuspendTimeoutSeconds" } } }, "PgSettingsData": { "description": "A raw representation of Postgres settings", "type": "object", "additionalProperties": { "type": "string" } }, "PgbouncerSettingsData": { "deprecated": true, "x-sunset": "2026-06-20", "description": "DEPRECATED. A raw representation of PgBouncer settings. This schema is deprecated and will be removed after 2026-06-20.\n", "type": "object", "additionalProperties": { "type": "string" } }, "PgVersion": { "description": "The major Postgres version number. Generally available versions are `14`, `15`, `16`, `17`, and `18`. `19` is being rolled out and is only accepted in regions where it has been enabled; requesting it in a region where it is not yet available returns an error.", "type": "integer", "minimum": 14, "maximum": 19, "default": 17 }, "ProjectOwnerData": { "type": "object", "required": [ "email", "name", "branches_limit", "subscription_type" ], "x-sensitive": [ "email", "name" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "name": { "type": "string" }, "branches_limit": { "type": "integer" }, "subscription_type": { "$ref": "#/components/schemas/BillingSubscriptionType" } } }, "LimitsUnsatisfiedResponse": { "type": "object", "required": [ "limits" ], "properties": { "limits": { "type": "array", "items": { "type": "object", "required": [ "name", "expected", "actual" ], "properties": { "name": { "type": "string", "description": "Identifier of the unsatisfied limit. Possible values are:\n- subscription_type\n- projects_count\n- project_region\n" }, "expected": { "type": "string" }, "actual": { "type": "string" } } } } }, "example": { "limits": [ { "name": "projects_count", "actual": "2", "expected": "1" }, { "name": "subscription_type", "actual": "launch", "expected": "scale" } ] } }, "ProjectsWithIntegrationResponse": { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "type": "object", "required": [ "id", "integration" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "integration": { "type": "string" } } } } }, "example": { "projects": [ { "id": "round-frog-53611540", "integration": "github" }, { "id": "long-leaf-72329067", "integration": "vercel" } ] } }, "DataAPISettings": { "x-tags": [ "DataAPI" ], "description": "Configuration settings for the Neon Data API", "type": "object", "properties": { "db_aggregates_enabled": { "type": "boolean", "description": "Enable aggregates feature", "default": true }, "db_anon_role": { "type": "string", "description": "Database role to use for anonymous requests", "default": "anonymous" }, "db_extra_search_path": { "type": "string", "description": "Extra schemas to add to the search path" }, "db_max_rows": { "type": "integer", "description": "Maximum number of rows that can be returned in a single request" }, "db_schemas": { "type": "array", "items": { "type": "string" }, "description": "List of schemas to expose via the API. Default: [\"public\"]" }, "jwt_role_claim_key": { "type": "string", "description": "JWT claim key to use for role extraction", "default": ".role" }, "jwt_cache_max_lifetime": { "type": "integer", "description": "Maximum lifetime for JWT cache in seconds" }, "openapi_mode": { "type": "string", "description": "OpenAPI specification mode (ignore-privileges, disabled)", "default": "disabled" }, "server_cors_allowed_origins": { "type": "string", "description": "CORS allowed origins" }, "server_timing_enabled": { "type": "boolean", "description": "Enable server timing headers" } } }, "DataAPICreateRequest": { "x-tags": [ "DataAPI" ], "description": "Create Neon Data API", "type": "object", "properties": { "auth_provider": { "type": "string", "description": "The authentication provider to use for the Neon Data API", "enum": [ "neon_auth", "external" ] }, "jwks_url": { "description": "The URL that lists the JWKS", "type": "string", "format": "uri" }, "provider_name": { "description": "The name of the authentication provider (e.g., Clerk, Stytch, Auth0)", "type": "string" }, "jwt_audience": { "description": "WARNING - using this setting will only reject tokens with a\ndifferent audience claim. Tokens without audience claim will still\nbe accepted.\n", "type": "string" }, "add_default_grants": { "description": "Grant all permissions to the tables in the public schema to authenticated users", "type": "boolean", "default": false }, "skip_auth_schema": { "description": "Skip creating the auth schema and RLS functions", "type": "boolean", "default": false }, "settings": { "$ref": "#/components/schemas/DataAPISettings", "description": "Configuration settings for the Data API" } } }, "DataAPICreateResponse": { "x-tags": [ "DataAPI" ], "description": "Neon Data API created successfully", "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } }, "DataAPIReponse": { "x-tags": [ "DataAPI" ], "description": "Neon Data API response", "type": "object", "required": [ "url", "status" ], "properties": { "url": { "type": "string", "description": "The URL of the Neon Data API", "format": "uri" }, "status": { "type": "string", "description": "The status of the Neon Data API deployment" }, "settings": { "allOf": [ { "$ref": "#/components/schemas/DataAPISettings" } ], "type": "object", "nullable": true, "description": "Configuration settings for the Data API (SubZero only)" }, "available_schemas": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "List of available database schemas (SubZero only)" } } }, "DataAPIUpdateRequest": { "x-tags": [ "DataAPI" ], "description": "Update Neon Data API", "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/DataAPISettings", "description": "Configuration settings for the Data API" } } }, "NeonAuthSupportedAuthProvider": { "type": "string", "enum": [ "mock", "stack", "better_auth" ] }, "NeonAuthProviderProjectOwnedBy": { "type": "string", "enum": [ "user", "neon" ] }, "NeonAuthProviderProjectTransferStatus": { "type": "string", "enum": [ "initiated", "finished" ] }, "NeonAuthRedirectURIWhitelistDomain": { "type": "object", "required": [ "domain", "auth_provider" ], "properties": { "domain": { "type": "string" }, "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" } } }, "NeonAuthRedirectURIWhitelistResponse": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/NeonAuthRedirectURIWhitelistDomain" } } } }, "NeonAuthAddDomainToRedirectURIWhitelistRequest": { "type": "object", "required": [ "domain", "auth_provider" ], "properties": { "domain": { "type": "string", "format": "uri" }, "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" } } }, "NeonAuthDeleteDomainFromRedirectURIWhitelistRequest": { "type": "object", "required": [ "domains", "auth_provider" ], "properties": { "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/NeonAuthDeleteDomainFromRedirectURIWhitelistItem" } } } }, "NeonAuthDeleteDomainFromRedirectURIWhitelistItem": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "format": "uri" } } }, "NeonAuthCreateIntegrationRequest": { "type": "object", "required": [ "auth_provider", "project_id", "branch_id" ], "x-sensitive": [ "database_name" ], "properties": { "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "project_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "branch_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "database_name": { "type": "string" }, "role_name": { "type": "string", "deprecated": true } } }, "EnableNeonAuthIntegrationRequest": { "type": "object", "required": [ "auth_provider" ], "x-sensitive": [ "database_name" ], "properties": { "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "database_name": { "type": "string" } } }, "NeonAuthCreateIntegrationResponse": { "type": "object", "required": [ "auth_provider", "auth_provider_project_id", "pub_client_key", "secret_server_key", "jwks_url", "schema_name", "table_name" ], "x-sensitive": [ "pub_client_key", "secret_server_key" ], "properties": { "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "auth_provider_project_id": { "type": "string" }, "pub_client_key": { "type": "string" }, "secret_server_key": { "type": "string" }, "jwks_url": { "type": "string" }, "schema_name": { "type": "string" }, "table_name": { "type": "string" }, "base_url": { "type": "string" } } }, "NeonAuthCreateAuthProviderSDKKeysRequest": { "type": "object", "required": [ "project_id", "auth_provider" ], "properties": { "project_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" } } }, "NeonAuthCreateNewUserRequest": { "type": "object", "required": [ "project_id", "auth_provider", "email" ], "x-sensitive": [ "email", "name" ], "properties": { "project_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "CreateBranchNeonAuthNewUserRequest": { "type": "object", "required": [ "email" ], "x-sensitive": [ "email", "name" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "NeonAuthCreateNewUserResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "ID of newly created user", "type": "string" } } }, "UpdateNeonAuthUserRoleRequest": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "type": "array", "description": "Array of roles to assign to the user", "items": { "type": "string" }, "minItems": 1, "example": [ "admin" ] } } }, "UpdateNeonAuthUserRoleResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "ID of the updated user", "type": "string" } } }, "NeonAuthAllowLocalhostResponse": { "type": "object", "required": [ "allow_localhost" ], "properties": { "allow_localhost": { "type": "boolean", "description": "Whether to allow localhost connections" } } }, "UpdateNeonAuthAllowLocalhostRequest": { "type": "object", "required": [ "allow_localhost" ], "properties": { "allow_localhost": { "type": "boolean", "description": "Whether to allow localhost connections" } } }, "NeonAuthOrganizationConfig": { "type": "object", "required": [ "enabled", "organization_limit", "membership_limit", "creator_role", "send_invitation_email" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the organization plugin is enabled", "default": true }, "organization_limit": { "type": "integer", "format": "int32", "minimum": 1, "default": 10, "description": "Maximum number of organizations a user can create" }, "membership_limit": { "type": "integer", "format": "int32", "minimum": 1, "default": 100, "description": "Maximum number of members per organization" }, "creator_role": { "type": "string", "description": "The role assigned to the user who creates an organization", "default": "owner", "enum": [ "admin", "owner" ] }, "send_invitation_email": { "type": "boolean", "description": "Whether to send invitation emails when inviting members to an organization", "default": false } } }, "NeonAuthOrganizationConfigUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the organization plugin is enabled" }, "organization_limit": { "type": "integer", "format": "int32", "minimum": 1, "description": "Maximum number of organizations a user can create" }, "membership_limit": { "type": "integer", "format": "int32", "minimum": 1, "description": "Maximum number of members per organization" }, "creator_role": { "type": "string", "description": "The role assigned to the user who creates an organization", "enum": [ "admin", "owner" ] }, "send_invitation_email": { "type": "boolean", "description": "Whether to send invitation emails when inviting members to an organization" } } }, "NeonAuthMagicLinkConfig": { "type": "object", "required": [ "enabled", "expires_in", "disable_sign_up" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the magic link plugin is enabled", "default": false }, "expires_in": { "type": "integer", "format": "int32", "minimum": 5, "maximum": 1440, "default": 5, "description": "Time in minutes before the magic link expires" }, "disable_sign_up": { "type": "boolean", "default": false, "description": "Whether to disable sign-up via magic link" } } }, "NeonAuthMagicLinkConfigUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the magic link plugin is enabled" }, "expires_in": { "type": "integer", "format": "int32", "minimum": 5, "maximum": 1440, "description": "Time in minutes before the magic link expires" }, "disable_sign_up": { "type": "boolean", "description": "Whether to disable sign-up via magic link" } } }, "NeonAuthPhoneNumberConfig": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the phone number plugin is enabled", "default": false }, "otp_expires_in": { "type": "integer", "description": "Time in seconds before the OTP expires", "default": 300, "minimum": 60, "maximum": 600 } } }, "NeonAuthPhoneNumberConfigUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the phone number plugin is enabled" }, "otp_expires_in": { "type": "integer", "description": "Time in seconds before the OTP expires", "minimum": 60, "maximum": 600 } } }, "NeonAuthTransferAuthProviderProjectRequest": { "type": "object", "required": [ "project_id", "auth_provider" ], "properties": { "project_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" } } }, "NeonAuthTransferAuthProviderProjectResponse": { "type": "object", "required": [ "url" ], "properties": { "url": { "description": "URL for completing the process of ownership transfer", "type": "string" } } }, "ListNeonAuthIntegrationsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NeonAuthIntegration" } } } }, "ListNeonAuthOauthProvidersResponse": { "type": "object", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } } } }, "NeonAuthPluginConfigs": { "type": "object", "description": "Aggregated plugin configurations for Neon Auth", "properties": { "organization": { "$ref": "#/components/schemas/NeonAuthOrganizationConfig" }, "magic_link": { "$ref": "#/components/schemas/NeonAuthMagicLinkConfig" }, "phone_number": { "$ref": "#/components/schemas/NeonAuthPhoneNumberConfig" }, "email_provider": { "$ref": "#/components/schemas/NeonAuthEmailServerConfig" }, "email_and_password": { "$ref": "#/components/schemas/NeonAuthEmailAndPasswordConfig" }, "oauth_providers": { "type": "array", "items": { "$ref": "#/components/schemas/NeonAuthOauthProvider" } }, "allow_localhost": { "type": "boolean" } } }, "NeonAuthWebhookConfig": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "webhook_url": { "type": "string" }, "enabled_events": { "type": "array", "items": { "type": "string", "enum": [ "user.before_create", "user.created", "send.otp", "send.magic_link", "organization.invitation.created", "organization.invitation.accepted", "phone_number.verified" ] } }, "timeout_seconds": { "type": "integer", "default": 5, "minimum": 1, "maximum": 10 } } }, "NeonAuthOauthProvider": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "$ref": "#/components/schemas/NeonAuthOauthProviderId" }, "type": { "$ref": "#/components/schemas/NeonAuthOauthProviderType" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } } }, "NeonAuthOauthProviderId": { "type": "string", "enum": [ "google", "github", "microsoft", "vercel" ] }, "NeonAuthOauthProviderType": { "type": "string", "enum": [ "standard", "shared" ] }, "NeonAuthAddOAuthProviderRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/NeonAuthOauthProviderId" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "microsoft_tenant_id": { "type": "string" } } }, "NeonAuthUpdateOAuthProviderRequest": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "microsoft_tenant_id": { "type": "string" } } }, "SharedEmailServer": { "type": "object", "properties": { "sender_email": { "type": "string" }, "sender_name": { "type": "string" } } }, "StandardEmailServer": { "type": "object", "required": [ "host", "port", "username", "password", "sender_email", "sender_name" ], "x-sensitive": [ "host", "password", "username" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "password": { "type": "string" }, "sender_email": { "type": "string" }, "sender_name": { "type": "string" } } }, "NeonAuthEmailServerConfig": { "type": "object", "discriminator": { "propertyName": "type", "mapping": { "standard": "#/components/schemas/StandardEmailServer", "shared": "#/components/schemas/SharedEmailServer" } }, "oneOf": [ { "$ref": "#/components/schemas/StandardEmailServer" }, { "$ref": "#/components/schemas/SharedEmailServer" } ] }, "SendNeonAuthTestEmailRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/StandardEmailServer" }, { "type": "object", "required": [ "recipient_email" ], "properties": { "recipient_email": { "description": "The email address to send the test email to.", "type": "string", "format": "email", "minLength": 1, "maxLength": 256 } } } ] }, "SendNeonAuthTestEmailResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the test email was sent successfully." }, "error_message": { "type": "string", "description": "The error message from the email server." } } }, "NeonAuthEmailVerificationMethod": { "type": "string", "enum": [ "link", "otp" ], "description": "The email verification method to use.\n- `link`: Sends a verification link via email\n- `otp`: Sends a one-time password (OTP) via email\n" }, "NeonAuthEmailAndPasswordConfig": { "type": "object", "required": [ "enabled", "email_verification_method", "require_email_verification", "auto_sign_in_after_verification", "send_verification_email_on_sign_up", "send_verification_email_on_sign_in", "disable_sign_up" ], "properties": { "enabled": { "type": "boolean", "description": "Whether email and password authentication is enabled" }, "email_verification_method": { "$ref": "#/components/schemas/NeonAuthEmailVerificationMethod", "description": "The email verification method to use" }, "require_email_verification": { "type": "boolean", "description": "Whether email verification is required before users can sign in" }, "auto_sign_in_after_verification": { "type": "boolean", "description": "Whether users are automatically signed in after verifying their email" }, "send_verification_email_on_sign_up": { "type": "boolean", "description": "Whether to send a verification email when users sign up" }, "send_verification_email_on_sign_in": { "type": "boolean", "description": "Whether to send a verification email when users sign in" }, "disable_sign_up": { "type": "boolean", "description": "Whether to disable new user sign ups" } } }, "NeonAuthEmailAndPasswordConfigUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether email and password authentication is enabled" }, "email_verification_method": { "$ref": "#/components/schemas/NeonAuthEmailVerificationMethod", "description": "The email verification method to use" }, "require_email_verification": { "type": "boolean", "description": "Whether email verification is required before users can sign in" }, "auto_sign_in_after_verification": { "type": "boolean", "description": "Whether users are automatically signed in after verifying their email" }, "send_verification_email_on_sign_up": { "type": "boolean", "description": "Whether to send a verification email when users sign up" }, "send_verification_email_on_sign_in": { "type": "boolean", "description": "Whether to send a verification email when users sign in" }, "disable_sign_up": { "type": "boolean", "description": "Whether to disable new user sign ups" } } }, "NeonAuthIntegration": { "type": "object", "required": [ "auth_provider", "auth_provider_project_id", "branch_id", "db_name", "created_at", "owned_by", "jwks_url" ], "x-sensitive": [ "db_name" ], "properties": { "auth_provider": { "$ref": "#/components/schemas/NeonAuthSupportedAuthProvider" }, "auth_provider_project_id": { "type": "string" }, "branch_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "db_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "owned_by": { "$ref": "#/components/schemas/NeonAuthProviderProjectOwnedBy" }, "transfer_status": { "$ref": "#/components/schemas/NeonAuthProviderProjectTransferStatus" }, "jwks_url": { "type": "string" }, "base_url": { "type": "string" }, "name": { "type": "string", "description": "The application name used in auth emails and communications. Defaults to the Neon project name.", "minLength": 1, "maxLength": 256 } } }, "NeonAuthConfigUpdate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The application name used in auth emails and communications.", "minLength": 1, "maxLength": 256 } } }, "NeonAuthConfigResponse": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The application name used in auth emails and communications." } } }, "GeneralError": { "type": "object", "required": [ "message", "code" ], "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request, useful for debugging.\nYou can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.\n" }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "description": "Error message", "type": "string" } } }, "ErrorCode": { "type": "string", "default": "" }, "BranchOperations": { "allOf": [ { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "BranchRecoverResponse": { "allOf": [ { "$ref": "#/components/schemas/BranchResponse" }, { "$ref": "#/components/schemas/EndpointsOptionalResponse" } ] }, "EndpointOperations": { "allOf": [ { "$ref": "#/components/schemas/EndpointResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "DatabaseOperations": { "allOf": [ { "$ref": "#/components/schemas/DatabaseResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "RoleOperations": { "allOf": [ { "$ref": "#/components/schemas/RoleResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "JWKSCreationOperation": { "allOf": [ { "$ref": "#/components/schemas/JWKSResponse" }, { "$ref": "#/components/schemas/OperationsResponse" } ] }, "AnnotationData": { "type": "object", "x-tags": [ "Branch" ], "required": [ "object", "value" ], "properties": { "object": { "$ref": "#/components/schemas/AnnotationObjectData" }, "value": { "$ref": "#/components/schemas/AnnotationValueData" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AnnotationValueData": { "type": "object", "description": "Annotation properties.", "x-tags": [ "Branch" ], "maxProperties": 50, "additionalProperties": { "type": "string" }, "example": { "github-commit-ref": "github-branch-name" } }, "AnnotationObjectData": { "type": "object", "x-tags": [ "Branch" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "AnnotationCreateValueRequest": { "type": "object", "x-tags": [ "Branch" ], "properties": { "annotation_value": { "$ref": "#/components/schemas/AnnotationValueData" } } }, "AnnotationResponse": { "type": "object", "x-tags": [ "Branch" ], "required": [ "annotation" ], "properties": { "annotation": { "$ref": "#/components/schemas/AnnotationData" } } }, "AnnotationsMapResponse": { "type": "object", "x-tags": [ "Branch" ], "required": [ "annotations" ], "properties": { "annotations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AnnotationData" } } } }, "ApplicationType": { "type": "string", "enum": [ "vercel", "github", "datadog", "opentelemetry" ], "description": "Type of application integration" }, "ProjectsApplicationsMapResponse": { "type": "object", "x-tags": [ "Project" ], "description": "A map where key is a project ID and a value is a list of installed applications.\n", "required": [ "applications" ], "properties": { "applications": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "$ref": "#/components/schemas/ApplicationType" } } } }, "example": { "applications": { "winter-boat-259881": [ "vercel", "github", "datadog", "opentelemetry" ] } } }, "ProjectsIntegrationsMapResponse": { "type": "object", "x-tags": [ "Project" ], "description": "A map where key is a project ID and a value is a list of installed integrations.\n", "required": [ "integrations" ], "properties": { "integrations": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationType" } } } }, "example": { "integrations": { "winter-boat-259881": [ "vercel", "github", "datadog", "opentelemetry" ] } } }, "CursorPaginationResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/CursorPagination" } } }, "CursorPagination": { "type": "object", "description": "To paginate the response, issue an initial request with `limit` value. Then, add the value returned in the response `.pagination.next` attribute into the request under the `cursor` query parameter to the subsequent request to retrieve next page in pagination. The contents on cursor `next` are opaque, clients are not expected to make any assumptions on the format of the data inside the cursor.", "properties": { "next": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" } } }, "Snapshot": { "type": "object", "required": [ "id", "name", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "name": { "type": "string" }, "lsn": { "type": "string" }, "timestamp": { "type": "string" }, "source_branch_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "manual": { "type": "boolean" }, "full_size": { "description": "Full logical size of the snapshot in bytes at the time it was taken.\n\nWhen absent, the logical size has not been calculated yet and the snapshot is not being charged.\n\nWhen present, a value of 0 means the snapshot is not being charged.\n", "type": "integer", "format": "int64" }, "diff_size": { "description": "Incremental storage size in bytes since the previous scheduled snapshot, when the snapshot is billed on incremental (diff) usage.\n\nWhen absent, either the incremental size has not been calculated yet and the snapshot is not being charged, or the snapshot is charged at full logical size (in that case `full_size` is set).\n", "type": "integer", "format": "int64" } } }, "SnapshotUpdateRequest": { "type": "object", "required": [ "snapshot" ], "properties": { "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "expires_at": { "description": "The date and time when the snapshot will expire.\n\nOmit to leave the current expiration unchanged. Send `null` to\nclear the expiration so the snapshot never expires. A future\ntimestamp sets the absolute expiration.\n", "type": "string", "format": "date-time", "nullable": true, "example": "2030-06-09T18:02:16Z" } } } } }, "BackupScheduleItem": { "type": "object", "required": [ "frequency" ], "properties": { "frequency": { "type": "string", "description": "How often to take snapshots. Must be one of the following values:\n - `hourly`\n - `daily`\n - `weekly`\n - `monthly`\n - `yearly`\n" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "The hour of the day to take the snapshot (if applicable).\n" }, "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the week or month to take the snapshot (if applicable).\n" }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the year to take the snapshot (if applicable).\n" }, "retention_seconds": { "type": "integer", "minimum": 3600, "description": "How long to keep a snapshot (in seconds) before it's automatically deleted.\nIf not set, the snapshot is kept indefinitely.\n" } } }, "BackupSchedule": { "type": "object", "required": [ "schedule" ], "properties": { "schedule": { "type": "array", "items": { "$ref": "#/components/schemas/BackupScheduleItem" } } } }, "BranchSchemaJSON": { "type": "object", "required": [ "tables" ], "properties": { "tables": { "type": "array", "items": { "type": "object", "required": [ "schema", "name", "columns" ], "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "nullable": { "type": "boolean", "description": "Whether the column allows NULL values" }, "generated": { "type": "boolean", "description": "Whether the column is a generated (computed) column" } } } }, "constraints": { "type": "array", "items": { "type": "object", "required": [ "type", "columns" ], "properties": { "type": { "type": "string", "description": "Type of constraint. Possible values: `primary_key`, `unique`, `foreign_key`\n" }, "columns": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Column names participating in this constraint" }, "name": { "type": "string", "description": "Optional name of the constraint" }, "referenced_table": { "type": "object", "required": [ "schema", "table", "columns" ], "properties": { "schema": { "type": "string", "description": "Schema of the referenced table" }, "table": { "type": "string", "description": "Name of the referenced table" }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Names of the referenced columns" } }, "description": "For foreign keys - the referenced table information" } } } } } } } } }, "BucketAccessLevel": { "type": "string", "enum": [ "private", "public_read" ], "description": "Controls anonymous access to objects in the bucket.\n- `private`: all reads and writes require authenticated requests (default).\n- `public_read`: anonymous `GetObject`/`HeadObject` requests succeed; listing,\n writes, and deletes still require authenticated requests.\n" }, "Bucket": { "type": "object", "required": [ "name", "access_level", "created_at" ], "properties": { "name": { "type": "string", "description": "The bucket name (unique within a branch)." }, "access_level": { "$ref": "#/components/schemas/BucketAccessLevel" }, "created_at": { "type": "string", "format": "date-time", "description": "When the bucket was created. For a bucket inherited from an\nancestor branch this is the ancestor's creation time (the branch\nfork never re-creates the bucket).\n" } } }, "BucketCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The bucket name." }, "access_level": { "type": "string", "enum": [ "private", "public_read" ], "default": "private", "description": "Access level for the bucket. Defaults to `private`. Set to `public_read`\nto allow anonymous `GetObject`/`HeadObject` on objects in this bucket.\n" } } }, "BucketResponse": { "type": "object", "required": [ "bucket" ], "properties": { "bucket": { "$ref": "#/components/schemas/Bucket" } } }, "BucketsListResponse": { "type": "object", "required": [ "buckets" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } } } }, "BranchStorage": { "type": "object", "required": [ "enabled", "s3_endpoint", "region", "force_path_style" ], "properties": { "enabled": { "type": "boolean", "description": "Always `true` in 200 responses. Present for forward compatibility: a\nfuture version may add intermediate states; callers should treat `true`\nas \"storage is usable for this branch right now.\"\n" }, "s3_endpoint": { "type": "string", "format": "uri", "description": "The S3-compatible endpoint URL for this branch.", "example": "https://br-cool-moon-42.storage.c-2.local.neon.build" }, "region": { "type": "string", "description": "The AWS region for this branch's storage. The platform normalizes\nthe us-east-1 convention server-side: a non-empty region string is\nalways returned in 200 responses (e.g. `\"us-east-1\"` for the S3\ndefault region).\n", "example": "us-east-2" }, "force_path_style": { "type": "boolean", "description": "Whether the S3 client must use path-style addressing\n(bucket-in-path rather than virtual-hosted subdomain).\nAlways true: the wildcard TLS cert covers one level of subdomain\n(*.storage.), so the branch ID occupies that label and the\nbucket name must travel in the request path, not as a further\nsubdomain. Callers must set the S3 SDK's ForcePathStyle (or\nequivalent) to true.\n", "example": true } } }, "BranchStorageNotEnabled": { "type": "object", "required": [ "code", "message", "reason" ], "properties": { "code": { "type": "string", "example": "STORAGE_NOT_ENABLED" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "org_not_entitled", "region_unavailable", "branch_directory_missing", "branch_not_found" ], "description": "Machine-readable reason why storage is unavailable:\n- `org_not_entitled`: the org's `PlatformBranchableStorage` feature flag is off.\n- `region_unavailable`: the project's region has no storage admin service wired.\n- `branch_directory_missing`: the branch is not registered in the storage service.\n- `branch_not_found`: the project or branch does not exist, or the caller does not\n have access to it.\n" } } }, "BranchAiGateway": { "type": "object", "required": [ "enabled", "base_url" ], "properties": { "enabled": { "type": "boolean", "description": "Always `true` in 200 responses. Present for forward compatibility,\nmirroring BranchStorage.enabled.\n" }, "base_url": { "type": "string", "format": "uri", "description": "The AI-gateway endpoint root for this branch \u2014 an OpenAI-compatible\nbase URL. No dialect path is included; clients append the route\n(e.g. `/ai-gateway/openai/v1/responses`) themselves.\n", "example": "https://br-cool-moon-42-api.ai.c-2.local.neon.build" } } }, "BranchAiGatewayNotEnabled": { "type": "object", "required": [ "code", "message", "reason" ], "properties": { "code": { "type": "string", "example": "AI_GATEWAY_NOT_ENABLED" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "ai_gateway_unavailable", "branch_not_found" ], "description": "Machine-readable reason why the AI gateway is unavailable:\n- `ai_gateway_unavailable`: the project's region/cell has no AI gateway configured.\n- `branch_not_found`: the project or branch does not exist, or the caller does not\n have access to it.\n" } } }, "BucketObject": { "type": "object", "required": [ "key", "size", "last_modified", "etag" ], "properties": { "key": { "type": "string", "description": "The full object key." }, "size": { "type": "integer", "format": "int64", "description": "The object size in bytes." }, "last_modified": { "type": "string", "format": "date-time", "description": "The time the object was last modified." }, "etag": { "type": "string", "description": "The object's entity tag (content hash)." } } }, "BucketObjectsListResponse": { "type": "object", "required": [ "folders", "objects", "prefix", "is_truncated" ], "properties": { "folders": { "type": "array", "description": "Common prefixes (folder names) collapsed under the requested\n`delimiter`. Empty when no `delimiter` was supplied.\n", "items": { "type": "string" } }, "objects": { "type": "array", "description": "Objects whose keys did not collapse into a folder.", "items": { "$ref": "#/components/schemas/BucketObject" } }, "prefix": { "type": "string", "description": "The prefix that was applied to this listing (echoed back)." }, "next_cursor": { "type": "string", "description": "Pagination cursor to pass as `cursor` on the next request. Empty\nwhen the listing is not truncated.\n" }, "is_truncated": { "type": "boolean", "description": "True when more results exist beyond this page." } } }, "BucketObjectsDeletePrefixResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer", "format": "int64", "description": "The number of objects soft-deleted under the prefix. 0 when no live\nobject matched the prefix on this branch.\n" } } }, "PresignRequest": { "type": "object", "required": [ "operation" ], "description": "Options for the presigned URL. The `operation` selects upload (`PUT`)\nor download (`GET`); the remaining fields are optional.\n", "properties": { "operation": { "type": "string", "enum": [ "upload", "download" ], "description": "The transfer direction. `upload` returns a presigned `PUT` URL;\n`download` returns a presigned `GET` URL.\n" }, "content_type": { "type": "string", "description": "The `Content-Type` to bind into the signed request. Only meaningful\nfor `upload`: when set, the caller MUST send the same `Content-Type`\nheader on the `PUT`, and the value is echoed back in the response\n`headers`. Ignored for `download`.\n" }, "expires_in_seconds": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 604800, "default": 900, "description": "How long the presigned URL stays valid, in seconds. Defaults to 900\n(15 minutes); capped at 604800 (7 days).\n" } } }, "PresignResponse": { "type": "object", "required": [ "url", "method", "headers", "expires_at" ], "properties": { "url": { "type": "string", "description": "The presigned URL. Transfer the object bytes by issuing\n`method url` with the returned `headers`.\n" }, "method": { "type": "string", "description": "The HTTP method to use against `url`: `PUT` for an upload,\n`GET` for a download.\n" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers the caller MUST send verbatim on the request (e.g.\n`Content-Type` when it was signed on an upload). May be empty.\n" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the presigned URL stops being valid." } } }, "CredentialScope": { "type": "string", "description": "A single capability a credential may exercise. A credential is granted\na set of these; it may only perform actions explicitly listed in its\nscopes.\n", "enum": [ "storage:read", "storage:write", "ai_gateway:invoke", "functions:invoke" ] }, "CreateCredentialRequest": { "type": "object", "required": [ "scopes", "principal_type" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "Free-form customer label for the credential." }, "scopes": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/CredentialScope" } }, "principal_type": { "type": "string", "enum": [ "user" ], "description": "Principal type for the credential. Only `user` is customer-managed\nand accepted here. `function` and `system` credentials are\nplatform-internal (e.g. function-serve auto-mint, presign signer)\nand are never issued through the customer-facing API.\n" } } }, "CreateCredentialResponse": { "type": "object", "required": [ "token_id", "token_id_short", "api_token", "s3_secret_access_key", "scopes", "branch_id", "created_at" ], "x-sensitive": [ "api_token", "s3_secret_access_key" ], "properties": { "token_id": { "type": "string", "description": "Opaque credential id (e.g. nak_live_<32hex>)." }, "token_id_short": { "type": "string", "description": "First 12 hex chars of token_id; safe to log." }, "name": { "type": "string", "description": "Customer-supplied label, echoed back from the request. Absent when not provided." }, "api_token": { "type": "string", "description": "Bearer token; returned exactly once." }, "s3_secret_access_key": { "type": "string", "description": "nsk_live_<64 hex>; the AWS_SECRET_ACCESS_KEY, returned exactly once." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialScope" } }, "branch_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the credential expires; absent means never expires.\n" } } }, "CredentialMeta": { "type": "object", "required": [ "token_id", "token_id_short", "scopes", "principal_type", "created_at" ], "properties": { "token_id": { "type": "string", "description": "Opaque credential id (e.g. nak_live_<32hex>)." }, "token_id_short": { "type": "string" }, "name": { "type": "string", "description": "Customer-supplied label; absent when not provided at issuance." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialScope" } }, "branch_id": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "principal_type": { "type": "string" }, "function_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the credential expires; absent means never expires. The\nverifier refuses to authenticate after `expires_at <= now()`.\n" } } }, "ListCredentialsResponse": { "type": "object", "required": [ "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialMeta" } } } }, "NeonFunction": { "type": "object", "required": [ "id", "slug", "name", "invocation_url", "created_at" ], "properties": { "id": { "type": "string", "description": "Opaque, stable function identifier." }, "slug": { "type": "string", "description": "Branch-unique, lowercase DNS-label. Forms the invocation URL's host together with the branch id. Immutable." }, "name": { "type": "string", "description": "Free-form display name." }, "invocation_url": { "type": "string", "description": "URL at which the function is invoked. The host carries `-` as its first DNS label under a Neon-managed functions domain, and the URL ends with a trailing slash so paths concatenate onto it. Empty string when the function has no servable invoke host (e.g. a deployment without an invocation front-door)." }, "current_deployment": { "description": "The most recent deployment, regardless of build status. It may\nstill be building or it may have failed. Omitted until the first\ndeployment is created.\n", "allOf": [ { "$ref": "#/components/schemas/NeonFunctionDeployment" } ] }, "active_deployment": { "description": "The most recent deployment whose build completed successfully.\nThis is the deployment that serves invocations. Omitted until a\ndeployment succeeds.\n", "allOf": [ { "$ref": "#/components/schemas/NeonFunctionDeployment" } ] }, "created_at": { "type": "string" } } }, "NeonFunctionDeployment": { "type": "object", "required": [ "id", "status", "memory_mib", "runtime", "created_at" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "The deployment id, which is the platform version number (monotonic per function)." }, "status": { "type": "string", "enum": [ "pending", "building", "completed", "failed" ], "description": "Build lifecycle status of the deployment." }, "memory_mib": { "type": "integer", "format": "int32" }, "runtime": { "type": "string" }, "created_at": { "type": "string" }, "environment": { "type": "array", "items": { "type": "string" }, "description": "The NAMES of the deployment's environment variables, sorted.\nValues are encrypted at rest and are never returned \u2014 they are\nwrite-only. To change a value, deploy the variable with the new\nvalue; to remove a variable, deploy it with an empty value.\n" }, "error": { "type": "string", "description": "Human-readable reason the deployment build failed. Present only\nwhen `status` is `failed`.\n" } } }, "NeonFunctionResponse": { "type": "object", "required": [ "function" ], "properties": { "function": { "$ref": "#/components/schemas/NeonFunction" } } }, "NeonFunctionsListResponse": { "type": "object", "required": [ "functions" ], "properties": { "functions": { "type": "array", "items": { "$ref": "#/components/schemas/NeonFunction" } } } }, "NeonFunctionUpdateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "New display name for the function. `null` clears the display\nname; the function's `name` then falls back to its slug. Leading\nand trailing whitespace is trimmed; a whitespace-only name is\nrejected.\n", "type": "string", "nullable": true, "minLength": 1, "maxLength": 256 } } }, "NeonFunctionDeploymentResponse": { "type": "object", "required": [ "deployment" ], "properties": { "deployment": { "$ref": "#/components/schemas/NeonFunctionDeployment" } } }, "FunctionDeployRequest": { "type": "object", "properties": { "zip": { "type": "string", "format": "binary", "description": "Optional ZIP archive of the function source code. Omit to reuse the\nlatest version's bundle (a config-only change). Required for the\nfirst deployment of a function.\n" }, "runtime": { "type": "string", "enum": [ "nodejs24" ] }, "environment": { "type": "string", "description": "Optional JSON object (a string-to-string map) of environment\nvariables for the deployment, e.g. {\"KEY\":\"VALUE\"}. Carried as a\nJSON-encoded string because multipart form data does not support\ntyped object parts.\n\nValues are write-only: they are encrypted at rest, and responses\ncarry only the variable names (the `environment` array), never the\nvalues.\n" } } } }, "parameters": { "CursorParam": { "name": "cursor", "description": "A cursor to use in pagination. A cursor defines your place in the data list. Include `response.pagination.next` in subsequent API calls to fetch next page of the list.", "in": "query", "schema": { "type": "string" } }, "LimitParam": { "name": "limit", "description": "The maximum number of records to be returned in the response", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "SortOrderParam": { "name": "sort_order", "description": "Defines the sorting order of entities.", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "TimeoutParam": { "name": "timeout", "in": "query", "description": "Specify an explicit timeout in milliseconds to limit response delay.\nAfter timing out, the incomplete list of project data fetched so far will be returned.\nProjects still being fetched when the timeout occurred are listed in the \"unavailable\" attribute of the response.\nIf not specified, an implicit implementation defined timeout is chosen with the same behaviour as above\n", "schema": { "type": "integer", "minimum": 100, "maximum": 30000 } } } } }