API Overview

This is the documentation of the public API of ParOne, Inc. The API allows you to programmatically manage your ParOne resources, including organizations, videos, feeds, and analytics. It’s designed to be RESTful and uses standard HTTP protocols.

Authentication

The ParOne APIs have two main classes of endpoints: read-only endpoints and read/write/update endpoints. Read-only endpoints are optimized for large numbers of client requests, whereas the read/write/update endpoints are low-frequency endpoints.

To authenticate just add the appropriate HTTP header to your HTTP request.

Read-only endpoints

To authenticate read-only endpoints, use your feed sync code. You can find your code in Settings -> Organization -> Feed Sync Code

HTTP header	Type	Description
X-Parone-Sync-Code	String	Your Feed Sync Code.

Read/write/update endpoints

To authenticate other endpoints, use your API Key and API Secret. You can find them in Settings -> Organization.

HTTP header	Type	Description
X-Parone-Api-Key	String	Your API Key.
X-Parone-Api-Secret	String	Your API Key Secret.

# Example: Making an authenticated request with required headers

curl -H "X-ParOne-API-Key: your-api-key" \
     -H "X-ParOne-API-Secret: your-api-secret" \
     "https://external.parone.io/v2/"

Rate Limiting

The API implements rate limiting to ensure fair usage. Current limits are:

100 requests per minute for standard accounts
1000 requests per minute for enterprise accounts

If you exceed these limits, you’ll receive a 429 (Too Many Requests) response.

Response Format

All responses are in JSON format. Successful responses typically include either a data object or a status field. Error responses include an error field with a description of what went wrong.

Example success response

{
  "status": "ok",
  "data": { ... }
}

Example error response:

{
  "error": "Invalid API key",
  "status": "KO"
}

Available Endpoints

Feeds Retrieve a curated list of videos grouped into feeds based on content-key and metadata.

Videos Retrieve a filtered list of videos based on organization, entitlements, user watch history, and search criteria.

MMI (Media Management Identifier)

The MMI (Media Management Identifier) allows you to access content from specific sub-organizations within your account. This is useful when you need to isolate videos related to a particular sub-organization.

HTTP Header	Description
X-ParOne-MMI-Key	The MMI key for sub-organization access

# Example: Making a request with MMI for sub-organization access

curl -H "X-ParOne-API-Key: your-api-key" \
     -H "X-ParOne-API-Secret: your-api-secret" \
     -H "X-ParOne-MMI-Key: your-mmi-key" \
     "https://external.parone.io/v2/"

Best Practices

Error Handling: Always check for error responses and handle them appropriately
Rate Limiting: Implement exponential backoff when hitting rate limits
Caching: Cache responses when appropriate to reduce API calls
Versioning: Keep track of API changes through our changelog