API Reference

The platform provides a comprehensive REST and GraphQL API for programmatic access to all features. This section provides an overview of the API capabilities.

API Overview

Base URL:

https://api.platform.com/v1

GraphQL Endpoint:

https://api.platform.com/graphql

Authentication:

• Bearer token authentication
• OAuth 2.0 support
• API key authentication

API Versioning

The API uses versioning to ensure stability:

• Current Version: v1
• Version Header: API-Version: v1
• Deprecation Policy: Deprecated endpoints are announced 6 months in advance

Rate Limits

• Standard Plan: 1,000 requests per hour
• Professional Plan: 5,000 requests per hour
• Enterprise Plan: 20,000 requests per hour
• Rate Limit Headers: Included in all responses

Authentication Methods

Bearer Token

Authorization: Bearer YOUR_API_TOKEN

OAuth 2.0

Authorization: Bearer YOUR_OAUTH_TOKEN

API Key

X-API-Key: YOUR_API_KEY

REST API Endpoints

Recordings

• GET /recordings - List all recordings
• GET /recordings/{id} - Get recording details
• POST /recordings - Upload new recording
• PUT /recordings/{id} - Update recording
• DELETE /recordings/{id} - Delete recording
• GET /recordings/{id}/transcript - Get transcript
• GET /recordings/{id}/summary - Get AI summary

Meetings

• GET /meetings - List all meetings
• GET /meetings/{id} - Get meeting details
• POST /meetings - Create meeting
• PUT /meetings/{id} - Update meeting
• DELETE /meetings/{id} - Delete meeting

Speakers

• GET /speakers - List all speakers
• GET /speakers/{id} - Get speaker details
• POST /speakers - Create speaker
• PUT /speakers/{id} - Update speaker
• DELETE /speakers/{id} - Delete speaker

Signals

• GET /signals - List all signals
• GET /signals/{id} - Get signal details
• POST /signals - Create custom signal
• PUT /signals/{id} - Update signal
• GET /signals/results - Get signal detection results

GraphQL API

Example Query

query GetRecording($id: ID!) {
  recording(id: $id) {
    id
    title
    duration
    transcript {
      text
      segments {
        start
        end
        speaker
        text
      }
    }
    summary {
      full
      short
      actionItems
    }
  }
}

Example Mutation

mutation CreateMeeting($input: MeetingInput!) {
  createMeeting(input: $input) {
    id
    title
    scheduledStart
    scheduledEnd
  }
}

Request/Response Formats

Request Format:

• Content-Type: application/json
• Accept: application/json

Response Format:

{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "v1"
  }
}

Error Handling

Error Response Format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { ... }
  }
}

Common Error Codes:

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Rate Limit Exceeded
• 500 - Internal Server Error

Pagination

List endpoints support pagination:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  }
}

Query Parameters:

• page - Page number (default: 1)
• perPage - Items per page (default: 20, max: 100)

Filtering and Sorting

Filtering:

GET /recordings?status=completed&folder=123

Sorting:

GET /recordings?sort=createdAt&order=desc

Webhooks

Webhooks allow you to receive real-time notifications:

Supported Events:

• recording.processed
• recording.failed
• meeting.created
• meeting.updated
• signal.detected
• transcript.completed

Webhook Payload:

{
  "event": "recording.processed",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": { ... }
}

API Documentation

For complete API documentation:

• Interactive API Docs: Available in your account under Settings → API
• OpenAPI Specification: Download from API settings
• GraphQL Schema: Available at /graphql/schema
• Postman Collection: Import from API settings

SDKs and Libraries

Official SDKs are available for:

• JavaScript/TypeScript: npm install @platform/sdk
• Python: pip install platform-sdk
• Ruby: gem install platform-sdk
• Go: go get github.com/platform/sdk-go

API Best Practices

1. Use pagination: Always paginate large result sets
2. Handle rate limits: Implement exponential backoff
3. Cache responses: Cache data when appropriate
4. Use webhooks: Prefer webhooks over polling
5. Error handling: Always handle errors gracefully
6. Version pinning: Pin to specific API versions
7. Secure tokens: Never expose API tokens in client-side code

Note: For detailed API documentation, authentication guides, and code examples, visit the API documentation section in your account settings or contact our developer support team.

Additional Resources

• API Status Page: Check API status and uptime
• Developer Portal: Access developer resources and guides
• Community Forum: Connect with other developers
• Support: Contact API support for assistance

Need Help?

• API Documentation: Complete reference documentation available in your account
• Developer Support: Contact our developer support team
• Community: Join our developer community forum
• Status: Check API status and maintenance windows