hedy

Access Hedy meeting data: sessions, transcripts, highlights, todos, topics, contexts, and webhooks via the Hedy REST API.

# Hedy

Access a user's Hedy meeting data through the Hedy REST API. Read sessions with transcripts, highlights, and todos. Manage topics, session contexts, and webhooks.

Hedy is an AI-powered meeting coach that provides real-time speech transcription and AI-powered conversation analysis. This skill lets you query the user's meeting history, search for specific sessions, retrieve structured meeting outputs, and manage organizational features like topics and webhooks.

## Setup

### 1. Get your API key

Generate an API key inside the Hedy app under Settings > API. Keys start with `hedy_live_`.

### 2. Configure OpenClaw

Add the following to `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "hedy": {
        "enabled": true,
        "apiKey": "hedy_live_YOUR_KEY_HERE",
        "config": {
          "region": "us"
        }
      }
    }
  }
}
```

Set `"region"` to `"eu"` if your Hedy account uses EU data residency. Default is `"us"`.

### 3. Sandbox users

If you run OpenClaw in a Docker sandbox, `apiKey` and `env` values from `openclaw.json` are injected into the host process only. Add the key to your sandbox environment separately:

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "env": {
            "HEDY_API_KEY": "hedy_live_YOUR_KEY_HERE"
          }
        }
      }
    }
  }
}
```

### 4. Restart OpenClaw

Start a new session so the skill is picked up.

## Region and Base URL

Determine the base URL from the configured region:

| Region | Base URL |
|--------|----------|
| `us` (default) | `https://api.hedy.bot` |
| `eu` | `https://eu-api.hedy.bot` |

If no region is configured, default to `us`.

All endpoints below use `{BASE_URL}` as a placeholder. Replace it with the resolved URL.

## Authentication

Every request requires:

```
Authorization: Bearer {HEDY_API_KEY}
```

The API key is injected via the `HEDY_API_KEY` environment variable. Never display, log, or include the API key in output shown to the user.

## Endpoints

All endpoints return JSON. Response shapes vary by endpoint (documented individually below). Error responses always use:

```json
{
  "success": false,
  "error": { "code": "error_code", "message": "Human-readable message" }
}
```

### GET /me

Returns the authenticated user's profile. Response is a bare JSON object (no wrapper).

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/me" | jq
```

Response:

```json
{
  "id": "uid_123",
  "email": "user@example.com",
  "name": "John Doe"
}
```

### GET /sessions

List recent meeting sessions. Only cloud-synced sessions are returned. Response is wrapped in `{ success, data, pagination }`.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/sessions?limit=20" | jq
```

Query parameters:
- `limit` (int, 1-100, default 50): Number of sessions to return

Note: This endpoint returns the most recent `limit` sessions only. There is no cursor-based pagination. To retrieve more sessions, increase the `limit` value (max 100).

Response:

```json
{
  "success": true,
  "data": [
    {
      "sessionId": "sess_123",
      "title": "Weekly Sync",
      "startTime": "2026-03-15T14:30:00Z",
      "duration": 45,
      "topic": { "id": "topic_1", "name": "Team Meetings" }
    }
  ],
  "pagination": { "hasMore": false, "next": null, "total": 42 }
}
```

### GET /sessions/{sessionId}

Full session detail including transcript, AI outputs, highlights, and todos. Response is a bare JSON object (no wrapper).

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/sessions/{sessionId}" | jq
```

Response:

```json
{
  "sessionId": "sess_123",
  "title": "Weekly Sync",
  "startTime": "2026-03-15T14:30:00Z",
  "endTime": "2026-03-15T15:15:00Z",
  "duration": 45,
  "transcript": "full meeting transcript text",
  "cleaned_transcript": "AI-cleaned version or null",
  "cleaned_at": "2026-03-15T16:00:00Z",
  "conversations": "Q&A structured format",
  "meeting_minutes": "formatted minutes",
  "recap": "brief summary",
  "highlights": [],
  "user_todos": [],
  "topic": { "id": "topic_1", "name": "Team Meetings" }
}
```

### GET /sessions/{sessionId}/highlights

Highlights (key quotes) from a specific session.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/sessions/{sessionId}/highlights" | jq
```

### GET /sessions/{sessionId}/todos

Todos from a specific session.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/sessions/{sessionId}/todos" | jq
```

### GET /sessions/{sessionId}/todos/{todoId}

A specific todo item.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/sessions/{sessionId}/todos/{todoId}" | jq
```

### GET /highlights

List all highlights across all sessions, sorted by timestamp (newest first). Response is wrapped in `{ success, data, pagination }`.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/highlights?limit=20" | jq
```

Query parameters:
- `limit` (int, 1-100, default 50)

Note: This endpoint returns the most recent `limit` highlights only. There is no cursor-based pagination. To retrieve more highlights, increase the `limit` value (max 100).

Response:

```json
{
  "success": true,
  "data": [
    {
      "highlightId": "high_123",
      "sessionId": "sess_456",
      "timestamp": "2026-03-15T14:35:00Z",
      "title": "Key Decision"
    }
  ],
  "pagination": { "hasMore": false, "next": null, "total": 15 }
}
```

### GET /highlights/{highlightId}

Full highlight detail. Response is a bare JSON object (no wrapper).

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/highlights/{highlightId}" | jq
```

Response:

```json
{
  "highlightId": "high_123",
  "sessionId": "sess_456",
  "timestamp": "2026-03-15T14:35:00Z",
  "timeIndex": 300000,
  "title": "Key Decision on Mobile App",
  "rawQuote": "yeah I think we should prioritize the mobile app",
  "cleanedQuote": "We should prioritize the mobile app",
  "mainIdea": "Team agreed to prioritize mobile app development",
  "aiInsight": "Strategic prioritization of mobile platform"
}
```

### GET /todos

All todos across all sessions. Returns a flat array (no pagination wrapper).

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/todos" | jq
```

Response (array of):

```json
{
  "id": "uuid-1234",
  "text": "Follow up with John",
  "dueDate": "Tomorrow",
  "sessionId": "sess_123",
  "completed": false,
  "topic": { "id": "topic_1", "name": "Team Meetings" }
}
```

### GET /topics

List all topics (conversation groupings), sorted by last update. Response is wrapped in `{ success, data }`. No pagination.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/topics" | jq
```

Response `data` (array of):

```json
{
  "id": "topic_123",
  "name": "Project Alpha",
  "description": "All about Project Alpha",
  "color": "#FF5733",
  "iconName": "lightbulb_outline",
  "topicContext": "Custom instructions for this topic",
  "topicContextUpdatedAt": "2026-03-15T16:00:00Z",
  "sessionCount": 12,
  "lastSessionDate": "2026-03-15T14:30:00Z",
  "dominantSessionType": "brainstorm",
  "overview": { "summary": "..." },
  "overviewUpdatedAt": "2026-03-15T16:00:00Z",
  "createdAt": "2026-02-01T10:00:00Z",
  "updatedAt": "2026-03-15T16:00:00Z"
}
```

Fields like `overview`, `overviewUpdatedAt`, `topicContext`, and `dominantSessionType` may be null or absent if not yet generated.

### GET /topics/{topicId}

Full topic detail including overview and insights. Response is wrapped in `{ success, data }`.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/topics/{topicId}" | jq
```

### GET /topics/{topicId}/sessions

Sessions grouped under a topic. This is the only endpoint with cursor-based pagination.

```bash
curl -s -H "Authorization: Bearer $HEDY_API_KEY" "{BASE_URL}/topics/{topicId}/sessions?limit=20" | jq
```

Query parameters:
- `limit` (int, 1-100, default 50)
- `startAfter` (string)