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 def...

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 login credentials. To use a specific key, pass --api-key or set NEON_API_KEY. The key's permissions determine what the request can do.

Usage

Bash

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
`--describe`	Print path, query, and body fields from the OpenAPI spec without calling the API. Body names are dotted for -F.	boolean	`false`	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 and --describe).	boolean	`false`	No

Examples

GET request

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

Bash

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:

Bash

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):

Bash

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"
  }
}

Bash

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

List endpoints

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

Bash

neon api --list

YAML output

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

Bash

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