API Call Component

The API Call component connects your agent to any HTTP API. You can fetch data, send updates, or trigger actions.
If you’ve used Postman or curl, this will feel familiar — but with built-in security, observability, retries, and Vault integration.

Quick Start: Test Your First Call

1. Method: GET
2. URL:

Sample URL

HTTPGET

https://jsonplaceholder.typicode.com/todos/1

3. Click Test → You should see a JSON object with "id": 1.

Once you confirm this works, you can add headers, authentication, and outputs.

Step 1: Choose Method and URL

Every request needs:

• Method: tells the server what you want to do.
• URL: the endpoint you’re calling.

Method	Common use	Body needed?	Safe to retry?
GET	Fetch data	No	Yes
POST	Create a resource	Often	No
PUT	Replace a resource	Yes	Yes
PATCH	Update part of data	Yes	Yes
DELETE	Remove a resource	Optional	Yes
HEAD	Get only headers	No	Yes
OPTIONS	Check allowed methods	No	Yes

Example:

Sample GET request

HTTP

https://api.example.com/users/{{userId}}

Step 2: Add Headers and Body

Most APIs need more than just a URL. You usually add:

• Headers → key-value pairs for metadata like authentication and content type.
• Body → the request payload (data you send), required for methods like POST, PUT, PATCH.

Headers

Header name	Purpose	Example
Authorization	Authentication token	Bearer {{KEY(MY_TOKEN)}}
Content-Type	Format of request body	application/json
X-API-Key	Vendor-specific key	{{KEY(API_KEY)}}

Secure headers

Use Vault to store tokens. Click the key icon in the header field and select a stored secret.
This prevents leaking keys into logs or history.

Body

The body is required for most POST, PUT, and PATCH requests.
The format depends on the API’s Content-Type header.

Content-Type	Example payload	When to use
application/json	json{`{ "name": "Alice", "role": "admin" }`}	Most modern APIs
multipart/form-data	file + { "title": "Avatar" }	File uploads
application/x-www-form-urlencoded	name=Alex&age=30	Web forms
text/plain	Hello world	Simple text APIs
application/xml	<user><name>Alex</name></user>	Legacy XML APIs
application/octet-stream	Raw binary	Uploading files/blobs

Serialization behavior

The component automatically encodes the body to match the Content-Type.
If they don’t align, the server may return 400 Bad Request or 415 Unsupported Media Type.

Example: POST with JSON body

{
  "email": "[email protected]",
  "active": true
}

When you send this with Content-Type: application/json, the server expects properly formatted JSON.

Step 3: Add Authentication

APIs almost always require authentication. There are two main types supported here:

Option A: Header Keys (simplest)

You paste a static token or API key into the Authorization header.

`Authorization: Bearer {{KEY(MY_TOKEN)}}`

• Good for: testing, personal tokens, simple APIs.
• Limitations: tokens may expire, often lower rate limits.

Option B: OAuth (recommended)

OAuth is like giving your agent a temporary pass instead of a permanent key. The system automatically handles token refresh, so you don’t have to rotate secrets manually.

Supported OAuth flows

Flow	When to use	Example
Authorization Code (with PKCE)	When a user needs to log in (e.g. “Login with Google”).	Connecting to Gmail, LinkedIn
Client Credentials	When services talk directly, no user login needed.	Server-to-server APIs
OAuth 1.0a	Older APIs still using this.	Legacy Twitter API

Setup in the component

1. Select OAuth as authentication type.
2. Choose your provider (Google, LinkedIn, Twitter, or Custom).
3. Enter the required fields (client ID, secret, scopes).
4. Test the connection — tokens are fetched and managed automatically.

Why OAuth?

• Tokens refresh automatically.
• More secure than static keys.
• Often grants higher API rate limits.

Mental model

• API key = a permanent password you paste in.
• OAuth = the system logs in for you and rotates short-lived passes.

Step 4: Test Your Call

1. Fill in Method and URL.
2. Add headers and authentication if required.
3. Click Test.
4. Inspect the Response tab — check status, headers, and body.

Step 5: Work With Outputs

The response is available as Response and can be used in later steps.
Use JSONPath to extract values.

Use case	JSONPath expression
First item ID	Response.data[0].id
Nested field	Response.user.profile.email
Default fallback	Response.items[0] ?? 'guest'

Step 6: Handle Errors and Retries

Status	Meaning	What to check
400	Bad request	Check body, parameters, Content-Type
401/403	Unauthorized	Token validity, scopes
404	Not found	URL or resource ID
429	Too many requests	Rate limiting; enable retries/backoff
5xx	Server error	Retry later, check provider status

Retries and backoff are built in. Secrets are redacted in logs.

Step 7: Debug and Mock

• Preview request to see variables resolved before sending.
• Run logs show full request/response for troubleshooting.
• Mock Data lets you simulate responses safely without calling live APIs.

Troubleshooting FAQ

How do I send a Bearer token?
Add under Headers: Authorization: Bearer {{KEY(TOKEN)}}.

Why do I see 415 Unsupported Media Type?
Your request body doesn’t match the Content-Type header.

How do I upload a file with multipart?
Choose multipart/form-data and include both the file and metadata.

How do I paginate results?
Use query parameters like page or cursor, or parse Link headers.

How do I extract nested JSON?
Example: Response.user.address[0].city.