Public API v2

The ChatNorris API v2 lets you integrate and automate your AI agent platform from any external application. You can manage agents, send messages, read conversations, leads and more. Base URL:

https://app.chatnorris.ai/api/v2

API access is available on the Standard and Premium plans. To enable it, you need an active API key. On the Free plan, the API keys section appears locked — if you try to create a key, you’re redirected to the plans page.

Generate an API key

Sign in to your account and go to Settings → API Keys.
Enter a descriptive name for the key (e.g. “Production” or “Zapier”).
Click New key.
Copy the generated key — it’s shown only once. Store it somewhere safe.

If you lose the key, you have to delete it and create a new one. Each organization can have up to 10 API keys.

Each key has full API access on behalf of your organization. Treat it like a password and don’t share it or expose it in a website’s code.

The API v2 is also the foundation of the automation integrations listed on the Integrations page: Zapier (public app, no credentials of your own) and the n8n community node (n8n-nodes-chatnorris, open source). Both connect with your API key and the endpoints in this reference — see Zapier and n8n.

Authentication

Every request must include the API key in the Authorization header as a Bearer token:

Authorization: Bearer <your_api_key>

Requests without a key or with an invalid key receive 401 Unauthorized. The X-API-Key header isn’t accepted.

Permissions (scopes)

Each endpoint requires a permission (scope). The API keys you create in Settings → API Keys always have full access (*), so they can use every endpoint in this reference: you don’t have to choose permissions when you create the key. For reference, this is the permission each group of endpoints requires:

Scope	Access
`chatbots:read`	List and get agents and knowledge sources
`chatbots:write`	Create, update and delete agents and sources
`chat:write`	Send messages through an agent and upload attachments
`conversations:read`	List and get conversations and messages
`leads:read`	List and get leads
`channels:read`	List connected channels
`*`	Full access to all scopes

The project, members and usage endpoints don’t require a specific scope — only valid authentication.

Response format

All responses are JSON with the following structure:

Success

{
  "status": "success",
  "data": { ... }
}

Success with pagination

{
  "status": "success",
  "data": { ... },
  "pages": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 98
  }
}

Error

{
  "status": "error",
  "message": "Error description",
  "code": "ERROR_CODE"
}

Pagination

List endpoints support pagination through query params:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (starts at 1)
`per_page`	integer	`25`	Results per page (maximum `100`)

Error codes

HTTP code	Code	Description
400	`INVALID_INPUT`	The request body fails validation
401	`AUTH_REQUIRED`	The `Authorization` header is missing
401	`INVALID_API_KEY`	The API key doesn’t exist, was deleted, or has an invalid format
401	`API_KEY_EXPIRED`	The API key has expired
403	`ORG_SUSPENDED`	The organization that owns the key isn’t active
403	`FEATURE_NOT_ALLOWED`	Your organization’s plan doesn’t include API access (for example, the Free plan)
403	`INSUFFICIENT_SCOPE`	The key doesn’t have the scope required for this endpoint
403	`PLAN_LIMIT_REACHED`	A plan limit was reached (agents, credits, etc.)
404	`NOT_FOUND`	The requested resource doesn’t exist or doesn’t belong to your organization
429	`RATE_LIMIT_EXCEEDED`	The requests-per-minute limit was exceeded
429	`PLAN_LIMIT_REACHED`	The plan’s AI credit limit was reached
500	`INTERNAL_ERROR`	Internal server error

Rate limiting

The API allows 300 requests per minute per API key. When the limit is exceeded, the response includes the Retry-After header with the number of seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 15

{
  "status": "error",
  "message": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED"
}

Getting started

AI agents

Web widget

Channels

Conversations and live chat

Campaigns

Leads and analytics

Team

Account and settings

Billing

Troubleshooting

FAQ

Glossary

Public API v2

Introduction to the API

Public API v2

Generate an API key

Authentication

Permissions (scopes)

Response format

Success

Error

Error codes

Rate limiting

​Public API v2

​Generate an API key

​Authentication

​Permissions (scopes)

​Response format

​Success

​Success with pagination

​Error

​Pagination

​Error codes

​Rate limiting

Public API v2

Generate an API key

Authentication

Permissions (scopes)

Response format

Success

Success with pagination

Error

Pagination

Error codes

Rate limiting