> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Keys
> Generate and manage API keys to integrate ZappWay programmatically with your own systems, applications, and backend services.
# API Keys
## Overview
**API Keys** give your external systems secure, programmatic access to the ZappWay platform. With an API key, you can automate agent interactions, manage datastores, query contact data, retrieve conversation logs, and much more — all without touching the dashboard manually.
**To access API Keys:**
```
ZappWay Dashboard
└── Sidebar Menu → Settings → API Keys
├── Active Keys (list, copy, revoke)
└── Create API Key
```
**Common use cases:**
* Embedding ZappWay's AI into your own custom application or mobile app
* Syncing your internal databases with ZappWay datastores automatically
* Exporting leads and conversation logs to your CRM in real time
* Triggering agent queries from your own backend workflows
***
## Managing API Keys
### Generating a New Key
ZappWay generates cryptographically secure, random API keys. To create one:
1. Navigate to **Settings → API Keys**
2. Click **Create API Key**
3. Optionally give the key a descriptive label (e.g., "CRM Integration", "Mobile App", "Zapier Webhook")
4. The key is displayed immediately in the list
5. Click the **copy icon** to save it to your clipboard
**Treat your API key like a password.** It grants full programmatic access to your ZappWay organization. Never expose it in client-side code, public repositories, browser JavaScript, or any environment accessible to end users. Store it securely using environment variables or a secrets manager.
### Viewing Existing Keys
The API Keys page lists all active keys associated with your organization. For security, **the full key value is only shown once** — immediately after creation. After that, only the last few characters are visible for identification purposes.
If you lose a key, you cannot recover it. You must revoke it and generate a new one.
### Revoking a Key
To permanently invalidate an API key:
1. Navigate to **Settings → API Keys**
2. Click the **trash icon** next to the key you want to revoke
3. Confirm the deletion in the dialog
**What happens after revocation:**
* The key stops working **immediately**
* Any service or integration using that key will begin failing with `401 Unauthorized` errors
* Revocation is permanent and cannot be undone
If you suspect a key has been compromised, revoke it immediately and generate a replacement. Update all integrations using the old key before the new one is deployed.
***
## Authentication
All API requests to ZappWay must include your API key in the `Authorization` header using Bearer token format:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
**Example request using curl:**
```bash theme={null}
curl -X GET https://app.zappway.ai/api/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
**Example request using JavaScript (Node.js):**
```javascript theme={null}
const response = await fetch('https://app.zappway.ai/api/v1/agents', {
method: 'GET',
headers: {
'Authorization': `Bearer ${process.env.ZAPPWAY_API_KEY}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
```
**Example request using Python:**
```python theme={null}
import os
import requests
headers = {
"Authorization": f"Bearer {os.environ['ZAPPWAY_API_KEY']}",
"Content-Type": "application/json"
}
response = requests.get("https://app.zappway.ai/api/v1/agents", headers=headers)
data = response.json()
```
***
## Base URL
All API endpoints are available under the following base URL:
```
https://app.zappway.ai/api
```
Versioned endpoints (recommended for production integrations):
```
https://app.zappway.ai/api/v1
```
***
## API Modules
ZappWay's REST API is organized into modules, each corresponding to a core platform feature. Explore the full reference documentation for each:
Create, update, query, and manage your AI Employee agents programmatically. Control system prompts, model selection, and behavior configuration.
Manage your knowledge repositories. Upload files, upsert documents, and control the information your agents have access to.
Connect websites, files, and external services to your datastores. Trigger re-indexing and manage source configurations.
Send messages to your agents, retrieve conversation history, and monitor human intervention events via API.
***
## Common Use Cases
### Chat Integration (Custom Application)
Embed ZappWay's AI engine into your own web app, mobile app, or internal tool. Use the agent query endpoint to send user messages and receive AI responses without the ZappWay UI.
```bash theme={null}
POST https://app.zappway.ai/api/v1/agents/{agentId}/query
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"query": "What is your return policy?",
"conversationId": "optional-session-id-for-continuity"
}
```
### Datastore Sync (Automated Knowledge Updates)
Keep your AI agent's knowledge base up to date by programmatically upserting documents whenever your internal data changes — from your CMS, database, or any content pipeline.
```bash theme={null}
POST https://app.zappway.ai/api/v1/datastores/{datastoreId}/upsert
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"documents": [
{
"id": "doc-123",
"text": "Updated product description...",
"metadata": { "source": "cms", "updated_at": "2025-01-15" }
}
]
}
```
### Lead Export (CRM Automation)
Pull conversation logs and contact data captured by your agents and push them directly into your CRM, email marketing platform, or data warehouse.
```bash theme={null}
GET https://app.zappway.ai/api/v1/agents/{agentId}/conversations?limit=50&after=2025-01-01
Authorization: Bearer YOUR_API_KEY
```
***
## Response Format
All API responses return JSON. A standard successful response follows this structure:
```json theme={null}
{
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 143
}
}
```
Error responses include a descriptive message:
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired API key."
}
}
```
### HTTP Status Codes
| Code | Meaning |
| --------------------------- | -------------------------------------------------- |
| `200 OK` | Request succeeded |
| `201 Created` | Resource created successfully |
| `400 Bad Request` | Invalid parameters — check your request body |
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | Valid key but insufficient permissions |
| `404 Not Found` | The requested resource does not exist |
| `429 Too Many Requests` | Rate limit exceeded — slow down requests |
| `500 Internal Server Error` | Server-side error — contact support if it persists |
***
## Rate Limits
API requests are subject to rate limiting to ensure platform stability for all users.
| Plan | Rate Limit |
| -------------- | --------------------------------- |
| **Free** | 60 requests / minute |
| **Pro** | 300 requests / minute |
| **Enterprise** | Custom — configured per agreement |
When a rate limit is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying.
**Best practices to avoid rate limiting:**
* Batch multiple operations into single requests where the API supports it
* Implement exponential backoff on `429` responses
* Cache responses locally when the same data is requested repeatedly
***
## Security Best Practices
**1. Use Environment Variables**
Never hardcode API keys in your source code. Store them as environment variables and load them at runtime.
```bash theme={null}
# .env file (never commit this to version control)
ZAPPWAY_API_KEY=your_key_here
```
**2. Restrict Key Usage by Service**
Create a separate API key for each integration or service (e.g., one for your CRM sync, one for your mobile app). This way, if one key is compromised, you can revoke it without affecting other integrations.
**3. Rotate Keys Periodically**
Rotate API keys every 90 days as a security hygiene practice. Generate a new key, update your integrations, and revoke the old key only after confirming the new one works.
**4. Monitor for Unauthorized Usage**
Regularly check your API logs for unexpected activity — unusual request volumes, requests from unexpected IP addresses, or errors on endpoints you're not using. Contact [support@zappway.ai](mailto:support@zappway.ai) if you detect suspicious behavior.
**5. Never Expose Keys in Frontend Code**
API keys must only be used server-side. If your use case requires client-side AI interaction, proxy requests through your own backend server that holds the key securely.
***
## Troubleshooting
### Issue: `401 Unauthorized` Error
**Symptoms:**
* All API requests return `401` regardless of endpoint
**Solutions:**
1. Verify the key is being sent in the correct header format: `Authorization: Bearer YOUR_KEY`
2. Check for extra spaces or line breaks around the key value
3. Confirm the key has not been revoked — check the **API Keys** page in your dashboard
4. Generate a new key and test with it directly to rule out a corrupted key
### Issue: `403 Forbidden` Error
**Symptoms:**
* Request is authenticated but returns `403` on specific endpoints
**Solutions:**
1. Verify your account role has permission to perform the action (e.g., only Admins can delete agents via API)
2. Confirm the resource belongs to the same organization as your API key
3. Check if the endpoint requires a specific plan tier — some endpoints are Pro or Enterprise only
### Issue: `429 Too Many Requests`
**Symptoms:**
* Requests start failing during high-volume automation jobs
**Solutions:**
1. Implement exponential backoff — wait and retry after the time specified in the `Retry-After` header
2. Reduce request frequency by batching operations
3. Check if your integration has a loop that's making unintended rapid-fire requests
4. Upgrade your plan for higher rate limits if your use case legitimately requires more throughput
### Issue: Key Stopped Working After Working Previously
**Symptoms:**
* An integration that was working starts returning `401` errors
**Solutions:**
1. Check the API Keys page — the key may have been revoked by another Admin in your organization
2. Verify no one rotated the key as part of a security procedure
3. Generate a new key and update the affected integration
4. Contact [support@zappway.ai](mailto:support@zappway.ai) if you need help identifying who revoked the key
***
## Full API Reference
For detailed documentation on every endpoint, including parameters, request bodies, and example responses:
View the complete API reference with interactive examples for every endpoint.
***
## Support
Need help with API integration?
**Contact ZappWay Support:**
* Email: [support@zappway.ai](mailto:support@zappway.ai)
* Subject line: Include "API" for faster routing
**Provide These Details When Reporting Issues:**
* The endpoint you are calling (method + URL)
* The HTTP status code and error message returned
* A sanitized version of your request (remove the API key before sharing)
* Your programming language and HTTP client/library
***
**Last Updated:** March 2026
**Platform:** ZappWay Dashboard — API Keys
***