An AI agent is only as powerful as the systems it can reach. This guide walks through every integration pattern the ApiSpi platform supports—from simple REST webhooks to complex bidirectional data pipelines—so you can connect your agents to the tools your organization already uses.

Integration Architecture Overview

ApiSpi exposes three primary integration surfaces:

Most production integrations use all three in combination. A user action in your application triggers an inbound request; the agent calls several outbound tools to fulfil the request; your application receives a webhook when the response is ready.

1. Authentication and Authorization

API Keys

All ApiSpi API calls require a bearer token in the Authorization header. Generate API keys from the dashboard under Settings → API Keys. Create separate keys for each environment (development, staging, production) and rotate them on a regular schedule—at least annually, or immediately after any suspected compromise.

Scoped Permissions

API keys support scoped permissions. A key used only by your data pipeline to read conversation logs does not need write access to agent configuration. Apply the principle of least privilege: grant each key only the permissions it genuinely needs.

Webhook Signature Verification

ApiSpi signs all outbound webhook payloads with HMAC-SHA256 using your webhook secret. Always verify the signature before processing a webhook payload. Do not process payloads from unknown sources, even if the content looks valid.

2. The Inbound API

Synchronous Requests

Use the synchronous endpoint for interactions that must complete before your application can proceed. The endpoint accepts a JSON payload containing the agent ID, the user message, optional session context, and any metadata you want attached to the interaction.

Synchronous calls block until the agent produces a response. Set your HTTP client timeout to at least 60 seconds—complex agent tasks involving multiple tool calls can take longer than typical web requests.

Asynchronous Requests

For long-running tasks or workloads where you do not need an immediate response, use the asynchronous endpoint. You receive a job ID immediately; the agent processes the request in the background and delivers the result via webhook when complete. This pattern is essential for batch processing and any interaction triggered by an automated workflow rather than a waiting user.

Streaming Responses

When building chat interfaces where perceived speed matters, use the streaming endpoint. The response is delivered as a Server-Sent Events stream, allowing your application to render tokens progressively as they are generated rather than waiting for the complete response.

3. Outbound Tools — Extending Agent Capabilities

Defining Custom Tools

Custom tools let your agent call your internal APIs. Define each tool with a name, description, and JSON Schema for its parameters. The description is critical—it is the text the model uses to decide when to call your tool. Write it precisely: describe what the tool does, when to use it, and what it returns.

Tool Endpoint Requirements

Tool endpoints must be publicly accessible HTTPS endpoints (or reachable via our VPC peering option for private network deployments). They must respond within 30 seconds. For operations that take longer, implement an async pattern: return a pending status immediately and provide a polling or webhook mechanism for the result.

Error Response Format

Return errors as JSON with a consistent structure: an error code, a human-readable message, and optional detail fields. The agent can interpret and respond to structured errors; it cannot do anything useful with an HTML error page or an empty 500 response.

Pre-Built Connectors

ApiSpi ships pre-built connectors for common enterprise tools. No custom code is required to connect your agent to Salesforce, Jira, Confluence, Slack, Microsoft Teams, Google Workspace, ServiceNow, or Zendesk. Enable a connector from the dashboard, authorize it with OAuth, and it is available to your agent as a set of pre-defined tools.

4. Webhooks and Event Streams

Configuring Webhooks

Register webhook endpoints in the dashboard under Settings → Webhooks. You can subscribe to specific event types—conversation completed, tool call failed, quality score below threshold, human escalation triggered—rather than receiving all events. Filter early to avoid processing overhead on your receiving end.

Event Payload Structure

Every webhook payload includes the event type, a timestamp, the agent ID, a conversation ID you can use for correlation, and event-specific data. Store conversation IDs in your own system from the moment a conversation starts—they are the key to reconstructing what happened from your logs and ours.

Retry and Idempotency

ApiSpi retries failed webhook deliveries with exponential backoff for up to 24 hours. Your receiving endpoint must be idempotent—processing the same event twice should produce the same outcome as processing it once. Use the event ID as an idempotency key: if you have already processed an event with that ID, skip it.

5. Session and Context Management

Session IDs

Pass a stable session ID with each request to maintain conversation continuity. The agent uses the session ID to retrieve prior turns and relevant context. Use your own user or conversation identifiers as session IDs rather than generating random values—this makes correlation between your systems and ApiSpi logs straightforward.

Context Injection

The context field in the request payload lets you inject structured data that the agent should have available but that is not part of the user's message—the current user's account tier, the page they are on, the state of an open support ticket. Keep injected context concise and relevant; extraneous data dilutes the agent's attention.

Session Expiry

Sessions expire after a configurable period of inactivity (default 30 minutes). When a session expires, the next request starts a fresh conversation. Design your application to handle this gracefully—if continuity matters, re-inject the necessary context on the new session rather than assuming the agent remembers.

6. Testing Your Integration

Sandbox Environment

Use the sandbox environment for all development and testing. The sandbox is isolated from production, uses test API keys, and will not trigger real outbound tool calls unless you explicitly configure sandbox tool endpoints. Changes to agent configuration in the sandbox do not affect production.

Replay Testing

The dashboard's replay feature lets you re-run any past conversation through the current agent configuration. Use this to verify that a prompt change does not break existing interactions before deploying to production.

Load Testing

Before a major launch, coordinate with our team to run a load test against your integration. We can help size your rate limits appropriately and identify any bottlenecks in your tool endpoints before real user traffic arrives.

Conclusion

A well-integrated agent disappears into your product—users interact with your application and the agent works behind the scenes, pulling data from your systems and taking actions on behalf of users. Getting the integration right takes upfront investment, but it is what transforms an interesting demo into a genuinely useful product.

Need help with your integration? Our solutions team offers integration workshops for enterprise customers.

Security First

Integrations that expose internal systems deserve careful security review. Read our Security and Compliance guide before moving to production.