Call an External API

Use a direct API call when the service you need has an HTTP API but no suitable built-in or custom integration.

Before building against it, find the service's current documentation and identify:

• The base URL and required endpoints.
• The authentication method.
• The request and response formats.
• Rate limits, timeouts, and documented errors.

Store credentials

Add API keys and tokens to Secrets. Refer to each credential by its environment-variable name in the prompt; never include the value.

Use the BILLING_API_TOKEN environment variable to authenticate server-side
requests to https://api.example.com/v1. Do not expose or log the token.

OAuth flows usually require more than a static secret. Describe the provider's authorization flow, callback URL, and required scopes, or configure an appropriate integration first.

Describe the request

Give the agent the endpoint, trigger, inputs, expected result, and failure behavior:

When the user submits the form, POST the validated fields to /customers.
Use a 10-second timeout. Show a useful error for authentication, rate-limit,
validation, and server failures, and do not retry validation errors.

The agent can use a standard HTTP client or add a supported package when the API needs a specific SDK. See Install External Packages.

Review and test

• Keep credentials and privileged calls in backend code.
• Validate user-controlled values before sending them.
• Do not log tokens, passwords, or sensitive response data.
• Test success, timeout, rate-limit, authentication, and malformed-response cases.
• Confirm the integration against test data before using production credentials.

Related

• Webhooks — send event payloads to an incoming webhook.
• Custom Integration — save reusable service instructions and credentials at project level.
• Python Libraries — guide the agent when an API uses a specialized SDK.