OptiTech CLI command: api

The api command sends an authenticated request to any OptiTech API route and prints the response. Pass an API path as the first argument. The method defaults to GET, or POST when you supply a body.

By default the request uses your optitech auth credentials. To use a specific key, pass --api-key or set OPTITECH_API_KEY. The key's permissions determine what the request can do.

note

api is a raw passthrough: it does not read your context file or auto-fill parameters. Pass what each route needs explicitly. For example, optitech api /projects returns ERROR: org_id is required unless you add -Q org_id=<org_id> or authenticate with an organization API key. Get your organization ID from optitech orgs list.

Usage

optitech api <path> [options]

Options

Option	Description	Type	Default	Required
`--data`, `-d`	Raw request body: a JSON string, @file, or - for stdin. Overrides --field.	string	—	No
`--field`, `-F`	Body field key=value (repeatable). Dot-notation nests objects (e.g. -F branch.name=dev); values are typed (numbers, booleans, null, JSON).	array	—	No
`--header`, `-H`	Extra request header key:value (repeatable).	array	—	No
`--include`, `-i`	Print the response status and headers before the body.	boolean	`false`	No
`--list`	List available API endpoints from the OpenAPI spec.	boolean	`false`	No
`--method`, `-X`	HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to GET, or POST when a body is provided.	string	—	No
`--query`, `-Q`	Query parameter key=value (repeatable).	array	—	No
`--raw-field`, `-f`	Body field key=value with the value kept as a raw string.	array	—	No
`--refresh`	Refresh the cached OpenAPI spec (used with --list).	boolean	`false`	No

Examples

GET request

Pass required parameters with --query (-Q); add --include (-i) to print the status and headers before the body:

optitech api /projects -Q org_id=org-cool-darkness-12345678 -i

The response is the route's raw JSON. For the fields each route returns, see the OptiTech API Reference.

Request body

Set body fields with --field (-F) as key=value. Values are typed automatically (numbers, booleans, null, and JSON), and dot-notation nests objects. A body switches the default method to POST:

optitech api /projects/{project_id}/branches -F branch.name=dev

This sends { "branch": { "name": "dev" } }. Use --raw-field (-f) to keep a value as a literal string. For a full JSON body, use --data (-d) with a string, @file, or - (stdin).

Create a project

POST /projects takes a project object. To create it under an organization, set project.org_id in the body (unlike GET /projects, which takes org_id as a query parameter):

optitech api /projects -X POST -F project.name=my-project -F project.org_id=org-cool-darkness-12345678

For a larger body, put the JSON in a file and pass it with -d @<file>:

project.json

{
  "project": {
    "name": "my-project",
    "org_id": "org-cool-darkness-12345678"
  }
}

optitech api /projects -X POST -d @project.json

List endpoints

--list prints every route from the OptiTech OpenAPI spec; --refresh refetches the cached spec:

optitech api --list

YAML output

Responses print as JSON. Use the global --output yaml (-o yaml) for YAML:

optitech api /projects -Q org_id=org-cool-darkness-12345678 -o yaml