---
audience: developer
summary: Get a token, hit the API, parse the response. Eight lines of curl.
title: Your first REST API call
path: tutorials/developer/first-rest-api-call
status: published
---

# Your first REST API call

Smoke-test the API end-to-end. Eight lines.

## Setup

```bash
export SCAIWAVE_HOST="http://localhost:8000"   # or your tenant's URL
export TOKEN="..."                              # your Bearer JWT
```

Get a token via the [auth tutorial](/docs/scaiwave/tutorials/developer/authenticate-with-scaikey)
or pass `mock-dev-token` if your local server is in
`SCAIWAVE_AUTH_MODE=mock`.

## 1. Register (if you haven't already)

```bash
curl -X POST "$SCAIWAVE_HOST/v1/auth/register" \
  -H "Authorization: Bearer $TOKEN"
```

Returns:

```json
{
  "data": {
    "participant_id": "5e4d…",
    "tenant_id": "abc-…",
    "display_name": "alice"
  }
}
```

## 2. List your rooms

```bash
curl "$SCAIWAVE_HOST/v1/directory/rooms" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Returns an envelope:

```json
{
  "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

```bash
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:

```bash
export ROOM_ID="<id from response>"
```

## 4. Send a message

```bash
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

```bash
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

```bash
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

```bash
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](/docs/scaiwave/tutorials/developer/subscribe-to-websocket-events)
to see chunks live.

## 8. Search

```bash
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:

```json
{
  "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](/docs/scaiwave/reference/error-codes).

## What's next

- [Send a message via the API](/docs/scaiwave/tutorials/developer/send-a-message-via-api) — deeper into the event model.
- [Subscribe to WebSocket events](/docs/scaiwave/tutorials/developer/subscribe-to-websocket-events).
- API: [Auth](/docs/scaiwave/reference/api/auth), [Rooms](/docs/scaiwave/reference/api/rooms), [Messages](/docs/scaiwave/reference/api/messages-and-reactions).