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 <endpoint> [flags]

The current instance's access token is attached automatically, and the response body is streamed to stdout exactly as received.

Arguments

Name	Description
<endpoint>	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

Name	Description
--org	Override the active organization. Used to fill the {org} placeholder.

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.
--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

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, 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

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 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

-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

-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

--input <file> sends a raw request body. Use --input - to read the body from stdin.

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 <status> line is written to stderr, and the command exits non-zero.

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

• amctl agent — high-level commands for managing agents
• amctl project — high-level commands for managing projects
• amctl context link — link the current directory to a project