Call an API from an automation

Use an HTTP step when an automation needs an outside API that has no connector of its own. http.get reads, and http.send writes with POST, PUT, PATCH or DELETE. A send changes data outside Tale, so a live run asks for an approval first, as every write does. A test run never sends: it answers with a mock.

Read from an API

nodes:
  - id: orders
    type: http.get
    credential: Shop API
    input:
      url: /orders
      query: { status: open }

The step returns { status, ok, headers, body }. body holds the parsed JSON or the text, and null for an empty answer. headers keeps content-type, etag, last-modified, location, link, retry-after and the x-ratelimit- headers, and drops the others. A status outside 200–299 fails the step unless okStatuses lists it; then ok is false, and a later step decides what to do with the answer.

Send to an API

http.send takes the same inputs and three more: method (POST, PUT, PATCH or DELETE, required), body and contentType. A JSON value in body is sent as JSON. A string is sent as it is, with contentType, or text/plain without one.

nodes:
  - id: create_order
    type: http.send
    credential: Shop API
    input:
      url: /orders
      method: POST
      body:
        item: '{{ input.item }}'
        quantity: 2

Sign in with a credential

In Settings › Connectors, add a credential to HTTP. Choose how it signs in: a bearer token, an API key sent in a header, or a user name and password. Enter its Base URL, such as https://api.example.com/v2; for an API key, API key header names the header, X-Api-Key by default. Give the credential a name, and name it in the step's credential field.

A credentialed step stays under the base URL. A path is placed under it, a full address must start with it, and a redirect may not leave it. Only the credential signs the request. Wherever an answer would hand back one of the credential's values, Tale replaces it with [redacted], so it never reaches a run's record.

A step without a credential carries none, never the organization's default one, and calls public https:// addresses only.

What Tale refuses

• A private network address or a cloud metadata address, with or without a credential.
• A plain http:// address. The editor warns about one before you save.
• A user name or a password written into the address, or a credential in a query parameter of it: the editor refuses the save. Store the credential in Settings › Connectors instead.
• An Authorization or Cookie header set by the step. The editor refuses this too.
• An answer larger than 1 MB.

An organization's HTTP steps make at most 120 calls a minute across the deployment, and 10 at once on one server. A call over the minute's budget fails; one over the number at once waits for a free slot as long as its timeoutMs allows.

When a step fails

The run page says why an HTTP step failed and how to fix it. The execution logs explain how to read the failure.