Build with the AHS interfaces available today
Use the implemented REST contract and restricted web Widget safely. This documentation is explicit about what is available now and what remains planned.
Quick start
Confirm the local API in one request
The public system ping is the smallest safe request for verifying that your local gateway and required dependencies are ready.
- 1Start the local API and its required dependencies.
- 2Send the request from your terminal.
- 3Expect a 200 response with the standard data envelope.
curl --request GET \
+ --url http://localhost:8080/v1/system/ping \
+ --header 'Accept: application/json'Authentication boundaries
Choose credentials by endpoint, not by convenience
Every operation in the reference declares its actual security scheme. Credentials remain scoped to one purpose and must never be exchanged for another.
Management session
Dashboard and management routes use the secure ahs_session cookie. State-changing browser requests also require the paired X-CSRF-Token header. These routes are not a server-key API.
Publishable Widget key
Widget routes accept X-AHS-Publishable-Key only from an allowed browser origin. Conversation operations also use a short-lived X-AHS-Conversation-Token. A publishable key is restricted, browser-visible, and not an administrative secret.
Server secret API key
Trusted backends call POST /v1/answers with X-AHS-API-Key and no browser Origin. An optional exact IP allowlist can restrict the source. Never place this secret in browser or mobile code.
Test and Production environments
Each project starts with isolated Test and Production environments. Knowledge, settings, conversations, publishable keys, and server keys stay bound to their exact environment.
Consistent errors
API failures use the documented ErrorEnvelope. Handle the HTTP status and stable error code; show the message safely and retain X-Request-ID when support needs to trace a request.
Endpoint-specific rate limits
Protected search, generation, and Widget operations can return 429. Limits vary by operation and scope, so back off instead of assuming one global quota.
OpenAPI 3.1
Interactive implemented API reference
Search endpoints, inspect schemas and security requirements, copy request examples, or download the canonical YAML. Trying a request still requires the credentials declared by that operation.