HTTP Requests: Connect to Any API

The HTTP capability is your agent’s “swiss army knife”—enabling it to talk to virtually any online service that has an API. If a service exists on the internet and exposes an API, your agent can interact with it. In this example, we simply asked the agent to “check the current weather in Stockholm using a suitable API.” The agent found a free weather API, made the HTTP request, parsed the JSON response, and presented the results in a readable table—all without any configuration.

​

How it works

Once enabled, you simply tell your agent which API you want to interact with—either in the chat or in your instructions. The agent figures out how to call the API and handles the request for you.

​

How the agent learns APIs

Think about what a human developer would need to work with an API—your agent needs the same things: Well-known APIs — For popular services (weather APIs, social platforms, major SaaS tools), the agent often knows how to use them already from the LLM’s training data. Things usually work right off the bat. Less familiar APIs — For niche or custom APIs, you have several options:

• Let it experiment — Ask the agent to try the API and figure it out through trial and error
• Point to documentation — Give the agent a URL to the API reference, or upload a PDF with the docs
• Use web search — Enable Web Search and ask the agent to research the API online
• Describe it yourself — If you know the API, just explain the endpoints and expected responses in the chat

The more context you provide, the faster the agent will succeed—especially for internal or proprietary APIs that don’t exist in public documentation.

​

Guardrails and approval

The HTTP capability card on the agent has two main guardrails:

• Allow requests to any URL (without secrets) — When on, the agent can hit any public HTTPS URL. When off, requests are only permitted to endpoints defined by an enabled API Capability, so the agent is locked down to a specific set of APIs.
• Require Approval — Choose No, Yes, for all requests, or Yes, except GET requests. When approval is required, the agent must wait for a workspace member to approve each outgoing request before it executes.

This is similar to how approval works for email and SMS.

​

When to use HTTP requests

The HTTP capability is ideal when:

• No existing capability — The service you need isn’t available as a built-in capability or MCP server
• Quick prototyping — You want to test an integration before investing in a proper setup
• Internal APIs — You have proprietary services or internal databases with REST endpoints
• Combining APIs — Your workflow requires calling multiple APIs in sequence

​

Example use cases

Real-time data lookups:

• “Check the current Bitcoin price using a cryptocurrency API”
• “Get the latest exchange rate between USD and EUR”
• “Look up the shipping status for order #12345 via the carrier’s API”

Combining multiple APIs:

• “Convert this address to GPS coordinates, then find the nearest coffee shops using a places API”
• “Fetch the weather forecast, then post a summary to Slack”
• “Look up the company info from this domain, then add it to my CRM”

Prototyping integrations:

• “Connect to our internal inventory API and check stock levels for product SKU-1234”
• “Query our company’s time tracking API and summarize my hours this week”

​

Real-world example: Office location analyzer

We built an HR agent that knows where all our employees live and helps analyze potential new office locations by calculating transit times for each person. This required chaining multiple APIs:

1. Geocoding API — Convert street addresses to GPS coordinates
2. Transit time API — Calculate commute times between coordinates
3. Map visualization — The agent built an interactive map to display the results

It took some iteration for the agent to discover which APIs to use and how to call them. But once it worked, we asked the agent to document the process—essentially “codifying” those API calls into its instructions so future requests are fast and reliable.

​

Handling credentials

For authenticated APIs, define an API Capability (Shared Assets → API Capabilities) that describes the endpoints and its keyholes — what kind of key the API needs and where it goes in the request. A keyhole holds no key itself: when you enable the API on an agent (on that agent’s Capabilities page), you choose which Secret goes in each keyhole, or create a new key right there. Different agents can use different keys for the same API, and each key keeps its own access settings. The platform supports bearer tokens, API key headers, basic auth, query parameters, and custom headers — plus managed flows including OAuth 2.0 client credentials, GCP service accounts, and signed JWT bearer tokens (RS256 / ES256). The agent references the API by name; the actual secret value is injected server-side and never reaches the LLM. Both Secrets and API Capabilities have a single agent access setting — No one, Entire workspace, Certain teams (all agents in the teams you pick), or Certain agents — and the platform only lets those agents use them. New ones start at No one until you make that choice. If your workspace uses agent lifecycle phases, you can also limit a secret or API Capability to production or sandbox agents, and give sandbox agents a separate test value of a secret. See Credentials for more on how secrets are stored and protected.

​

Defining endpoints

Every API Capability lists one or more endpoint patterns. They do two jobs:

• Routing — when the agent makes a request, the platform matches the URL against the patterns to work out which API it belongs to, and injects that API’s credentials.
• Restriction — with Allow requests to any URL turned off, the agent can only reach URLs that match one of the patterns.

Patterns are URL prefixes, not regular expressions: A few rules worth knowing:

• Agents call HTTPS on port 443 only. You can write the https:// prefix or leave it out — but a pattern that asks for http:// or another port is rejected, and a plain http:// request is refused before it leaves the platform, so a credential can never travel unencrypted.
• The path is matched as a prefix, so /api/3/ already covers everything below it — a trailing * is optional.
• * stands for a single path segment, or a single subdomain level in the host. It never spans a / or a ..
• OpenAPI-style placeholders such as {id} are not supported — use * instead.

Redirects are not followed automatically. If an endpoint answers with a redirect, the agent is given the target address and decides whether to call it — which runs the endpoint match and the credential injection again for the new URL. This keeps a redirect from carrying your credentials to a host you never approved. It also means that with Allow requests to any URL turned off, the redirect target must match an endpoint pattern too — if an API hands off downloads to a CDN, add the CDN host as an endpoint.

​

Available methods

The agent can use any standard HTTP method:

​

Tips for reliability

Ask the agent to remember what worked. Once your agent successfully calls an API, ask it to update its instructions with the details—endpoint URLs, required headers, expected responses. This “codifies” the API and makes future calls instant. Start simple. Test with basic GET requests before building complex multi-step workflows. Provide documentation. If you have API docs, share them with the agent. The more context it has, the faster it can figure out the correct calls.

​

FAQ

​

Learn more