Skip to main content
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
This tool is ideal for integrating with systems Neo doesn’t natively support.

​
How to Use

1

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
2

Configure Authentication

Choose how the API authenticates requests:
All credentials are stored securely in Azure Key Vault and never exposed in logs or event history.
3

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
4

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.
5

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

​
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
Mark sensitive values like client_secret as secrets—they’ll be stored in Azure Key Vault and masked in the UI.

​
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}
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.

​
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

Rewst user onboarding
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)
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).
Request Body Fields (example):

​
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: Custom Instructions:

​
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:
Request Body Fields:
Neo caches OAuth tokens and automatically refreshes them before expiry. You don’t need to handle token management in your instructions.

​
Best Practices

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.
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”.
Always enable technician approval when configuring new APIs. Review the requests the agent wants to make before allowing autonomous operation.
Add custom instructions for what the agent should do if the API returns an error—retry, escalate, or add a note to the ticket.
  • 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
Use the Test button (▶) on each API configuration to verify connectivity and authentication before enabling the workflow. This catches credential issues early.
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.