Connect your REST API to Crow by uploading an OpenAPI (Swagger) specification. This allows your AI agent to call your API endpoints to help users.
What is OpenAPI?
OpenAPI is a standard format for describing REST APIs. If you have an API, you likely already have an OpenAPI spec (also known as a Swagger spec). It’s typically a .json or .yaml file that describes your endpoints, parameters, and responses.
Setting Up OpenAPI Integration
Before uploading your spec, configure how Crow should connect to your API:
Base URL
Enter the base URL of your API:
https://api.yourcompany.com/v1
| Type | Description | Use When |
|---|
| None | No authentication | Public APIs |
| API Key | Custom header with secret key | Most private APIs |
| Bearer Token | Authorization header with token | OAuth/JWT APIs |
| JWT Forward | Forward user’s identity token | User-specific operations |
- Enter the header name (e.g.,
X-API-Key)
- Enter your secret API key
Bearer Token
- Enter your bearer token value
JWT Forward
JWT Forward only works for authenticated users. Anonymous users won’t have a token to forward.
Step 3: Upload OpenAPI Spec
Drag and drop or click to upload your OpenAPI specification file (.json or .yaml).
After upload, you’ll see:
- Confirmation that the spec was parsed successfully
- Number of tools (operations) discovered
- Link to configure which tools to enable
After uploading your spec, go to Actions > API Tools to select which operations your agent can use.
You don’t need to enable every endpoint. Only enable operations that are relevant to customer support scenarios.
Authentication Methods Explained
API Key
Adds a custom header to every request:
X-API-Key: your-secret-key
Bearer Token
Adds an Authorization header:
Authorization: Bearer your-token
JWT Forward
Forwards the user’s identity token from your widget:
Authorization: Bearer <user's-jwt-token>
- You must implement Identity Verification
- Your API must validate the same JWT tokens
- Anonymous users cannot use JWT-forwarded operations
Example OpenAPI Spec
Here’s a minimal example of an OpenAPI spec that defines an order lookup endpoint:
openapi: 3.0.0
info:
title: My Company API
version: 1.0.0
servers:
- url: https://api.mycompany.com/v1
paths:
/orders/{orderId}:
get:
operationId: getOrder
summary: Get order details
description: Retrieve details about a specific order
parameters:
- name: orderId
in: path
required: true
schema:
type: string
description: The order ID to look up
responses:
'200':
description: Order details
content:
application/json:
schema:
type: object
properties:
id:
type: string
status:
type: string
total:
type: number
Best Practices
Write Good Descriptions
The summary and description fields help your agent understand when to use each endpoint. Be descriptive:
summary: Get order details
description: Retrieve details about a specific order including status, items, shipping info, and total cost
Use Clear Operation IDs
The operationId becomes the tool name your agent sees. Use descriptive names:
- Good:
getOrderStatus, createSupportTicket
- Bad:
get1, post_endpoint
Limit Scope
Don’t expose sensitive or destructive operations. Your agent doesn’t need access to deleteUser or resetDatabase.
Test in Sandbox
After setup, test in the Sandbox to ensure your agent can successfully call your API.
Troubleshooting
Spec Won’t Upload
- Ensure the file is valid JSON or YAML
- Validate your spec at editor.swagger.io
- Check for syntax errors
API Calls Failing
- Verify the base URL is correct and accessible
- Check authentication credentials
- Ensure the API is reachable from Crow’s servers
Agent Not Using API
- Enable the tools in Actions > API Tools
- Test with specific questions that should trigger API calls
- Check that the tool descriptions match user queries
Need Help?
