Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kisara.my.id/llms.txt

Use this file to discover all available pages before exploring further.

This page explains the core integration rules to keep your Kisara API client secure, stable, and predictable in production.

​
Integration Hierarchy

1. Access

Confirm the right auth model first: API key for consumer endpoints and JWT for internal web-session flows.

2. Reliability

Handle traffic spikes with route-aware retries, backoff, and timeout discipline.

3. Contract

Validate envelope fields consistently so client behavior stays predictable.

​
Operational Summary

Start with access control, then implement retry and timeout policies, and finally enforce response-contract validation in your client.

​
Quick Checklist

Auth Header

Ensure protected endpoints always receive X-API-Key from server-side integrations.

Retry Strategy

Handle HTTP 429 with exponential backoff and a clear retry limit.

Response Contract

Validate status_code, message, data, and metadata before downstream processing.

​
Authentication

Consumer API protected endpoints use API key authentication. 
X-API-Key: <your_api_key>
Requests without a valid API key are rejected. Store API keys securely and avoid exposing them in public clients.
JWT bearer tokens are still used for internal web session flows such as login/refresh and API key lifecycle management.

​
Endpoint Access Model

Consumer API Access

Primary access method is X-API-Key on protected routes used by external integrations.

Internal Session Access

JWT is intended for authenticated web-session operations and account-bound internal flows.

​
Rate Limiting

The API applies both global and per-route limits to maintain service stability.
ScopeLimit
Global (all routes)100 requests per IP per minute
Auth and API key management (/auth/*)10 requests per IP per minute
User profile (/user)5 requests per IP per minute
Message routes (/message/*)30 requests per IP per minute
Notes:
  • If a route has a stricter limit, that route limit is applied first.
  • Home routes use the global limit.
  • Rate limit keys are based on client IP.
When limits are exceeded, the API responds with HTTP 429 and the standard error envelope.
1

Detect temporary failures

Treat HTTP 429 as a temporary failure.
2

Retry with backoff

Use exponential backoff (for example: 1s, 2s, 4s, max 30s).
3

Reduce burst traffic

Use batching or queues for heavy endpoints and parallel operations.
{
  "status_code": 429,
  "message": "Rate limit exceeded",
  "metadata": {
    "method": "GET",
    "url": "/endpoint",
    "execution_time_ms": 1,
    "ip": "127.0.0.1",
    "timestamp": "2026-04-15T12:00:00.000Z"
  }
}

​
Response Format

Most endpoints return a response envelope like this: 
{
  "status_code": 200,
  "message": "OK",
  "data": {},
  "metadata": {
    "method": "GET",
    "url": "/endpoint",
    "execution_time_ms": 12,
    "ip": "127.0.0.1",
    "timestamp": "2026-04-14T12:00:00.000Z"
  }
}
Treat this response shape as your main contract. Always validate status_code and metadata on the client side.

​
Contract Validation Order

1

Check status_code and message

Use these fields as your primary decision layer before reading data.
2

Validate data shape

Confirm expected keys and value types to avoid silent parser issues.
3

Capture metadata for observability

Persist timestamp and execution_time_ms for tracing and incident analysis.

​
Best Practices

Always check status_code

Do not rely on HTTP status alone. Use status_code and message to validate outcomes.

Keep metadata

Log metadata.timestamp and metadata.execution_time_ms for audit and debugging.

Use timeouts

Configure request timeouts on the client so your app does not hang during network issues.

Use idempotency

For sensitive operations, prevent duplicate requests to avoid side effects.

​
Next Steps

  • Continue to API Reference for full parameter and schema details.
  • Test endpoints in the API playground to validate integration quickly.

Explore all endpoints

Move to route-level details, request bodies, and response schemas.

Back to docs home

View quickstart, platform endpoints, and recommended onboarding path.
Last modified on April 16, 2026