API Call Component
Use API Call when your agent needs to hit an external HTTP endpoint: to fetch data, trigger an action, or update a system.
Why this matters
What You’ll Configure
- Set the Core Request
- Add Inputs
- Add Authentication
- Handle Pagination and Rate Limits
- Enable Mock Mode
- Capture Outputs
- Common API Examples
- Best Practices
- Troubleshooting Tips
- What to Try Next
Step 1: Set the Core Request
Field | Required? | Purpose | Quick Tips |
---|---|---|---|
Method | Yes | HTTP verb (GET , POST , etc.) | Choose the simplest method that works |
URL | Yes | Target endpoint | Supports variables like {{input.userId}} , {{vault.token}} |
Headers | No | Authorization, content-type, etc. | JSON format. Supports variables |
Content-Type | No | MIME type for the body | Examples: application/json , form-data , text/plain |
Body | No | Payload for methods like POST or PUT | Follows Content-Type and supports dynamic data |
URL Pattern Cheatsheet
https://api.example.com/users
Step 2: Add Inputs
- Open the Inputs tab
- Select + Add Input
- Define type, default value, and mark optional if needed
Type | Notes |
---|---|
string | Basic text |
number | Integer or decimal |
boolean | true or false |
array | JSON list |
object | JSON object |
binary | Files, base64, or external URLs |
date | ISO 8601 format |
Step 3: Add Authentication
Use the Vault
INFO
Built-in OAuth 2.0
Field | Purpose |
---|---|
Scopes | Space-delimited list of access rights |
Auth URL | Where users authorize |
Token URL | Exchanges code for token |
Client ID / Secret | Credentials from your app |
Callback URL | Must match platform setup |
expires_in
is present in the response.
Other Auth Flows
Flow | Requirements | When to Use |
---|---|---|
OAuth 1.0a | Token URLs, Consumer Key/Secret, Callback | Older APIs like Twitter |
Client Credentials | Token URL, Client ID/Secret | Server-to-server, no user prompt |
API Key in Header | Header field like Authorization | Simple key-based access |
JWT (Bearer Token) | Encoded token in headers | Authenticated access via token sharing |
Step 4: Handle Pagination or Rate Limits
Pagination logic
Step 5: Enable Mock Mode
TIP
- Toggle Use Mock Data in the settings panel
- Edit the mock response JSON in the editor
- Use Debug to simulate how your agent will behave
Sample Success
{
"Response": {
"status": "ok",
"data": {
"user": { "id": 123, "name": "Jane Doe" }
}
}
}
Sample Error
{
"Response": {
"status": 429,
"error": "rate_limit",
"message": "Too many requests"
}
}

Step 6: Capture Outputs
Output | Description |
---|---|
Response | Full API response (JSON or text) |
Headers | Key-value pairs from the response |
Optional Custom Output
You can extract just the part you need:
{
"Name": "userId",
"Expression": "Response.data.user.id"
}
Common API Examples
POST to Slack (Send alert)
{
"url": "https://hooks.slack.com/services/T000/B000/XXX",
"method": "POST",
"headers": { "Content-Type": "application/json" },
"body": { "text": "New signup: {{input.userName}}" }
}
GET GitHub Issues (with params)
{
"url": "https://api.github.com/repos/{{input.owner}}/{{input.repo}}/issues?state=open&per_page=100",
"method": "GET",
"headers": { "User-Agent": "SmythOS-Agent" }
}
PUT User with If-Match Header
{
"url": "https://api.example.com/users/{{id}}",
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"If-Match": "{{input.etag}}"
},
"body": { "name": "{{input.newName}}" }
}
Upload to Imgur (multipart)
{
"url": "https://api.imgur.com/3/upload",
"method": "POST",
"headers": {
"Authorization": "Client-ID {{vault.imgur_client_id}}",
"Content-Type": "multipart/form-data"
},
"body": {
"image": "{{input.file}}",
"type": "file"
}
}
Best Practices
- Test with Debug Mode before going live
- Use Retry and Condition blocks for error handling
- Never hardcode credentials — use Vault
- Validate API URLs and tokens in Postman or curl
- Keep inputs and outputs named clearly
- Use Mock Mode during dev or rate-limited testing

Troubleshooting Tips
If your call fails...
What to Try Next
- Combine API Call with Code Component to clean or validate responses
- Link with Agent Skill to allow natural inputs (text, voice) to trigger your call
- Use Condition blocks to handle branches like
status === 404
- Store secrets in Vault securely
- Chain multiple API calls for multi-step workflows
- Adapt examples from the Common Examples above to your use case
Tip