API Access

Programmatic access to Harmony's data and features.

Overview

The Harmony API enables:

• Custom integrations
• Automated workflows
• Data export and analysis
• Third-party app connections
• Enterprise automation

Getting Started

API Access Requirements

📝 ASSUMPTION: API access may require specific plan levels:

Plan	API Access
Solo	Limited
Plus	Standard
Max	Full
Enterprise	Full + Custom

Getting API Credentials

1. Go to Settings → Integrations → API
2. Click Generate API Key
3. Copy your API key securely
4. Never share or expose your key

API Key Security

• Store securely (environment variables, secrets manager)
• Never commit to code repositories
• Rotate periodically
• Revoke if compromised

Authentication

API Key Authentication

Include your API key in requests:

Authorization: Bearer YOUR_API_KEY

OAuth 2.0

For user-context integrations:

Authorization: Bearer USER_ACCESS_TOKEN

API Endpoints

Meetings

Endpoint	Method	Description
/api/v1/meetings	GET	List meetings
/api/v1/meetings/{id}	GET	Get meeting details
/api/v1/meetings/{id}/transcript	GET	Get transcript
/api/v1/meetings/{id}/summary	GET	Get summary
/api/v1/meetings/{id}/insights	GET	Get insights

Contacts

Endpoint	Method	Description
/api/v1/contacts	GET	List contacts
/api/v1/contacts/{id}	GET	Get contact details
/api/v1/contacts/{id}/meetings	GET	Contact's meetings

Insights

Endpoint	Method	Description
/api/v1/insights	GET	List insights
/api/v1/insights/{id}	GET	Get insight details
/api/v1/insights/{id}/data	GET	Get insight data

Upload

Endpoint	Method	Description
/api/v1/meetings/upload	POST	Upload recording
/api/v1/meetings/{id}/status	GET	Check processing status

Example Requests

List Meetings

curl -X GET "https://api.heyharmony.com/v1/meetings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "mtg_abc123",
      "title": "Sales Call - Acme Corp",
      "date": "2026-02-01T14:00:00Z",
      "duration": 1800,
      "status": "processed"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Get Meeting Transcript

curl -X GET "https://api.heyharmony.com/v1/meetings/mtg_abc123/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "meeting_id": "mtg_abc123",
  "transcript": [
    {
      "speaker": "John Smith",
      "text": "Thanks for joining today.",
      "timestamp": "00:00:05"
    }
  ]
}

Upload a Recording

curl -X POST "https://api.heyharmony.com/v1/meetings/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Customer Call" \
  -F "date=2026-02-01T10:00:00Z"

Pagination

For list endpoints, use pagination:

GET /api/v1/meetings?page=2&per_page=50

Parameters:

Parameter	Default	Max
page	1	-
per_page	20	100

Filtering

Filter results with query parameters:

GET /api/v1/meetings?date_from=2026-01-01&date_to=2026-01-31&status=processed

Common filters:

Filter	Description
date_from	Start date
date_to	End date
status	Processing status
team_id	Specific team
user_id	Specific user

Webhooks

Available Events

Receive notifications when events occur:

Event	Trigger
meeting.started	Recording began
meeting.processed	Processing complete
meeting.failed	Processing failed
insight.generated	Insight created

Setting Up Webhooks

1. Go to Settings → Integrations → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select events to receive
5. Save

Webhook Payload

{
  "event": "meeting.processed",
  "timestamp": "2026-02-01T15:30:00Z",
  "data": {
    "meeting_id": "mtg_abc123",
    "title": "Sales Call",
    "duration": 1800
  }
}

Webhook Security

Verify webhook signatures:

1. Get the signature from X-Harmony-Signature header
2. Compute HMAC-SHA256 of request body
3. Compare signatures

Rate Limits

Default Limits

Plan	Requests/Minute
Plus	60
Max	300
Enterprise	Custom

Rate Limit Headers

Response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706803200

Handling Rate Limits

If you exceed limits:

• HTTP 429 response
• Wait until reset
• Implement exponential backoff

Error Handling

Error Format

{
  "error": {
    "code": "not_found",
    "message": "Meeting not found",
    "details": {}
  }
}

Common Errors

Code	Status	Description
unauthorized	401	Invalid API key
forbidden	403	Insufficient permissions
not_found	404	Resource not found
rate_limited	429	Too many requests
server_error	500	Internal error

SDKs and Libraries

Official SDKs

📝 ASSUMPTION: SDK availability may vary:

• Python SDK
• Node.js SDK
• Ruby SDK

Community Libraries

Check our GitHub for community-maintained libraries.

Use Cases

Automated Reporting

# Get last week's meetings
meetings = harmony.meetings.list(
    date_from="2026-01-25",
    date_to="2026-02-01"
)

# Generate report
for meeting in meetings:
    insights = harmony.meetings.get_insights(meeting.id)
    # Process and report

Data Warehouse Sync

# Export all meetings to data warehouse
meetings = harmony.meetings.list()
for meeting in meetings:
    transcript = harmony.meetings.get_transcript(meeting.id)
    warehouse.insert("meetings", meeting, transcript)

Custom Notifications

# Webhook handler
@app.route("/webhook", methods=["POST"])
def handle_webhook():
    event = request.json
    if event["event"] == "meeting.processed":
        send_slack_notification(event["data"])
    return "OK"

Best Practices

1. Use Pagination

Always paginate large result sets:

all_meetings = []
page = 1
while True:
    response = api.meetings.list(page=page)
    all_meetings.extend(response.data)
    if not response.has_more:
        break
    page += 1

2. Handle Errors Gracefully

Implement retry logic:

import time

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            time.sleep(2 ** attempt)
    raise Exception("Max retries exceeded")

3. Cache When Possible

Reduce API calls:

# Cache meeting data locally
if not cache.has(meeting_id):
    meeting = api.meetings.get(meeting_id)
    cache.set(meeting_id, meeting)

API Documentation

Full API documentation:

📝 API Reference (placeholder)

Support

For API support:

• Documentation: api.heyharmony.com/docs
• Email: [email protected]
• Status: status.heyharmony.com