Neon CLI command: api

The api command sends an authenticated request to any Neon API route and prints the response. Pass an API path as the first argument. The method defaults to GET, or POST when you supply a body.

By default the request uses your neon auth credentials. To use a specific key, pass --api-key or set NEON_API_KEY. The key's permissions determine what the request can do.

note

api is a raw passthrough: it does not read your context file or auto-fill parameters. Pass what each route needs explicitly. For example, neon api /projects returns ERROR: org_id is required unless you add -Q org_id=<org_id> or authenticate with an organization API key. Get your organization ID from neon orgs list.

Usage

neon api <path> [options]

Options

Option	Description	Type	Default	Required
`--data`, `-d`	Raw request body: a JSON string, @file, or - for stdin. Overrides --field.	string	—	No
`--field`, `-F`	Body field key=value (repeatable). Dot-notation nests objects (e.g. -F branch.name=dev); values are typed (numbers, booleans, null, JSON).	array	—	No
`--header`, `-H`	Extra request header key:value (repeatable).	array	—	No
`--include`, `-i`	Print the response status and headers before the body.	boolean	`false`	No
`--list`	List available API endpoints from the OpenAPI spec.	boolean	`false`	No
`--method`, `-X`	HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to GET, or POST when a body is provided.	string	—	No
`--query`, `-Q`	Query parameter key=value (repeatable).	array	—	No
`--raw-field`, `-f`	Body field key=value with the value kept as a raw string.	array	—	No
`--refresh`	Refresh the cached OpenAPI spec (used with --list).	boolean	`false`	No

Examples

GET request

Pass required parameters with --query (-Q); add --include (-i) to print the status and headers before the body:

neon api /projects -Q org_id=org-cool-darkness-12345678 -i

The response is the route's raw JSON. For the fields each route returns, see the Neon API Reference.

Request body

Set body fields with --field (-F) as key=value. Values are typed automatically (numbers, booleans, null, and JSON), and dot-notation nests objects. A body switches the default method to POST:

neon api /projects/{project_id}/branches -F branch.name=dev

This sends { "branch": { "name": "dev" } }. Use --raw-field (-f) to keep a value as a literal string. For a full JSON body, use --data (-d) with a string, @file, or - (stdin).

Create a project

POST /projects takes a project object. To create it under an organization, set project.org_id in the body (unlike GET /projects, which takes org_id as a query parameter):

neon api /projects -X POST -F project.name=my-project -F project.org_id=org-cool-darkness-12345678

For a larger body, put the JSON in a file and pass it with -d @<file>:

project.json

{
  "project": {
    "name": "my-project",
    "org_id": "org-cool-darkness-12345678"
  }
}

neon api /projects -X POST -d @project.json

List endpoints

--list prints every route from the Neon OpenAPI spec; --refresh refetches the cached spec:

neon api --list

YAML output

Responses print as JSON. Use the global --output yaml (-o yaml) for YAML:

neon api /projects -Q org_id=org-cool-darkness-12345678 -o yaml