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

# External API Request

> Make HTTP requests to external APIs and webhooks from your workflows

The External API Request tool allows Neo Agent to call external APIs, webhooks, or internal services as part of ticket processing.

## What It Does

When enabled, the agent can:

* Make GET or POST requests to configured API endpoints
* Authenticate using Bearer tokens, Basic Auth, API keys, or OAuth 2.0
* Add custom headers for API versioning or additional metadata
* Construct request bodies based on ticket context
* Process and act on API responses

<Info>
  This tool is ideal for integrating with systems Neo doesn't natively support.
</Info>

## How to Use

<Steps>
  <Step title="Add an API Configuration">
    Click "Add API Configuration" and provide:

    * **API Name**: A unique identifier (e.g., `slack_alert`, `internal_ticketing`)
    * **Endpoint URL**: The full URL to call
    * **HTTP Method**: GET or POST
  </Step>

  <Step title="Configure Authentication">
    Choose how the API authenticates requests:

    | Method                           | When to Use                                                        |
    | -------------------------------- | ------------------------------------------------------------------ |
    | **None**                         | Public endpoints or pre-authenticated URLs (webhooks)              |
    | **Bearer Token**                 | APIs that accept a static token in the Authorization header        |
    | **Basic Auth**                   | APIs requiring username/password authentication                    |
    | **API Key Header**               | APIs that expect an API key in a custom header (e.g., `x-api-key`) |
    | **OAuth 2.0 Client Credentials** | APIs requiring OAuth 2.0 token-based auth with automatic refresh   |

    <Note>
      All credentials are stored securely in Azure Key Vault and never exposed in logs or event history.
    </Note>
  </Step>

  <Step title="Define Request Body Fields (POST only)">
    For POST requests, define the fields the agent should populate:

    * **Name**: The JSON key name
    * **Type**: String, Number, or Boolean
    * **Description**: Explains what the field represents (helps the agent populate it correctly)
    * **Required**: Whether the field must be included
  </Step>

  <Step title="Add Path Parameters (if your URL has {placeholders})">
    If the **Endpoint URL** contains a `{placeholder}` segment (e.g. `.../device/{serialNumber}`), Neo fills it at call time. Add one `{name}` per dynamic path segment — the agent provides each value on every call, URL-encoded into the path. Use as many as you need: `.../device/{serialNumber}/asset/{volumeName}`. For a value that never changes, type it into the URL instead of leaving braces.
  </Step>

  <Step title="Add Custom Instructions">
    Guide the agent on when and how to use each API. Include:

    * Conditions for calling the API
    * How to map ticket data to request fields
    * What to do with the response
  </Step>
</Steps>

## Authentication Methods Explained

### API Key Header

Use this method when the API expects an API key in a custom header rather than the standard `Authorization` header.

**Configuration:**

* **Header Name**: The header to use (e.g., `x-api-key`, `api-key`, `X-API-KEY`)
* **API Key**: Your API key value

**Common APIs using this method:** Stripe, SendGrid, Twilio, many REST APIs.

### OAuth 2.0 Client Credentials

Use this method for enterprise APIs that require OAuth 2.0 authentication. Neo automatically fetches and caches access tokens, refreshing them before they expire.

**Configuration:**

* **Token Endpoint URL**: The OAuth2 token endpoint (e.g., `https://auth.example.com/oauth/token`)
* **Token Request Parameters**: Key-value pairs sent in the token request:
  * `grant_type`: Usually `client_credentials`
  * `client_id`: Your application's client ID
  * `client_secret`: Your application's client secret (mark as secret)
  * `scope`: Required scopes (if applicable)
* **Token Auth (Optional)**: Some providers require Basic Auth on the token endpoint

<Tip>
  Mark sensitive values like `client_secret` as secrets—they'll be stored in Azure Key Vault and masked in the UI.
</Tip>

## Path Parameters

For REST APIs that take a value in the URL path (not the query string or body), put a `{placeholder}` in the **Endpoint URL** and Neo substitutes it on each call.

**Example:**

* **Endpoint**: `https://api.datto.com/v1/bcdr/device/{serialNumber}`
* Neo detects `serialNumber` and asks the agent to provide it every call, URL-encoding the value into the path.
* Multiple placeholders are supported: `https://api.datto.com/v1/bcdr/device/{serialNumber}/asset/{volumeName}`

<Note>
  Any `{name}` in the endpoint is treated as a required, dynamic path parameter. For a value that never changes (e.g. a webhook trigger ID), type the real value into the URL rather than leaving braces.
</Note>

## Custom Headers

Add static headers to every request beyond authentication. Useful for:

* **API versioning**: `Api-Version: 2024-01`
* **Tenant identification**: `X-Tenant-Id: acme-corp`
* **Request tracing**: `X-Request-Source: neo-agent`

Custom headers are configured per API and sent with every request to that endpoint.

## Example: Kick-off a Rewst Workflow

<Frame>
  <img src="https://mintcdn.com/neoagent/-RhBigU9NACF-x70/images/rewst.png?fit=max&auto=format&n=-RhBigU9NACF-x70&q=85&s=f5bf6ee6771995556ccc1855c6c2ae62" alt="Rewst user onboarding" width="200" height="100" data-path="images/rewst.png" />
</Frame>

If you have a Rewst workflow that you want Neo to decide when to kick off, you can give Neo the webhook URL.

**Settings:**

* **API Name**: `rewst_user_onboarding`
* **Endpoint**: `https://engine.rewst.io/webhooks/custom/trigger/<your-trigger-id>/<your-org-id>`
* **Method**: POST
* **Auth**: (Choose your preferred authentication method)

<Note>
  The trigger and org IDs are the same on every call, so paste the real values into the URL. Only use `{placeholder}` braces for values that change per ticket (see [Path Parameters](#path-parameters)).
</Note>

**Request Body Fields (example):**

| Name                 | Type   | Description                                  | Required |
| -------------------- | ------ | -------------------------------------------- | -------- |
| `user_email`         | String | The email of the user to onboard             | Yes      |
| `user_name`          | String | The name of the user to onboard              | Yes      |
| `user_phone`         | String | The phone number of the user to onboard      | Yes      |
| `microsoft_licenses` | String | The Microsoft licenses to assign to the user | Yes      |

## Example: Slack Webhook Alert

Configure an API to send alerts to a Slack channel when high-priority tickets arrive:

**Settings:**

* **API Name**: `slack_high_priority_alert`
* **Endpoint**: `https://hooks.slack.com/services/YOUR/WEBHOOK/URL`
* **Method**: POST
* **Auth**: None (webhook URL is pre-authenticated)

**Request Body Fields:**

| Name   | Type   | Description                  | Required |
| ------ | ------ | ---------------------------- | -------- |
| `text` | String | The message to post in Slack | Yes      |

**Custom Instructions:**

```
When a ticket has priority "Critical" or "Emergency", use the
slack_high_priority_alert API to notify the team. Include the
ticket number, company name, and a brief summary of the issue.
```

## Example: Enterprise API with OAuth 2.0

Configure an API that uses OAuth 2.0 Client Credentials for authentication:

**Settings:**

* **API Name**: `crm_update_contact`
* **Endpoint**: `https://api.example.com/v1/contacts`
* **Method**: POST
* **Auth**: OAuth 2.0 Client Credentials

**OAuth 2.0 Configuration:**

* **Token Endpoint URL**: `https://auth.example.com/oauth/token`
* **Token Request Parameters**:

| Key             | Value                | Secret  |
| --------------- | -------------------- | ------- |
| `grant_type`    | `client_credentials` | No      |
| `client_id`     | `your-client-id`     | No      |
| `client_secret` | `your-client-secret` | **Yes** |
| `scope`         | `contacts.write`     | No      |

**Request Body Fields:**

| Name    | Type   | Description                      | Required |
| ------- | ------ | -------------------------------- | -------- |
| `email` | String | Contact email address            | Yes      |
| `name`  | String | Contact full name                | Yes      |
| `notes` | String | Additional notes from the ticket | No       |

<Note>
  Neo caches OAuth tokens and automatically refreshes them before expiry. You don't need to handle token management in your instructions.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive API names">
    Choose names that clearly indicate purpose: `jira_create_issue`, `pagerduty_alert`, `custom_crm_update`. The agent uses these names to decide which API to call.
  </Accordion>

  <Accordion title="Write detailed field descriptions">
    The agent relies on field descriptions to map ticket data correctly. Instead of "The message", write "A summary of the ticket issue including the error message and affected user".
  </Accordion>

  <Accordion title="Test with approval enabled first">
    Always enable technician approval when configuring new APIs. Review the requests the agent wants to make before allowing autonomous operation.
  </Accordion>

  <Accordion title="Handle errors gracefully">
    Add custom instructions for what the agent should do if the API returns an error—retry, escalate, or add a note to the ticket.
  </Accordion>

  <Accordion title="Choose the right authentication method">
    * **Public webhooks** → None
    * **Static API key in header** → API Key Header
    * **Static token** → Bearer Token
    * **Username/password** → Basic Auth
    * **Enterprise APIs with token refresh** → OAuth 2.0 Client Credentials
  </Accordion>

  <Accordion title="Test before going live">
    Use the **Test** button (▶) on each API configuration to verify connectivity and authentication before enabling the workflow. This catches credential issues early.
  </Accordion>

  <Accordion title="Use custom headers for API versioning">
    Pin your integration to a specific API version using custom headers (e.g., `Api-Version: 2024-01`). This prevents breaking changes when the API provider releases updates.
  </Accordion>
</AccordionGroup>