# amctl api Make an authenticated HTTP request to the Agent Manager API and print the response verbatim. `amctl api` is the low-level escape hatch for endpoints that do not yet have a dedicated command, modeled on GitHub CLI's `gh api`. ``` amctl api [flags] ``` The current instance's access token is attached automatically, and the response body is streamed to stdout exactly as received. ## Arguments[​](#arguments "Direct link to Arguments") | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | API path to request. Resolved relative to the current instance's API base, so the `/api/v1` prefix may be omitted — `amctl api /orgs` and `amctl api /api/v1/orgs` are equivalent. May contain `{org}` and `{project}` placeholders. | ## Options inherited from parent commands[​](#options-inherited-from-parent-commands "Direct link to Options inherited from parent commands") | Name | Description | | ------- | ----------------------------------------------------------------------- | | `--org` | Override the active organization. Used to fill the `{org}` placeholder. | ## Options[​](#options "Direct link to Options") | Name | Short | Type | Default | Description | | ------------- | ----- | ------- | ---------------- | ------------------------------------------------------------------------------------------------- | | `--method` | `-X` | string | `GET` | HTTP method for the request. Switches to `POST` automatically when fields or a body are supplied. | | `--raw-field` | `-f` | strings | (none) | Add a string parameter as `key=value`. The value is sent as a raw string. Repeatable. | | `--field` | `-F` | strings | (none) | Add a typed parameter as `key=value`. Repeatable. See [Typed fields](#typed-fields). | | `--header` | `-H` | strings | (none) | Add a request header as `Name: value`. Repeatable. | | `--input` | | file | (none) | File to send as the raw request body. Use `-` to read stdin. | | `--include` | `-i` | bool | `false` | Print the response status line and headers before the body. | | `--project` | | string | (linked project) | Project used to fill the `{project}` placeholder. | ## Org and project placeholders[​](#org-and-project-placeholders "Direct link to Org and project placeholders") Most Agent Manager resources are scoped to an organization and project, under paths like `/orgs/{org}/projects/{project}/...`. For endpoints that include the literal `{org}` and `{project}` tokens, those placeholders are substituted from the current context, using the same precedence as other commands: 1. The `--org` / `--project` flags. 2. The linked project for the working directory. 3. The active org (`current_org`). From a [linked directory](/agent-manager/docs/next/reference/cli/overview/.md#linked-context), `amctl api /orgs/{org}/projects/{project}/agents` works without spelling out names. note An unknown placeholder (for example, a typo like `{proj}`) fails immediately with `unknown placeholder {proj} (supported: {org}, {project})` and makes no HTTP request. A known placeholder that resolves to empty also errors before any request is sent. ## HTTP method[​](#http-method "Direct link to HTTP method") The method defaults to `GET`. It switches to `POST` automatically when you supply fields (`-f` / `-F`) or a request body (`--input`). Override the method explicitly with `-X` / `--method`. ## Fields[​](#fields "Direct link to Fields") Fields become query-string parameters on a `GET` request, and a JSON request body otherwise. * `-f key=value` sends the value as a raw string. * `-F key=value` is typed — see below. ### Typed fields[​](#typed-fields "Direct link to Typed fields") `-F` parses the value before sending it: | Value | Sent as | | ---------------- | ----------------------------------------- | | `true` / `false` | boolean | | an integer | number | | `null` | null | | `@path` | the contents of a file (`@-` reads stdin) | | anything else | string | ## Headers[​](#headers "Direct link to Headers") `-H "Name: value"` adds a request header. The current instance's access token is attached as a bearer token automatically when no `Authorization` header is given; supplying your own `Authorization` header overrides it. ## Request body[​](#request-body "Direct link to Request body") `--input ` sends a raw request body. Use `--input -` to read the body from stdin. ## Response[​](#response "Direct link to Response") The response body is streamed to stdout exactly as received. With `-i` / `--include`, the status line and response headers are printed before the body. On an HTTP status of 400 or above, the body is still printed, a short `amctl: HTTP ` line is written to stderr, and the command exits non-zero. ## Examples[​](#examples "Direct link to Examples") ``` # List organizations amctl api /orgs # List agents, filling {org}/{project} from the current context amctl api /orgs/{org}/projects/{project}/agents # Get one agent (org/project spelled out explicitly) amctl api /orgs/default/projects/default/agents/it-helpdesk-agent # Filter with query parameters (explicit GET keeps fields in the query) amctl api -X GET /orgs/{org}/projects/{project}/agents -f limit=10 # Create a project from typed fields (inferred POST + JSON body) amctl api /orgs/{org}/projects -f name=triage -F retain=true # Send a raw JSON body from a file or stdin amctl api -X POST /orgs/{org}/projects --input ./project.json cat project.json | amctl api -X POST /orgs/{org}/projects --input - # Inspect response headers amctl api -i /orgs/{org}/projects/{project}/agents ``` ## See Also[​](#see-also "Direct link to See Also") * [`amctl agent`](/agent-manager/docs/next/reference/cli/agent/.md) — high-level commands for managing agents * [`amctl project`](/agent-manager/docs/next/reference/cli/project/.md) — high-level commands for managing projects * [`amctl context link`](/agent-manager/docs/next/reference/cli/context/.md#amctl-context-link) — link the current directory to a project