On this page

RUN

Core command

Calls an endpoint of the connected API by its URL, GET by default.

Syntax

RUN [<method>] <url> [TABLE | RAW]

Quick start

CONNECT API DESK:PROD;
RUN /api/customer/123;

Connects to the PROD environment of the DESK API, then sends GET /api/customer/123.

Arguments

Argument	Required	Values	Default
`<method>`	No	`GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`	`GET`
`<url>`	Yes	A URL relative to the connected API, with literal values, `:name`, `${name}` or `${ENV:NAME}`	None
`TABLE` or `RAW`	No	Shows the response as a table, or raw	A complete list

Examples

RUN /api/customer/123;
RUN /api/customer/123?expand=mail&showall=true;
RUN DELETE /api/customer/123;
RUN /api/customer/:id;
RUN /api/customer/${ENV:CUSTOMER_ID};
RUN /api/customer/${customerId};
RUN /api/customer/123 RAW;

Details

The API and the URL

The relative URL is resolved against the API of the session: run CONNECT API <api>:<environment> first. RUN takes no API or environment of its own, and fails clearly when no API is connected. The HTTP method is optional and defaults to GET; HEAD, POST, PUT, PATCH and DELETE are written before the URL: RUN DELETE /api/customer/123;. OPTIONS and any other method are refused.

Values in the URL

A literal value, such as 123, is used as written.
A :name path or query placeholder takes, in this order: the session variable set with VAR, the variable of the current API environment, the value saved for this endpoint in CONFIG API, the endpoint's default. Otherwise a clear error names the missing parameter.
${name} or {{name}} is an API or environment variable, the same templating as inside a stored endpoint. It is resolved in the typed URL, against the active environment, before the endpoint is matched, so it can change which endpoint a URL matches.
${ENV:NAME} reads an operating system environment variable when the command runs. An undefined one fails the command; it is never replaced by an empty text. It is unrelated to ${name}.

Query parameters are taken from the URL only: what is written is sent, plus any required parameter missing from the URL that can still be resolved as above, never an optional parameter that the URL does not mention.

Endpoint names and aliases

An endpoint's id, alias (CONFIG API) or name helps to find it, but is never run directly: RUN CUST; is refused with a hint towards SYNTAX CUST; and RUN CUST<TAB>, which completes the URL. Most imported endpoints have no alias, only a name and an id; completion works from any of the three.

Output

The response is shown as a complete list by default; TABLE shows it as a table and RAW as the raw response.

Last modified in release 5.5.0.

Found something wrong or unclear on this page? Tell us, with the page address.

RUN