Authentication

All requests to /v1/ endpoints require a valid Bearer token in the Authorization header.

Supported Bearer Tokens

The ChatATP Studio API supports two types of Bearer tokens:

Token Type	Prefix	Format / Source	When to Use
Developer API Key	`chatatp_sk_`	Generated in the ChatATP Studio dashboard (Developer → API keys)	Backend servers, direct integrations, and automated pipelines
OAuth Access Token	`cat_access_`	Returned as `access_token` from `POST /oauth/token/`	3rd-party user-facing apps where users authorize access via OAuth 2.1

Header Format

Regardless of whether you use an API Key or an OAuth Access Token, use the standard Bearer authentication scheme:

Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json

Direct Developer API Key Example

Authorization: Bearer chatatp_sk_live_abc123...
Content-Type: application/json

OAuth 2.1 Access Token Example

Authorization: Bearer cat_access_def456...
Content-Type: application/json

What do I put in the Bearer token for the OAuth part?When an OAuth authorization code is exchanged via POST /oauth/token/, the response body contains:

{
  "access_token": "cat_access_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cat_refresh_...",
  "scope": "agents:read messages:send"
}

Pass the value of access_token (cat_access_...) directly in your request’s Authorization: Bearer cat_access_... header.

Never log, commit, or expose API keys or client secrets in client-side code. Public OAuth clients must authenticate with PKCE instead of client secrets.

Code Examples

cURL

# Using Developer API Key
curl https://chatatp-agent-builder-backend.onrender.com/v1/agents/ \
  -H "Authorization: Bearer $CHATATP_API_KEY" \
  -H "Content-Type: application/json"

# Using OAuth Access Token
curl https://chatatp-agent-builder-backend.onrender.com/v1/agents/ \
  -H "Authorization: Bearer $CHATATP_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

JavaScript / TypeScript (fetch)

const res = await fetch("https://chatatp-agent-builder-backend.onrender.com/v1/agents/", {
  headers: {
    Authorization: `Bearer ${token}`, // Pass either chatatp_sk_... or cat_access_...
    "Content-Type": "application/json",
  },
});

Python (httpx)

import os, httpx

headers = {
    "Authorization": f"Bearer {token}",  # Pass either chatatp_sk_... or cat_access_...
    "Content-Type": "application/json",
}
async with httpx.AsyncClient(base_url="https://chatatp-agent-builder-backend.onrender.com") as client:
    r = await client.get("/v1/agents/", headers=headers)
    r.raise_for_status()

Errors

Status	SDK exception	Meaning
`400`	`ValidationError`	Invalid body or query
`401`	`AuthenticationError`	Missing, invalid, or expired key/token
`403`	`PermissionError`	Token does not have permission/scope for the resource
`404`	`NotFoundError`	Resource does not exist
`429`	`RateLimitError`	Too many requests
`5xx`	`ServerError`	Upstream failure

Error bodies include a human-readable message. Successful responses may include x-request-id, which the SDKs expose as requestId / request_id.

Overview

OAuth 2.1

Agents

Conversations

Messages

Usage

Knowledge Bases

Agent Users

Memories

Automations

Schedules

Supported Bearer Tokens

Header Format

Direct Developer API Key Example

OAuth 2.1 Access Token Example

Code Examples

cURL

JavaScript / TypeScript (fetch)

Python (httpx)

Errors

​Supported Bearer Tokens

​Header Format

​Direct Developer API Key Example

​OAuth 2.1 Access Token Example

​Code Examples

​cURL

​JavaScript / TypeScript (fetch)

​Python (httpx)

​Errors

Supported Bearer Tokens

Header Format

Direct Developer API Key Example

OAuth 2.1 Access Token Example

Code Examples

cURL

JavaScript / TypeScript (fetch)

Python (httpx)

Errors