Your first REST API call
Smoke-test the API end-to-end. Eight lines.
Setup
| export SCAIWAVE_HOST="http://localhost:8000" # or your tenant's URL
export TOKEN="..." # your Bearer JWT
|
Get a token via the auth tutorial
or pass mock-dev-token if your local server is in
SCAIWAVE_AUTH_MODE=mock.
1. Register (if you haven't already)
| curl -X POST "$SCAIWAVE_HOST/v1/auth/register" \
-H "Authorization: Bearer $TOKEN"
|
Returns:
| {
"data": {
"participant_id": "5e4d…",
"tenant_id": "abc-…",
"display_name": "alice"
}
}
|
2. List your rooms
| curl "$SCAIWAVE_HOST/v1/directory/rooms" \
-H "Authorization: Bearer $TOKEN" | jq .
|
Returns an envelope:
1
2
3
4
5
6
7
8
9
10
11
12
13 | {
"data": [
{
"id": "room-…",
"name": "playground",
"room_type": "group",
"workspace_id": "ws-…",
"creator_id": "5e4d…",
"created_at": "2026-05-17T10:21:00Z"
}
],
"meta": { "total": 1 }
}
|
Every authenticated response uses the
{"data": …, "meta": …} envelope. Errors use
{"error": {"code": "...", "message": "..."}}.
3. Create a room
| curl -X POST "$SCAIWAVE_HOST/v1/rooms" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"room_type": "group",
"name": "api-smoke-test",
"topic": "Just testing the API"
}' | jq .
|
Returns the created room with its id. Save it:
| export ROOM_ID="<id from response>"
|
4. Send a message
| curl -X POST "$SCAIWAVE_HOST/v1/rooms/$ROOM_ID/send" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": {
"msgtype": "swp.text",
"body": "Hello from curl"
}
}' | jq .
|
Returns the created event. The message is now searchable
within ~2 seconds.
5. List messages
| curl "$SCAIWAVE_HOST/v1/rooms/$ROOM_ID/messages?limit=10" \
-H "Authorization: Bearer $TOKEN" | jq .
|
The from and direction parameters let you paginate by
stream_position.
6. React
| EVENT_ID=$(curl -s "$SCAIWAVE_HOST/v1/rooms/$ROOM_ID/messages?limit=1" \
-H "Authorization: Bearer $TOKEN" | jq -r .data[0].id)
curl -X POST "$SCAIWAVE_HOST/v1/rooms/$ROOM_ID/events/$EVENT_ID/reaction" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"emoji": "🚀"}'
|
7. Engage an AI
| curl -X POST "$SCAIWAVE_HOST/v1/rooms/$ROOM_ID/ai/engage" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"participant_id": "<ai-participant-id>"}'
|
<ai-participant-id> comes from GET /v1/ai/models or
GET /v1/directory/participants?type=model.
After engaging, send a message in the room — the AI replies.
Watch the WebSocket stream
to see chunks live.
8. Search
| curl -X POST "$SCAIWAVE_HOST/v1/search" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "curl", "limit": 5}' | jq .
|
Finds your messages by content. Hybrid BM25 + vector ranking.
Envelope and errors
All endpoints return {"data": …} on success. On errors:
| {
"error": {
"code": "SW_AUTH_INVALID_TOKEN",
"message": "Invalid or expired token"
}
}
|
code is a stable identifier (SW_*) you can match on. message
is human-readable. See Error codes.
What's next
