# api Command - Nitro

> Manage Nitro APIs from the CLI with the `nitro api` commands: create service, gateway, or collection APIs in a workspace, list them, and inspect details.

Canonical source: https://chillicream.com/docs/nitro/cli/api

The `nitro api` commands manage APIs in a workspace.

Each API has a kind that determines how it behaves: `service` for a single GraphQL service, `gateway` for a federated gateway, or `collection` for grouping related APIs together.

All `api` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](https://chillicream.com/docs/nitro/cli/global-options)).

## `nitro api create`

Create a new API in a workspace. The path must start with `/` and uniquely identifies the API within its workspace.

```
nitro api create \
  --name "<name>" \
  --path "<path>"
```

### Options

| Option                         | Env                  | Description                                                                                     |
| ------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------- |
| \--name <name>                 | NITRO\_API\_NAME     | The name of the API. Required.                                                                  |
| \--path <path>                 | NITRO\_API\_PATH     | The path to the API. Must start with /. Required.                                               |
| \--workspace-id <workspace-id> | NITRO\_WORKSPACE\_ID | ID of the workspace to create the API in. Falls back to the workspace from the current session. |
| \--kind <kind>                 | NITRO\_API\_KIND     | The kind of the API. One of collection, gateway, service.                                       |

### Examples

Create an API in the workspace from the current session:

```
nitro api create --name "<name>" --path "/products"
```

Create an API in an explicit workspace:

```
nitro api create \
  --name "<name>" \
  --path "/products" \
  --workspace-id "<workspace-id>"
```

Create a gateway API:

```
nitro api create \
  --name "<name>" \
  --path "/products/catalog" \
  --kind gateway
```

## `nitro api list`

List all APIs in a workspace. Results are paginated, use the returned cursor to fetch the next page.

```
nitro api list
```

### Options

| Option                         | Env                  | Description                                                                |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------- |
| \--workspace-id <workspace-id> | NITRO\_WORKSPACE\_ID | ID of the workspace. Falls back to the workspace from the current session. |
| \--cursor <cursor>             | NITRO\_CURSOR        | Pagination cursor to resume from. Useful for non-interactive paging.       |

## `nitro api show`

Show the details of a single API by its ID.

```
nitro api show "<api-id>"
```

### Arguments

| Argument | Description                      |
| -------- | -------------------------------- |
| <id>     | ID of the API to show. Required. |

## `nitro api set-settings`

Update the schema registry settings of an API. These settings control how breaking and dangerous schema changes are evaluated when publishing new schema versions.

```
nitro api set-settings "<api-id>" \
  --treat-dangerous-as-breaking \
  --allow-breaking-schema-changes
```

### Arguments

| Argument | Description                        |
| -------- | ---------------------------------- |
| <id>     | ID of the API to update. Required. |

### Options

| Option                           | Env                                     | Description                                                                                             |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| \--treat-dangerous-as-breaking   | NITRO\_TREAT\_DANGEROUS\_AS\_BREAKING   | Treat dangerous schema changes as breaking. Required when running non-interactively.                    |
| \--allow-breaking-schema-changes | NITRO\_ALLOW\_BREAKING\_SCHEMA\_CHANGES | Allow breaking schema changes when no published client breaks. Required when running non-interactively. |

When run interactively, the CLI prompts for any setting you omit.

### Examples

Treat dangerous changes as breaking and reject any breaking change:

```
nitro api set-settings "<api-id>" \
  --treat-dangerous-as-breaking true \
  --allow-breaking-schema-changes false
```

Allow breaking changes when no client is affected:

```
nitro api set-settings "<api-id>" \
  --treat-dangerous-as-breaking true \
  --allow-breaking-schema-changes true
```

## `nitro api delete`

Delete an API by its ID. This removes the API and all of its schema versions, clients, and stages.

```
nitro api delete "<api-id>"
```

### Arguments

| Argument | Description                        |
| -------- | ---------------------------------- |
| <id>     | ID of the API to delete. Required. |

### Options

| Option   | Description                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------------- |
| \--force | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with \--output json. |

[Edit this page on GitHub](https://github.com/ChilliCream/graphql-platform/edit/main/website/content/docs/nitro/cli/api.md)

Last updated on **June 30, 2026** by **Tobias Tengler**