REST API Overview

The ChatSpark REST API powers server-side integrations for chat, agents, conversations, and more. All requests use JSON and standard HTTP conventions.

Base URL

All API requests must be sent to this base URL. Use HTTPS only.

text

https://chatspark.io/api/v1

Versioning

The API is versioned via the URL path. The current version is v1. When we introduce breaking changes, we will release a new version (e.g. v2) and maintain backward compatibility for at least 12 months.

text

https://chatspark.io/api/v1/agents
https://chatspark.io/api/v1/agents/{id}/chat
https://chatspark.io/api/v1/health

Request & Response Format

All request bodies and responses use application/json. Include Content-Type: application/json for POST, PATCH, and PUT requests.

Header	Required	Description
`Content-Type`	POST/PATCH/PUT	Must be `application/json`
`Authorization`	All (except health)	`Bearer cs_live_...` or `Bearer cs_test_...`
`x-request-id`	Optional	Client-supplied request ID for idempotency or tracing
`Idempotency-Key`	Create operations	Unique key to ensure create requests are idempotent

Standard Response Envelope

Successful responses return the requested data directly. Error responses follow a consistent structure.

Success (2xx)

json

{
  "agents": [...],
  "nextCursor": "abc123"
}

Error (4xx, 5xx)

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "message is required",
    "details": { "field": "value" }
  }
}

All responses include an x-request-id header. Use it when contacting support.

Quick Example

bash

curl -X POST https://chatspark.io/api/v1/agents/123/chat \
  -H "Authorization: Bearer cs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!"}'

Identity Verification

Health