Public API

Base URL

The Public API base URL is https://app.chatty.net/v1. All Public API endpoint paths in this reference are relative to this base URL. Keep its /v1 prefix and append the path directly; do not insert an extra /api or /chat. For example, the /settings route is reached at the base URL followed by /settings.

The Chat Conversations API is a separate surface with /chat paths. The two APIs use the same API-key header but have separate rate-limit budgets and legacy-key rules.

Make your first request

Create a key with settings:read, copy it once, and keep it on your server. Send X-Api-Key on every request. For JSON writes, also send Content-Type: application/json.

curl 'https://app.chatty.net/v1/' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'X-Api-Version: 2026-08-17'

GET / requires settings:read (or an implied permission). It returns the selected version:

{
  "data": {
    "version": "2026-08-17"
  }
}

Without the header, authentication returns 401 UNAUTHENTICATED. An unknown or revoked key returns 401 INVALID_API_KEY. A key without the required scope, including a legacy key with no scopes field, returns 403 FORBIDDEN:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key is missing the 'settings:read' scope"
  }
}

Choose a version

The API selects the version in this order:

1. Your X-Api-Version request header.
2. The version pinned to your API key.
3. The floor version, 2026-08-17.

The current version is 2026-08-17. The header must be a real calendar date in YYYY-MM-DD format; malformed dates return 400 INVALID_API_VERSION. Date validation does not imply that a later date enables new endpoints. GET / reports the selected value; there is no separate version response header.

Permissions and feature availability

An API key identifies one shop. Do not supply a shop ID to switch stores. Read the complete scope catalog before creating the key.

Read setup status

GET /setup/status requires setup:read. It has no request body or query parameters.

curl 'https://app.chatty.net/v1/setup/status' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'X-Api-Version: 2026-08-17'

Example response; counts depend on the shop:

{
  "data": {
    "entries": 3,
    "scenarios": 1,
    "skillsOn": 2,
    "skillsTotal": 10,
    "state": "setup",
    "steps": {
      "trainingData": true,
      "instructions": true,
      "skills": true,
      "scenarios": true,
      "testAi": false
    }
  }
}

entries counts active, inactive and draft knowledge entries. scenarios counts active scenarios. skillsOn and skillsTotal describe the Skills checklist. state is empty when no step is complete, live when every step is complete and AI is enabled, and setup otherwise.

This endpoint can return 401 UNAUTHENTICATED, 401 INVALID_API_KEY, 403 FORBIDDEN, 400 INVALID_API_VERSION, 429 RATE_LIMITED, or 500 INTERNAL_ERROR. Errors use the same error.code and error.message envelope as GET /.

Limits and errors

The Public API allows 120 requests per minute per key and 300 per minute per source IP, including unauthenticated attempts in the IP budget. POST /ai/ask has an additional 20 requests per minute per key budget. Read Errors and rate limits for response headers, backoff and AI quota errors.

Resource references

The same underlying operations are available through MCP, except HTTP version discovery (GET /). Tool availability and action permissions depend on whether you use an API key or OAuth. An OAuth grant does not authenticate a direct REST request. See Quick Reference for the endpoint list.