---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
alternate:
  - https://sourcecraft.dev/portal/docs/en/cli-ref/src-api.md
  - https://sourcecraft.dev/portal/docs/ru/cli-ref/src-api.md
  - href: en/cli-ref/src-api.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt

# src api

Makes an authenticated HTTP request to the SourceCraft REST API and prints the response.

The path argument should be a path of a SourceCraft REST API endpoint.

Placeholder values {org} (or {owner}) and {repo} in the path get
replaced with values from the repository of the current directory or the
repository selected with the global -R/--repo flag.

The default HTTP request method is GET, and POST if any parameters were added or
a request body is supplied via --input. Override the method with -X/--method.

Pass one or more -f/--raw-field values in key=value format to add static string
parameters to the request payload. To add non-string or placeholder-determined
values, use -F/--field. Adding request parameters automatically switches the
request method to POST; to send them as a GET query string instead, use
--method GET.

The -F/--field flag has magic type conversion based on the format of the value:

* literal values true, false, null, and integer numbers get converted to
appropriate JSON types;
* placeholder values {org} (or {owner}) and {repo} get populated with
values from the current repository;
* if the value starts with @, the rest is interpreted as a filename to read the
value from. Pass @- to read from standard input.

To pass nested parameters, use key[subkey]=value syntax. To pass arrays, declare
multiple fields with key[]=value1, key[]=value2. To pass an empty array, use
key[] without a value.

To pass a pre-constructed request body, read it from a file with --input (use -
to read from standard input). When passing the body this way, any parameters
specified via field flags are added to the query string of the endpoint URL.

Pass -q/--jq to filter the JSON response through a jq expression. The results are
printed one per line; a successful but empty response and a non-2xx error body
are passed through untouched.

Pass -t/--template to format the JSON response with a Go template. A successful
but empty response and a non-2xx error body are passed through untouched.

Pass --paginate to fetch all pages of a list endpoint by following the
next_page_token of each response (page_size defaults to 100 when not set). The
pages are merged by concatenating their single top-level array field into one
flat JSON array — so --jq and --template see an array, not the per-page
envelope. Pass --slurp to instead collect the raw page objects into an outer
JSON array.

Pass --silent to discard the response body; the exit code still reflects the
HTTP status.

Pass the global -V/--verbose flag to dump the full HTTP request and response
(method, URL, headers, and body) to standard error for debugging.

## Usage

`src api <path> [flags]`

### Examples

**Get the authenticated user**

`src api user`

**List issues in the current repository**

`src api repos/{owner}/{repo}/issues`

**Post an issue comment**

`src api repos/{owner}/{repo}/issues/123/comments -f body='Hi from the CLI'`

**Add parameters to a GET request**

`src api -X GET repos/{owner}/{repo}/issues -f filter='status = open'`

**Use a JSON file as the request body**

`src api repos/{owner}/{repo}/pulls --input body.json`

**Set a custom HTTP header**

`src api -H 'Accept: application/json' user`

**Include response status line and headers**

`src api -i user`

**Filter the response with jq (list responses are envelopes, e.g. {"issues": [...]})**

`src api repos/{owner}/{repo}/issues -q '.issues[].title'`

**Format the response with a Go template**

`src api repos/{owner}/{repo}/issues --template '{{range .issues}}{{.title}}not_var{{"\n"}}{{end}}'`

**Fetch all pages, merged into one flat array**

`src api repos/{owner}/{repo}/issues --paginate -q '.[].title'`

### Flags

| Flag | Description |
| --- | --- |
| `-F, --field key=value` | Add a typed parameter in key=value format (use "@<path>" or "@-" to read from a file or stdin) |
| `-H, --header key:value` | Add an HTTP request header in key:value format |
| `-i, --include` | Include HTTP response status line and headers in the output |
| `--input file` | The file to use as the request body (use "-" to read from standard input) |
| `-q, --jq string` | Query to select values from the response using jq syntax |
| `-X, --method string` | The HTTP method for the request (default "GET") |
| `--paginate` | Make additional HTTP requests to fetch all pages of results |
| `-f, --raw-field key=value` | Add a string parameter in key=value format |
| `--silent` | Do not print the response body |
| `--slurp` | Use with "--paginate" to return an array of all pages of results |
| `-t, --template string` | Format JSON output using a Go template |

### Inherited flags

| Flag | Description |
| --- | --- |
| `--env string` | Override Sourcecraft environment (use 'src envs' to list available) |
| `--json string` | Output JSON, optionally filtered (--json or --json=field1,field2) |
| `--json-compact string` | Output compact JSON, optionally filtered |
| `-R, --repo string` | Select another repository using OWNER/REPO format |
| `-V, --verbose` | Enable debug logging output |

### Learn more

Use `src api <subcommand> --help` for more information about a command.