General API Guidelines

This page describes the general rules for working with the Kinescope API that apply to all endpoints. If you’re new to the API, start here.

Who this article is for

• Developers — need to get started with the Kinescope API
• Backend developers — need to understand basic authorization rules and request formats
• DevOps engineers — need to integrate Kinescope into automated processes

Basic information

Base URL

All API requests are made to:

https://api.kinescope.io

API versions

The Kinescope API uses versioning via URL prefixes:

Authorization

Token format

For authorization in the public API, use the Authorization header with the Bearer type:

Authorization: Bearer YOUR_API_TOKEN

Important: The API token must be in UUID format (e.g., e51e55a1-7615-493e-9055-10ac9cc44ccd). You can get a token from the Kinescope Dashboard in Settings → API tokens.

Workspace and tokens

Each API token is tied to a specific workspace. When making a request, the workspace is determined automatically from the token — you don’t need to pass it separately.

All endpoints require the Authorization: Bearer ... header.

Response format

Successful response

All successful responses are returned in JSON format with a wrapper:

{
  "data": {
    "id": "video-uuid",
    "title": "My Video",
    "status": "done"
  }
}

List response with pagination

Lists are returned with pagination and sorting metadata:

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 156
    },
    "order": {
      "created_at": "desc"
    }
  },
  "data": [
    {"id": "video-1", "title": "First Video"},
    {"id": "video-2", "title": "Second Video"}
  ]
}

Response headers

All API responses include the X-Request-ID header with a unique request identifier. Use it when contacting support:

X-Request-ID: 7127f2d7-0e96-40d0-9a03-2e987c096466

Pagination

Use pagination parameters to retrieve lists:

Example:

curl "https://api.kinescope.io/v1/videos?page=2&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sorting

Use the order parameter to sort results:

order=field.direction,field2.direction

• field — field name for sorting
• direction — direction: asc (ascending) or desc (descending)
• Multiple fields can be specified separated by commas

Examples:

# Newest first, then alphabetical
curl "https://api.kinescope.io/v1/videos?order=created_at.desc,title.asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# By creation date ascending only
curl "https://api.kinescope.io/v1/videos?order=created_at.asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

If a field is specified without a direction, asc is used by default.

Important: Not all fields support sorting. If an invalid field is specified, the API will return an error with code 400216 (NOT_ALLOWED_ORDER_FIELD).

Date format

For analytics and time ranges

The from and to parameters support two formats:

1. Short format: YYYY-MM-DD (e.g., 2024-01-01)
2. Full format: RFC3339 YYYY-MM-DDTHH:MM:SSZ (e.g., 2024-01-01T00:00:00Z)

Example:

curl "https://api.kinescope.io/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Both parameters are required for analytics endpoints.

Error handling

Error format

All errors are returned in a consistent format:

{
  "error": {
    "code": 404404,
    "message": "video not found",
    "detail": "The requested video does not exist or has been deleted"
  }
}

HTTP response codes

Validation error

For validation errors, the response also includes an invalid_params array:

{
  "error": {
    "code": 400400,
    "message": "validation error",
    "invalid_params": [
      {
        "name": "title",
        "reason": "required",
        "message": "Title is required"
      },
      {
        "name": "privacy_type",
        "reason": "oneof",
        "message": "Must be one of: anywhere, nowhere, custom"
      }
    ]
  }
}

Special response formats

CSV export

Some endpoints support exporting data in CSV format via a .csv suffix in the URL:

Example:

# JSON (default)
curl "https://api.kinescope.io/v1/billing/invoices/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# CSV
curl "https://api.kinescope.io/v1/billing/invoices/123.csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Important: CSV format is not supported for all endpoints. Check the specific endpoint’s documentation or try adding .csv to the URL — if the format is not supported, JSON will be returned.

Limits and restrictions

If limits are exceeded, the API will return 429 Too Many Requests.

What’s next?

Now that you know the general API rules, you can proceed to specific sections:

1. File upload via API — uploading video and supplementary materials
2. Kinescope API — full API documentation
3. Analytics — getting view statistics via API
4. JWT authentication for chat — setting up stream chat authorization
5. Authorization backend — video access control

Still have questions? Write to the support chat within the Kinescope interface — our specialists will help!