> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/resources/reporters/currents-cmd/currents-api.md).

# currents api

Call any route of the Currents REST API from the command line with the currents api command

`currents api <path>` sends an authenticated request to a route of the [Currents REST API](https://docs.currents.dev/api) and prints the response body. Use it for API calls that no other `currents` command makes, such as listing runs or creating a webhook.

## Usage

Run the commands on this page in a project that installs `@currents/cmd`. Elsewhere, replace `npx currents` with `npx --package @currents/cmd@2 currents`.

{% hint style="info" %}
The command needs an [API key](/dashboard/administration/api-keys.md), passed as `--api-key` or set as `CURRENTS_API_KEY`. Routes that change data need a key with write access.
{% endhint %}

```bash
npx currents api /v1/runs/<run-id>
```

The path is a REST API route. `/v1/runs/<run-id>`, `v1/runs/<run-id>` and `runs/<run-id>` are the same route.

A response that is not 2xx prints its body on stderr, and the command exits with `1`.

## Send parameters

* `-f key=value` adds a parameter. `true`, `false`, `null` and numbers are sent as JSON values. In a JSON body, `key[]=value` adds the value to an array.
* `-F key=value` adds a parameter whose value is always a string.
* Without `-X`, parameters make the request a `POST` with the parameters in a JSON body. To send them in the query string of a `GET`, pass `-X GET`.
* `--input <file>` sends the JSON in the file as the body, or the JSON from stdin with `-`. The parameters then go to the query string.

## Examples

List the failed runs of the `main` branch of a project:

```bash
npx currents api /v1/projects/<project-id>/runs -X GET -f "branches[]=main" -f status=FAILED -f limit=20
```

Cancel a run:

```bash
npx currents api /v1/runs/<run-id>/cancel -X PUT
```

Create a webhook from the JSON in `webhook.json`:

```bash
npx currents api /v1/webhooks -X POST -F projectId=<project-id> --input webhook.json
```

## Options

| Option                        | Environment variable | Description                                                                                               |
| ----------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
| `--api-key <api-key>`         | `CURRENTS_API_KEY`   | An API key from the Currents dashboard. Required.                                                         |
| `-X, --method <method>`       |                      | The HTTP method. Default: `GET`, or `POST` when `--field`, `--raw-field` or `--input` is given.           |
| `-f, --field <key=value>`     |                      | A request parameter. Repeat for more. Sent in the query string of a `GET` and in the JSON body otherwise. |
| `-F, --raw-field <key=value>` |                      | Like `--field`, but the value is always a string.                                                         |
| `--input <file>`              |                      | Send the JSON in this file as the body, or the JSON from stdin with `-`.                                  |
| `-H, --header <key:value>`    |                      | An HTTP header to send. Repeat for more.                                                                  |
| `-i, --include`               |                      | Print the HTTP status line and the response headers before the body.                                      |
| `--debug`                     | `CURRENTS_DEBUG`     | Print debug logs. Keys are hidden in them. Default: `false`.                                              |

The command does not page through results. To read the next page, send the cursor or page parameter that the route describes in [Pagination](https://docs.currents.dev/api/get-started/pagination).

To get one run by its CI build ID, or the last run of a branch, use [currents run get](/resources/reporters/currents-cmd/currents-run-get.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.