# Neon CLI command: api

The `api` command sends an authenticated request to any [Neon API](/guides/ai-agents-on-neon-reference-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`](/guides/apis-sdks-cli-login) credentials. To use a specific key, pass `--api-key` or set `NEON_API_KEY`. The [key's permissions](/guides/manage-operate-manage-api-keys#types-of-api-keys) determine what the request can do.

:::callout{intent="note"}
`api` is a raw passthrough: it does not read your [context file](/guides/apis-sdks-cli-link) 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`](/guides/apis-sdks-cli-orgs).
:::

## 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](/guides/ai-agents-on-neon-reference-api).

### 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>`:

```json title="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
```

## Related pages

- [Neon CLI command: orgs](./apis-sdks-cli-orgs.md)
- [Neon CLI command: ip-allow](./apis-sdks-cli-ip-allow.md)
- [Neon CLI command: vpc](./apis-sdks-cli-vpc.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.