Calling an API

The Call an API step calls an external system and returns the response. It is deterministic: same input, same result.

The form

Field	Use
Address	The full URL. http or https
Method	GET, POST, PUT, PATCH, DELETE — chosen from a list
Query parameters	A field of their own, encoded by the platform
Headers	Name and value
Body	For the methods that accept one
Timeout	Within the platform's ceiling

Produces: the HTTP code, the JSON body, the text body, the headers, and whether the response was truncated.

Use the parameters field, not the URL

Concatenating parameters into the URL makes a value containing a space, an accent, or & build a different request from the one you wrote. The dedicated field is encoded correctly.

Authentication

Almost every API asks for a credential. The form's Authentication section covers the usual forms, and in none of them do you type the credential inside the step:

Form	When to use
No authentication	Public APIs
Bearer	A token in the Authorization header — the most common
API Key	A key in a header of its own, or in a URL parameter
Basic	Username and password
OAuth 2.0 (client credentials)	The platform obtains the token with the client and secret, and renews it on its own
Custom	When the system requires an arrangement none of the above covers

Having chosen the form, you say which secret in the space supplies the value. The step keeps the reference to the secret; the value stays in the vault and enters the request only at the moment of the call.

Why the credential does not live in the step

A published version is immutable. A key typed into a header would go into it and never come out — not by editing, not by rotation. That is why publishing refuses values that look like credentials.

With the credential as a secret, three things start working:

• Rotation without republishing. You replace the secret's value and every agent referencing it starts using the new one. No definition changes, no version is republished.
• Immediate revocation. Disabling the secret cuts off its use right away, without erasing the record that it existed.
• Nothing appears in the history. What is recorded of the run shows the authentication header as ••••••••. Even someone with access to the history does not see the value.

Creating the secret

Secrets are created in the space's configuration, not inside the step. Each one gets an identifier of its own — starting with ags_ — and a name you choose so you can recognize it in the list.

Whoever creates it supplies the value once. After that it is not displayed again anywhere: the vault accepts replacement, never disclosure. If you lost the value, the way forward is to generate another in the source system and replace it here.

See Allowed resources.

A production secret does not apply in development

A secret declared as production-only is refused when the agent runs in development. The separation is deliberate: a test must not reach the real system by accident.

The address has to be allowed

The space keeps a list of allowed addresses. An address outside it is refused at publishing time, not on the first run.

If you need to call a new system, ask whoever administers the space to allow it. See Allowed resources.

What publishing refuses

These checks happen before the version exists:

Situation	Why
Missing or invalid address	Publishing without an address would create an immutable version that fails on its first run
A scheme other than http/https	Outside what the platform runs
An address outside the allowed list	The space's governance
An invented method	Only the methods on the list
A method assembled from data	The method has to be fixed
A timeout outside the range	Outside the platform's ceiling
A reserved header	Host, Content-Length, and the like belong to the platform
A header value that looks like a credential	See below
A parameter the action does not have	A typo becomes a refusal, not strange behavior

A credential in a header is refused

See Authentication. Publishing refuses a header value that looks like a credential; the way forward is the authentication section, with a space secret.

Network protection

Even with the address allowed, the platform resolves the name at call time and blocks internal destinations — private, local, and metadata service addresses — including when a redirect tries to lead there.

An address assembled from data publishes with a warning: the platform cannot state in advance where it points, and the protection then acts on every connection.

What publishing does not do

It does not resolve the name or open a connection to validate it. A correct agent must not become unpublishable because the server on the other side happened to be down that minute.

Run an automation

When the call involves more than one request — authenticating, paginating, handling a specific error — the way forward is the Run an automation step: a published program, with declared inputs and outputs, adopted by the organization.

The difference: an HTTP call is one request; an automation is a procedure. Neither uses AI.

Common errors

Symptom	Cause	What to do
Publishing refused because the address is not allowed	The host is not on the space's list	Ask for it to be allowed
Publishing refused because it looks like a credential	A key written straight into the header	Use a secret reference
The call is blocked at run time	The destination resolved to an internal address	Confirm the system's public address
Truncated response	The response is larger than the limit	Narrow the query's scope or paginate

Next steps

• Allowed resources
• When something fails
• Step types