API Reference

API documentation for ew-npvr

Overview

ew-npvr provides two separate APIs:

  1. Management API: RESTful HTTP API for managing NPVR entries (port 8099)
  2. Media API: Streaming API for content delivery (Unix socket by default)

Management API

The Management API provides CRUD operations for NPVR recordings. Interactive documentation is available via Swagger UI at http://<management-address>/swagger/.

Base URL

http://<management-address>/api/v1

Default: http://localhost:8099/api/v1

Endpoints

Health Check

GET /

Returns service health status.

Response: 200 OK with body "OK"

Create NPVR Entry

POST /content

Creates a new NPVR recording entry.

Request Body:

{
  "channelName": "channel-1",
  "title": "My Recording",
  "startTime": 1713254400,
  "stopTime": 1713258000,
  "refID": "optional-reference-id"
}

Parameters:

  • channelName (string, required): Name of the channel to record
  • title (string, required): Title of the recording
  • startTime (integer, required): Start time in epoch seconds
  • stopTime (integer, required): End time in epoch seconds
  • refID (string, optional): Optional reference ID for external systems

Response: 200 OK

{
  "id": "01HP2Q3R4S5T6U7V8W9X0Y1Z2"
}

Error Responses:

  • 400 Bad Request: Invalid request parameters
  • 409 Conflict: Entry with same refID already exists
  • 424 Failed Dependency: Unable to verify segment availability
  • 500 Internal Server Error: Server error

Get NPVR Entries

GET /content
GET /content/{id}

Retrieves NPVR entries by ID or by search criteria.

Query Parameters:

  • id (string): Specific entry ID or refID
  • channel (string): Filter by channel name
  • startTime (integer): Filter entries starting after this epoch time
  • stopTime (integer): Filter entries ending before this epoch time
  • cursor (string): Pagination cursor for next page
  • limit (integer): Maximum entries to return (1-10000, default: 10000)

Response: 200 OK

{
  "cursor": {
    "nextCursor": "base64-encoded-cursor",
    "limit": 100
  },
  "entries": [
    {
      "id": "01HP2Q3R4S5T6U7V8W9X0Y1Z2",
      "refID": "optional-reference-id",
      "timeCreated": 1713254000,
      "timeModified": 1713254100,
      "channelName": "channel-1",
      "title": "My Recording",
      "startTime": 1713254400,
      "endTime": 1713258000,
      "state": "done",
      "playable": true
    }
  ]
}

NPVR Entry Fields:

  • id (string): Unique time-ordered UUID
  • refID (string): Optional user-provided reference ID
  • timeCreated (integer): Creation timestamp (epoch seconds)
  • timeModified (integer): Last modification timestamp (epoch seconds)
  • channelName (string): Channel name
  • title (string): Recording title
  • startTime (integer): Recording start time (epoch seconds)
  • endTime (integer): Recording end time (epoch seconds)
  • state (string): Current state (pending, ongoing, done, error, deleting, updating, update-ongoing)
  • playable (boolean): Whether the content is ready for playback

Error Responses:

  • 400 Bad Request: Invalid parameters
  • 404 Not Found: Entry not found
  • 500 Internal Server Error: Server error

Update NPVR Entry

PUT /content
PUT /content/{id}

Updates the start and end times of an existing NPVR entry.

Request Body:

{
  "id": "01HP2Q3R4S5T6U7V8W9X0Y1Z2",
  "startTime": 1713254400,
  "stopTime": 1713260000
}

Parameters:

  • id (string, required): Entry ID (can be in URL path or request body)
  • startTime (integer, required): New start time
  • stopTime (integer, required): New end time

Response: 200 OK

Error Responses:

  • 400 Bad Request: Invalid parameters
  • 404 Not Found: Entry not found
  • 423 Locked: Entry cannot be updated in its current state
  • 424 Failed Dependency: Unable to verify new segment availability
  • 500 Internal Server Error: Server error

Delete NPVR Entry

DELETE /content?id={id}
DELETE /content/{id}

Marks an NPVR entry for deletion.

Parameters:

  • id (string, required): Entry ID (in URL path or query parameter)

Response: 200 OK or 204 No Content

Error Responses:

  • 400 Bad Request: Missing ID parameter
  • 423 Locked: Entry cannot be deleted in its current state
  • 500 Internal Server Error: Server error

Media API

The Media API provides access to recorded content segments and metadata for streaming.

Endpoints

Get Segment Times

GET /{channel}/segment_times.json?startTime={startTime}&stopTime={stopTime}

Returns segment timing information for a recording.

Parameters:

  • channel (string): Channel name
  • startTime (integer): Recording start time (epoch seconds)
  • stopTime (integer): Recording end time (epoch seconds)

Response: JSON file containing segment timing metadata

Get Content Info

GET /{channel}/{configId}/content_info.json

Returns content information for a specific channel configuration.

Parameters:

  • channel (string): Channel name
  • configId (integer): Configuration ID

Response: JSON containing content metadata (codec information, track details, etc.)

Get Segment

GET /{channel}/{configId}/{track}/{segment}

Retrieves a media segment file.

Parameters:

  • channel (string): Channel name
  • configId (integer): Configuration ID
  • track (string): Track identifier
  • segment (string): Segment filename (e.g., `12345.cmfv)

Response: Binary media segment data

Special Features:

  • Supports thumbnail generation with thumbnail query parameter
  • Returns appropriate Content-Type headers
  • Includes Edgeware-CBM: 1.44.4 header for compatibility

Pagination

The Management API uses cursor-based pagination for efficient handling of large result sets.

First Request:

GET /api/v1/content?channel=channel-1&limit=100

Response:

{
  "cursor": {
    "nextCursor": "eyJjaGFubmVsIjoiY2hhbm5lbC0xIiwic3RhcnRUaW1lIjoxNzEzMjU4MDAwfQ==",
    "limit": 100
  },
  "entries": [ ... ]
}

Next Page:

GET /api/v1/content?cursor=eyJjaGFubmVsIjoiY2hhbm5lbC0xIiwic3RhcnRUaW1lIjoxNzEzMjU4MDAwfQ==

Error Handling

All APIs use standard HTTP status codes:

  • 200 OK: Successful request
  • 204 No Content: Successful request with no response body
  • 400 Bad Request: Invalid request parameters
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate refID)
  • 423 Locked: Resource locked (cannot perform operation in current state)
  • 424 Failed Dependency: Dependent operation failed
  • 500 Internal Server Error: Server error

Error responses include descriptive text in the response body.