Getting Started

This guide walks you through authentication and sending your first request to the StipCore Agents API.

Authentication

All endpoints (REST and WebSocket) require a valid JWT in the Authorization header:

Authorization: Bearer <your-jwt-token>

The token is validated and used to load the user/channel configuration. Invalid or missing tokens result in 401 Unauthorized or WebSocket closure with code 4001.

Health check

Verify the service is up:

GET /status

Response:

{ "status": "ok" }

No authentication is required for /status.

First chat request (REST)

1. Synchronous response — Use POST /chat/run when you want the full reply in one response:

POST /chat/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Hello",
  "conversation_id": "optional-existing-conversation-id"
}

Response:

{
  "response": "Full AI reply text",
  "conversation_id": "uuid"
}

2. Streaming response — Use POST /chat/stream to receive Server-Sent Events:

POST /chat/stream
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Hello",
  "conversation_id": "optional-existing-conversation-id"
}

The response is a stream of SSE events; see Chat API for the exact event format.

First WebSocket connection

1. Open a WebSocket to WS /ws with the same Authorization header.
2. Send a JSON message with type and data as described in WebSocket API.
3. Receive replies as JSON messages (sync or stream chunks).

For full message schemas and event types, see WebSocket API.