DEVELOPER GUIDE

Business capabilities.
Explicit integration contracts.

Integrate through the versioned API, register tools and MCP servers, and track asynchronous work. Start with authentication, resource ownership, and the response contract for the endpoint you use.

Read the quickstart System architecture

AUTHENTICATED BUSINESS API

Start with a session.

Use the backend origin for your environment. An active account with login enabled is required; the AI authentication endpoint issues a Sanctum bearer token.

Configure your origin and account.
Set KAZIAI_API_ORIGIN to the Laravel backend origin. The API root is /api/ai/v2. Obtain a token from POST /auth/login; the login response contains data.token and data.user.
Create a conversation session.
The session endpoint associates work with the authenticated user and company. The created session response returns the identifier at the top level.

Create a session

curl "$KAZIAI_API_ORIGIN/api/ai/v2/sessions"   --request POST   --header "Authorization: Bearer $KAZIAI_TOKEN"   --header "Content-Type: application/json"   --header "Accept: application/json"   --header "Idempotency-Key: onboarding-session-001"   --data '{"channel":"web"}'

Session response shape

{
  "session_id": "<session-id>",
  "channel": "web",
  "expires_at": "<expiry-timestamp>"
}

Send a scoped business request.
Supply the session identifier and, optionally, an enabled agent or model. Use a distinct idempotency key for each intended write request.

Send a business request

curl "$KAZIAI_API_ORIGIN/api/ai/v2/chat"   --request POST   --header "Authorization: Bearer $KAZIAI_TOKEN"   --header "Content-Type: application/json"   --header "Accept: application/json"   --header "Idempotency-Key: project-request-001"   --data '{
    "message": "Review the current project tasks and identify blockers.",
    "session_id": "<session-id>",
    "agent": "operations"
  }'

These examples document the source API contract. Replace placeholders with your environment values and validate the responses against your backend version.

A MAP OF THE API SURFACE

Discover. Prepare.
Execute. Inspect.

Capability	Representative endpoint	Purpose
Discovery	`GET /agents · GET /tools`	Inspect the enabled agent and tool catalog.
Conversation	`POST /chat · GET /sessions/{id}`	Submit a request and inspect its session history.
Knowledge	`POST /knowledge/hybrid-search`	Retrieve relevant business knowledge.
Planning	`POST /planning/create`	Create a structured execution plan.
Approvals	`POST /approvals/{id}/approve`	Apply an authorized reviewer decision.
Integrations	`POST /connectors/{slug}/test`	Test a configured company connection.
MCP	`POST /mcp · GET /mcp/info`	Use or inspect the MCP server interface.
Jobs	`POST /jobs · GET /jobs/{id}`	Submit and track asynchronous work.
Health	`GET /health · GET /health/ready`	Inspect service and readiness state.

Paths above are relative to /api/ai/v2. Authorization and request schemas vary by capability; confirm the registered route and its request contract before use.

CLIENT BEHAVIOR MATTERS

Treat each response
as a defined contract.

Authentication & ownership

Bearer authentication and company ownership are separate checks. A valid token does not grant permission to every operation or resource.

Response envelopes

The source uses different envelopes: discovery can return {data: [...]}, session lists wrap pagination, and session creation returns a top-level session_id. Normalize per endpoint rather than assuming a global response shape.

Idempotent write requests

Idempotency protection activates when a write request supplies Idempotency-Key. Reusing a key with different request content is a conflict; do not use one key for unrelated operations.

Request tracing

Use X-Request-ID and the returned request/correlation identifiers to connect client activity to server logs and usage records.

Rate limits & retries

Routes have different throttles. Respect rate-limit responses, use bounded retries, and define whether replaying an action is safe before retrying it.

Streaming & cancellation

Validate HTTP status, event names, JSON event payloads, error events, and cancellation against the selected streaming endpoint. The current project’s streaming integration requires further validation.

CONNECT AT THE RIGHT BOUNDARY

Three ways to
extend a workflow.

Register a business tool

Give a tool a structured argument schema, a handler, and an explicit permission and approval policy. Its result must distinguish success, failure, and pending review.

Use events and webhooks

Define the event contract and subscription. Handle authentication, retries, duplicates, delivery records, and replay without creating duplicate business actions.

Connect through MCP

The source includes client/server interfaces, server registration, tool discovery, and status services. Test transport, authentication, discovered tool schemas, and execution authorization for the selected server.

Inspect the connector catalog

KAZILITE & PROVIDER ROUTING

Connect a serving endpoint.
Evaluate the workload.

The KaziLite provider uses a configurable OpenAI-compatible base URL and chat, tool-calling, embedding, streaming, and health methods. Implemented adapter methods do not establish that every served checkpoint supports every capability.

Decision	Verify
Serving contract	Endpoint paths, authentication, model identifiers, request formats, and error behavior.
Model capability	Representative prompts, structured tool arguments, context limits, and approval-sensitive requests.
Operational capacity	Latency, concurrent workload, memory requirements, availability, and recovery behavior.
Data policy	Allowed information, cloud/local routing, logs, retention, and connected external services.

KaziLite training and benchmark assets are part of the adjacent model package. Treat benchmark targets and synthetic reference evaluations separately from measured model performance.

BEFORE A TECHNICAL PILOT

Test the boundaries
as carefully as the happy path.

Verify authentication, permissions, and cross-company access denial.
Confirm endpoint schemas, response envelopes, and pagination.
Exercise missing arguments, rejected approvals, failed handlers, and timeouts.
Test duplicate requests and idempotency conflicts on consequential writes.
Verify streaming errors and cancellation before enabling the streaming client.
Record evaluation results and reconcile completed work against its source system.

A PRACTICAL NEXT STEP

Build a pilot with explicit acceptance criteria.

Scope the business outcome, identify the controls, and define what a successful pilot must prove.

Plan your implementation

Business capabilities.Explicit integration contracts.