Skip to main content

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
You can reach nearly any REST-style service without custom code.
Define your call once, pass dynamic inputs at runtime, and inject secrets via Vault.

What You’ll Configure

Step 1: Set the Core Request

FieldRequired?PurposeQuick Tips
MethodYesHTTP verb (GET, POST, etc.)Choose the simplest method that works
URLYesTarget endpointSupports variables like {{input.userId}}, {{vault.token}}
HeadersNoAuthorization, content-type, etc.JSON format. Supports variables
Content-TypeNoMIME type for the bodyExamples: application/json, form-data, text/plain
BodyNoPayload for methods like POST or PUTFollows Content-Type and supports dynamic data

URL Pattern Cheatsheet

https://api.example.com/users

Step 2: Add Inputs

  1. Open the Inputs tab
  2. Select + Add Input
  3. Define type, default value, and mark optional if needed
TypeNotes
stringBasic text
numberInteger or decimal
booleantrue or false
arrayJSON list
objectJSON object
binaryFiles, base64, or external URLs
dateISO 8601 format

Step 3: Add Authentication

Use the Vault

INFO

Store API keys in Vault and inject them like {{vault.api_key}} inside headers or body.

Built-in OAuth 2.0

FieldPurpose
ScopesSpace-delimited list of access rights
Auth URLWhere users authorize
Token URLExchanges code for token
Client ID / SecretCredentials from your app
Callback URLMust match platform setup
SmythOS handles automatic token refreshing when expires_in is present in the response.

Other Auth Flows

FlowRequirementsWhen to Use
OAuth 1.0aToken URLs, Consumer Key/Secret, CallbackOlder APIs like Twitter
Client CredentialsToken URL, Client ID/SecretServer-to-server, no user prompt
API Key in HeaderHeader field like AuthorizationSimple key-based access
JWT (Bearer Token)Encoded token in headersAuthenticated access via token sharing

Step 4: Handle Pagination or Rate Limits

Pagination logic

Loop paginated responses using a Condition block.

{
"if": "Response.next_page != null",
"then": "repeat API Call with {{Response.next_page}}"
}

Use headers like Retry-After or X-RateLimit-Remaining to control rate-limited calls.

Step 5: Enable Mock Mode

TIP

Mock Mode helps you simulate API responses for testing without hitting the live service.

  1. Toggle Use Mock Data in the settings panel
  2. Edit the mock response JSON in the editor
  3. 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"
}
}
Mock editor in API component

Step 6: Capture Outputs

OutputDescription
ResponseFull API response (JSON or text)
HeadersKey-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
API Call component UI

Troubleshooting Tips

If your call fails...
  • Check the request headers — especially Content-Type
  • Confirm that Vault keys exist and are correctly named
  • Verify that the endpoint needs auth and you've supplied it
  • Use Postman or curl to isolate request issues

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

When copying code from API docs, just replace the dynamic values with {{input.name}} or {{vault.secret}}.