> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Action

> Integrating external services into your agent workflows

**API Actions** grant your agents the ability to interact with the real world by calling external services.

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <img src="https://mintcdn.com/maitai-cbe2cd27/o70b7aP0pbkBNV82/images/forge/agents/Build_Agents_Capabilities_APIAction1.png?fit=max&auto=format&n=o70b7aP0pbkBNV82&q=85&s=7b9f2e7357f71459fef79a04dca8ba65" style={{width: '100%', height: 'auto'}} width="701" height="900" data-path="images/forge/agents/Build_Agents_Capabilities_APIAction1.png" />

  <img src="https://mintcdn.com/maitai-cbe2cd27/o70b7aP0pbkBNV82/images/forge/agents/Build_Agents_Capabilities_APIAction2.png?fit=max&auto=format&n=o70b7aP0pbkBNV82&q=85&s=cee5b8565d1e68dcf894a3196a4e7bb5" style={{width: '100%', height: 'auto'}} width="700" height="899" data-path="images/forge/agents/Build_Agents_Capabilities_APIAction2.png" />
</div>

### Configuration

* **Endpoint & Schema**: Define the HTTP method, URL, timeout, and a JSON schema for the action's parameters, including which are required. Use `{{parameter_name}}` placeholders for dynamic values in the URL path or query.
* **Importing Specs**: Bootstrap quickly by uploading an **OpenAPI spec**: create a single action or a full set of API Actions in bulk.
* **Usage Guidance**: **When to use** / **When not to use** hints that feed routing and orchestration decisions. Specific guidance here directly improves capability selection.
* **Authentication**: Store API keys and headers in Maitai, or reference per-request secrets (below).
* **Response Handling**: Make **Real** API calls or return **Mock** responses for testing and prototyping.

## Invocation Mode

Every action is either **Foreground** or **Background**. What that means in practice depends on the agent's [execution mode](/build/agents/execution_mode):

|                      | Foreground                                                                     | Background                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`route` mode**     | Eligible to be the routed capability, its output becomes the agent's response. | Never the primary route. The router may select **one background action** to run in parallel with the routed capability, purely to enrich state/context for later turns. |
| **`reasoning` mode** | Results feed the loop and can be surfaced in the agent's final response.       | Context-only: results are stored for other actions and sub-agents to use, but never shown directly to the user.                                                         |

*Example*: a background `get_loan_options` action gathers data silently, which a "Loan Advisor" sub-agent then uses to formulate a tailored recommendation.

<Note>
  **Webhook Creation** actions are always foreground, they pause execution and need to drive the session, so they can't run as background enrichment.
</Note>

## Per-request secrets

Instead of storing credentials in Maitai, you can reference them by name and supply the value at request time. In the action's **auth** or **headers** config, use a `{{secrets.NAME}}` placeholder:

```text theme={null}
Authorization: Bearer {{secrets.stripe_key}}
```

Then pass the value when calling the agent:

```python theme={null}
agent = client.agent.get("YOUR_AGENT_NAME", version="prod")
request = agent.to_request(
    messages=[...],
    session_id="YOUR_SESSION_ID",
    secrets={"stripe_key": "sk_live_..."},
)
```

Secrets are validated up front (a `400` lists any missing names), resolved only inside auth/headers, never exposed to the LLM, and redacted before any request record is persisted. Sub-agents invoked during the run can resolve the same secrets. Full details: [Agent Call, per-request secrets](/sdk/agent_call#per-request-secrets).

## Per-request control (SDK)

Beyond secrets, the SDK can adjust how a published agent uses its API Actions for a single request, without changing the agent definition:

* **Capability mask**: subtractively disable an action (or a whole sub-agent) for one request via `agent.disable_action("name")`. You can only disable capabilities the published version exposes, never enable disabled ones.
* **Config overlay**: toggle [flow steps](/build/agents/agent_flow) via `agent.config.system_steps.<step>`.

See [Agent Call, per-request overlays](/sdk/agent_call#per-request-overlays-agent-get).