API Reference Overview api-reference-overview
The Concurrency Monitoring API provides a RESTful interface for managing streaming sessions and enforcing concurrent usage policies. This reference provides complete documentation for all endpoints, authentication methods, request/response formats, and error handling.
API Base URLs
Production Environment
https://streams.adobeprimetime.com/v2/
Staging Environment
https://streams-stage.adobeprimetime.com/v2/
Note: Always use the staging environment for development and testing. Production credentials are provided only after successful staging integration.
Authentication
All API calls require HTTP Basic Authentication using your application credentials:
- Username: Your application ID (provided by Adobe)
- Password: Empty string
Example Authentication Header
curl -u "<your-app-id>:" https://streams-stage.adobeprimetime.com/v2/sessions
For an application with id "demo-app" the authentication header would be exactly as shown below, including the quotes and colon:
curl -u "demo-app:" https://streams-stage.adobeprimetime.com/v2/sessions
Response Format Standards
Success Responses
All successful responses follow this structure:
{
"status": "success",
"data": {
// Response-specific data
},
"timestamp": "2024-01-15T10:30:00Z"
}
Error Responses
All error responses follow this structure:
{
"associatedAdvice": [
{
"policyName": "string",
"ruleName": "string",
"scope": {},
"attribute": "string",
"threshold": 0,
"conflicts": [
{}
]
}
],
"obligations": [
{
"namespace": "string",
"action": "string",
"arguments": [
"string"
]
}
]
}
Evaluation Result Format
When policies are evaluated (especially for 409 conflicts), responses include an evaluation result:
{
"evaluationResult": {
"decision": "DENY",
"obligations": [
{
"id": "obligation-id",
"fulfillOn": "DENY",
"attributes": {
"attribute1": "value1"
}
}
],
"associatedAdvice": [
{
"id": "advice-id",
"adviceType": "rule-violation",
"attributes": {
"rule": "rule-name",
"threshold": 3,
"current": 4,
"conflicts": [
{
"sessionId": "session-123",
"terminationCode": "term-456",
"metadata": {
"deviceId": "device-789",
"channel": "Channel1"
}
}
]
}
}
]
}
}
Common HTTP Status Codes
Parameter Passing Methods
Path Parameters
Required parameters that are part of the URL path:
{idp}- Identity Provider identifier{subject}- User identifier (typically from Adobe Pass){sessionId}- Session identifier (returned in Location header)
Additionals Parameters
Optional parameters are passed in the URL:
GET /sessions/{idp}/{subject}?platform=test
Form Data (POST/PUT)
Metadata and session data in request body:
POST /sessions/{idp}/{subject}
Content-Type: application/x-www-form-urlencoded
channel=Channel1&deviceId=device-123&contentType=live
Headers
Special parameters passed in HTTP headers:
X-Terminate: termination-code-123
X-Client-Version: 1.0.0
Error Handling Best Practices
409 Conflict Handling
When you receive a 409 Conflict response:
- Parse the evaluation result to understand the policy violation
- Extract conflict information from
associatedAdvice - Present options to the user based on your LIFO/FIFO strategy
- Use termination codes if implementing LIFO behavior
410 Gone Handling
When you receive a 410 Gone response:
- Check if response has a body - indicates remote termination
- Parse advice to understand why session was terminated
- Update UI to reflect session termination
- Handle gracefully - session may have timed out naturally
- Start a new session - if deemed appropriate, initiate a new session
Rate Limiting
When you receive a 429 Too Many Requests:
- Limit call frequency to up to 200 requests per minute, which is the maximum level accepted by CM
- Send heartbeats at the required interval, which is one per minute.
Testing Tools
Interactive API Explorer
Use our Swagger UI for interactive testing:
- Enter your application ID in the top-right corner
- Click “Explore” to set authentication
- Test endpoints with real parameters
- View request/response examples