Hedy API

What is the Hedy API?

The Hedy API provides programmatic access to your meeting data, transcripts, summaries, and AI-generated insights. Whether you’re building custom integrations, automating workflows, or connecting with tools like Zapier, the API gives you the power to extend Hedy’s capabilities beyond the app. All API features require a Pro subscription with cloud sync enabled.

Getting Started with the API

1. Open the Hedy app and navigate to Account Settings

2. Scroll to the API Access section

3. Click Generate New API Key (Pro subscription required)

4. Copy your API key and store it securely - you won’t be able to see it again

5. Visit our API documentation on SwaggerHub for detailed endpoint information, or access the raw OpenAPI spec at https://api.hedy.bot/v1/docs

Security Note: Your API key provides full access to your Hedy data. Keep it secure and never share it publicly or commit it to version control.

API Capabilities

The Hedy API offers comprehensive access to your meeting intelligence:

• Sessions: List and retrieve your meeting sessions, including full transcripts, AI summaries, and key points

• Highlights: Retrieve important moments from your meetings with AI-generated insights

• Topics: Create, update, delete, and organize sessions by topics with custom context instructions

• Todos: Retrieve and manage action items across all sessions

• Session Contexts: Create and manage reusable instructions that guide how Hedy analyzes your meetings

• Webhooks: Configure and manage webhook endpoints via the API for real-time event notifications

• User Info: Retrieve your account details via the /me endpoint

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Webhooks

Set up webhooks to receive real-time notifications when events occur in your Hedy account:

1. In the API Access section, click Manage Webhooks

2. Click the + button to add a new webhook

3. Enter your HTTPS endpoint URL

4. Select the events you want to receive:

   • session.created - When a new recording session starts

   • session.ended - When a recording session completes processing

   • session.exported - When a session is manually exported by the user

   • highlight.created - When a new highlight is added

   • todo.exported - When todos are exported from a session

5. Save your webhook and note the signing secret for payload verification

You can also manage webhooks programmatically via the API using GET, POST, and DELETE on the /webhooks endpoint. Each account can have up to 50 webhooks.

Webhook Signature Verification

Every webhook delivery includes a signature in the X-Hedy-Signature header so you can verify it came from Hedy. The signature is an HMAC-SHA256 hash of the raw request body, signed with your webhook’s signing secret. Verify the signature on your server before processing the payload to ensure authenticity. Each delivery also includes an X-Hedy-Event header indicating the event type (e.g., session.ended).

Session Contexts

Session Contexts let you create reusable sets of custom instructions that tell Hedy how to analyze your meetings. For example, you might create a context for “Sales Calls” that focuses on action items and customer objections, or one for “Standup Meetings” that tracks blockers and updates.

Use the API to manage your session contexts:

• GET /contexts - List all your session contexts

• GET /contexts/{id} - Get a specific context by ID

• POST /contexts - Create a new context (title and content)

• PATCH /contexts/{id} - Update an existing context

• DELETE /contexts/{id} - Remove a context

Set a context as default and it will apply to all new sessions automatically. Free tier accounts are limited to 1 session context.

Managing Topics via API

Topics help you organize your sessions into categories. The API supports full topic management:

• GET /topics - List all topics with AI-generated insights and session counts

• GET /topics/{id} - Get a specific topic’s details

• POST /topics - Create a new topic with name, description, color, and icon

• PATCH /topics/{id} - Update a topic’s properties or custom context

• DELETE /topics/{id} - Remove a topic (sessions are unlinked, not deleted)

• GET /topics/{id}/sessions - List all sessions within a topic

Topics can include a topicContext field with custom instructions (up to 20,000 characters) that guide how Hedy analyzes sessions assigned to that topic.

Common Use Cases

• Project Management Integration: Automatically create tasks in your PM tool from meeting action items

• Knowledge Management: Index meeting content in your company’s knowledge base

• CRM Integration: Update customer records with meeting insights

• Analytics Dashboards: Build custom reports on meeting patterns and productivity

• Workflow Automation: Trigger actions based on meeting content or completion

• Zapier Integration: Connect Hedy to thousands of apps using Zapier (add ?format=zapier to endpoints for Zapier-compatible flat array responses)

API Limits and Best Practices

• Rate limits: 200 requests per minute per API key

• Pagination: Use the limit parameter (default 50, max 100) and the after cursor parameter to page through results

• Cache responses when possible to reduce API calls

• Handle errors gracefully with exponential backoff

• Use webhooks for real-time updates instead of polling

Auto Export Todos

Enable automatic todo export to send action items to your integrated systems:

1. In the API Access section, toggle on Auto Export Todos

2. Todos will be automatically sent to your configured webhook endpoints

3. Each todo includes context, assignee suggestions, and meeting reference

Code Examples

Here’s a simple example to get your recent sessions:

curl -X GET "https://api.hedy.bot/v1/sessions?limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

For more examples and the full endpoint reference, visit our API documentation.

Troubleshooting

401 Unauthorized Error

• Verify your API key is correct and properly formatted

• Ensure you have an active Pro subscription

• Check that cloud sync is enabled in your account

• Confirm the API key hasn’t been regenerated (old keys are invalidated)

Empty Response or Missing Data

• Ensure cloud sync is enabled - API only accesses cloud-synced data

• Wait a few minutes after recording for data to sync

• Check your date filters and pagination parameters

• Verify you’re using the correct endpoint for your data type

Webhook Not Receiving Events

• Confirm your endpoint URL uses HTTPS (required)

• Check that your server responds with 200 OK status

• Verify the X-Hedy-Signature header if implementing signature verification

• Test your webhook using the “Test Webhook” button

• Check firewall rules aren’t blocking Hedy’s servers

Rate Limit Exceeded

• Implement caching to reduce redundant API calls

• Use webhooks for real-time updates instead of polling

• Batch operations where possible

• Contact support if you need higher limits

Pro tip: Use webhooks instead of polling for real-time updates. This is more efficient and provides instant notifications when your data changes.

Privacy and Security

Your data security is our priority:

• All API communication uses HTTPS encryption

• API keys can be regenerated at any time (invalidates old key)

• Webhook payloads are signed with HMAC-SHA256 for verification

• Data is only accessible with valid authentication

• All endpoints enforce strict security headers

Getting Help

For API-specific questions:

• Browse the API documentation for endpoint details and schemas

• Read our API announcement blog post for examples and use cases

• Join our Slack community for support and to share your integrations