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:

Navigate to Settings → API Keys
Click Create API Key
Optionally give the key a descriptive label (e.g., “CRM Integration”, “Mobile App”, “Zapier Webhook”)
The key is displayed immediately in the list
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:

Navigate to Settings → API Keys
Click the trash icon next to the key you want to revoke
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:

Authorization: Bearer YOUR_API_KEY

Example request using curl:

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):

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:

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:

AI Agents

Create, update, query, and manage your AI Employee agents programmatically. Control system prompts, model selection, and behavior configuration.

Datastores

Manage your knowledge repositories. Upload files, upsert documents, and control the information your agents have access to.

Datasources

Connect websites, files, and external services to your datastores. Trigger re-indexing and manage source configurations.

Conversations & Logs

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.

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.

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.

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:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 143
  }
}

Error responses include a descriptive message:

{
  "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.

# .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 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:

Verify the key is being sent in the correct header format: Authorization: Bearer YOUR_KEY
Check for extra spaces or line breaks around the key value
Confirm the key has not been revoked — check the API Keys page in your dashboard
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:

Verify your account role has permission to perform the action (e.g., only Admins can delete agents via API)
Confirm the resource belongs to the same organization as your API key
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:

Implement exponential backoff — wait and retry after the time specified in the Retry-After header
Reduce request frequency by batching operations
Check if your integration has a loop that’s making unintended rapid-fire requests
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:

Check the API Keys page — the key may have been revoked by another Admin in your organization
Verify no one rotated the key as part of a security procedure
Generate a new key and update the affected integration
Contact 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:

API Reference

View the complete API reference with interactive examples for every endpoint.

Support

Need help with API integration? Contact ZappWay Support:

Email: 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

Primeiros Passos

Workspace

Automação ZappFlux

API Keys

API Keys

Overview

Managing API Keys

Generating a New Key

Viewing Existing Keys

Revoking a Key

Authentication

Base URL

API Modules

AI Agents

Datastores

Datasources

Conversations & Logs

Common Use Cases

Chat Integration (Custom Application)

Datastore Sync (Automated Knowledge Updates)

Lead Export (CRM Automation)

Response Format

HTTP Status Codes

Rate Limits

Security Best Practices

Troubleshooting

Issue: `401 Unauthorized` Error

Issue: `403 Forbidden` Error

Issue: `429 Too Many Requests`

Issue: Key Stopped Working After Working Previously

Full API Reference

API Reference

Support

Primeiros Passos

Workspace

Automação ZappFlux

​API Keys

​Overview

​Managing API Keys

​Generating a New Key

​Viewing Existing Keys

​Revoking a Key

​Authentication

​Base URL

​API Modules

AI Agents

Datastores

Datasources

Conversations & Logs

​Common Use Cases

​Chat Integration (Custom Application)

​Datastore Sync (Automated Knowledge Updates)

​Lead Export (CRM Automation)

​Response Format

​HTTP Status Codes

​Rate Limits

​Security Best Practices

​Troubleshooting

​Issue: 401 Unauthorized Error

​Issue: 403 Forbidden Error

​Issue: 429 Too Many Requests

​Issue: Key Stopped Working After Working Previously

​Full API Reference

API Reference

​Support

API Keys

Overview

Managing API Keys

Generating a New Key

Viewing Existing Keys

Revoking a Key

Authentication

Base URL

API Modules

Common Use Cases

Chat Integration (Custom Application)

Datastore Sync (Automated Knowledge Updates)

Lead Export (CRM Automation)

Response Format

HTTP Status Codes

Rate Limits

Security Best Practices

Troubleshooting

Issue: `401 Unauthorized` Error

Issue: `403 Forbidden` Error

Issue: `429 Too Many Requests`

Issue: Key Stopped Working After Working Previously

Full API Reference

Support