Skip to main content

API Overview

Base URL and Versioning​

  • Base URL: https://chattz.net/api
  • Versioned endpoints: https://chattz.net/api/v1/...

Example:

https://chattz.net/api/v1/users/data?id=42

Authentication​

Most endpoints require the community API key.

Accepted API key inputs:

  • X-Chattz-Api-Key: <key> (preferred)
  • X-Api-Key: <key>
  • Authorization: Bearer <key>
  • Query string: ?api_key=<key>

Community scope rules:

  • Community endpoints validate that the API key belongs to the same community as the target channel, thread, or message.
  • GET /api/v1/users/data is public and does not require a key.

Authentication Examples​

curl "https://chattz.net/api/v1/channels/123456789012/messages" \
  -H "X-Chattz-Api-Key: YOUR_KEY"
curl "https://chattz.net/api/v1/channels/123456789012/messages" \
  -H "X-Api-Key: YOUR_KEY"
curl "https://chattz.net/api/v1/channels/123456789012/messages" \
  -H "Authorization: Bearer YOUR_KEY"
curl "https://chattz.net/api/v1/channels/123456789012/messages?api_key=YOUR_KEY"

Rate Limits​

Default per endpoint:

  • 5 requests per 1 second

When rate-limited:

  • HTTP 429
  • code: "chattz_api_rate_limited"
  • meta.retry_after contains retry timing details

Response Format​

Success​

{
  "success": true,
  "code": "some_code",
  "...": "payload fields"
}

Error​

{
  "success": false,
  "code": "error_code",
  "message": "Human readable message",
  "meta": {}
}

Common Error Cases​

  • 400: Invalid IDs, invalid pagination, invalid or missing JSON fields
  • 401: Missing or invalid API key
  • 403: Valid key but not allowed for target community
  • 404: User, channel, thread, or message not found
  • 405: HTTP method not allowed
  • 429: Rate limit exceeded
  • 500 / 503: Internal or storage availability failure

Endpoint Index​