External API Connection

The External API connection lets you integrate any REST API with OpsTower. Instead of waiting for a dedicated integration, you can point an agent at any HTTP endpoint — an internal microservice, a third-party SaaS API, a partner data feed — and give it the credentials to authenticate automatically.

When to Use This

Use the External API connection when:

• You rely on a service OpsTower does not have a dedicated integration for yet
• You have internal APIs or microservices your agents should be able to query
• You want to pull data from a third-party REST API that uses standard authentication

Authentication Methods

The External API connection supports five authentication methods:

Method	How It Works
Bearer Token	Sends an Authorization: Bearer <token> header on every request
API Key Header	Sends a custom header (e.g., X-API-Key: <value>) on every request
Basic Auth	Sends an Authorization: Basic <base64> header on every request
Query Parameter	Appends a key-value pair to the URL query string on every request
No Auth	No credentials attached — for open or internally-networked endpoints

All credentials are encrypted at rest using AES-GCM. Agents never see raw secrets — authentication is injected automatically before each request.

Setting Up the Connection in OpsTower

1. In OpsTower, navigate to Connections in the sidebar.
2. Click Add Connection and select External API.
3. Enter a Label (optional) — a friendly name like “Internal Billing API” or “Weather Service.”
4. Enter the Base URL — the root URL of the API (e.g., https://api.example.com/v1). All agent requests will be relative to this URL.
5. Choose the Authentication Type and fill in the required credentials.
6. Optionally provide:
   • API Documentation URL — a link to the API docs or OpenAPI spec. Agents can fetch this at runtime to learn the available endpoints.
   • API Description — free-text context about what the API does and which endpoints are useful. This is injected into the agent’s context so it knows how to use the API.
7. Click Test Connection to verify the base URL is reachable with the provided credentials.
8. Click Save to create the connection.

What Agents Can Do

Once connected and enabled on an agent, the agent can make HTTP requests to the API:

• GET, POST, PUT, PATCH, DELETE — all standard HTTP methods are supported
• Path construction — the agent appends a path to your base URL (e.g., /users, /orders/123)
• Query parameters — the agent can add query string parameters
• Request bodies — the agent can send JSON or other content types for POST/PUT/PATCH
• Custom headers — the agent can add headers (security-sensitive headers like Authorization and Cookie are blocked to prevent overriding configured credentials)

Responses are returned as text and capped at 8KB to keep agent context manageable. A 15-second timeout is enforced on all requests.

Providing API Context

The more context you give, the better your agents will use the API. There are two optional fields that significantly improve agent performance:

API Documentation URL

If the API has documentation or an OpenAPI/Swagger spec available at a URL, provide it. Agents with web tools enabled can fetch the docs at runtime to discover endpoints, required parameters, and response schemas.

API Description

Write a plain-text description of the API. Include:

• What the API does and what data it provides
• Key endpoints the agent should know about (e.g., GET /users returns a list of users)
• Important notes about pagination, rate limits, or response formats
• Any domain-specific terminology the agent should understand

This text is injected directly into the agent’s tool description, so keep it concise and actionable.

Security

The External API connection includes several safety measures:

• SSRF protection — all constructed URLs are validated to stay on the same origin as the configured base URL, preventing path-based redirect attacks
• Header sanitization — agents cannot override authentication headers (Authorization, Cookie) or inject dangerous headers (Host, Transfer-Encoding)
• Credential encryption — all secrets are encrypted at rest with AES-GCM
• Request timeout — a 15-second timeout prevents hanging connections
• Response cap — responses are truncated at 8KB to avoid context overflow

Use Cases

• Internal tools: Connect your admin API so agents can look up user accounts, check feature flags, or pull internal metrics
• Partner APIs: Let agents query a partner data feed for pricing, inventory, or status checks
• SaaS platforms: Connect any SaaS tool with a REST API — CRM, helpdesk, shipping provider, etc.
• Webhook receivers: Point agents at status endpoints for CI/CD, deployment pipelines, or health checks

Agent Type Compatibility

The External API connection is available to all agent types: Analyst, Debugger, Product Manager, and Custom.

Troubleshooting

• Connection test fails: Verify the base URL is correct and reachable. Check that the authentication credentials are valid. The test sends a basic request to the base URL.
• Agent gets 401/403 errors: The credentials may have expired or lack the required permissions. Update the connection with fresh credentials.
• Responses are truncated: The 8KB response cap keeps agent context manageable. If the API returns large payloads, guide the agent (via the API description field) to use query parameters or endpoints that return smaller result sets.
• Requests time out: The API must respond within 15 seconds. If the endpoint is slow, consider pointing agents at a faster or cached version.