# 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:

| Version | Prefix | Description |
|--------|---------|----------|
| v1 | `/v1/*` | Stable API version |

## **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](https://app.kinescope.io) 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:

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

### List response with pagination

Lists are returned with pagination and sorting metadata:

```json
{
  "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:

| Parameter | Type | Default | Description |
|----------|-----|--------------|----------|
| `page` | integer | 1 | Page number (starts at 1) |
| `per_page` | integer | 10 | Number of items per page |

**Example:**

```bash
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:**

```bash
# 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:**

```bash
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:

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

### HTTP response codes

| Code | Description | When it occurs |
|-----|----------|-----------------|
| 200 | OK | Request completed successfully |
| 400 | Bad Request | Invalid request format or parameters |
| 401 | Unauthorized | Invalid token |
| 402 | Payment Required | Plan limits exceeded |
| 403 | Forbidden | No permission to perform the operation |
| 404 | Not Found | Resource not found |
| 413 | Request Entity Too Large | Request size exceeds the limit |
| 422 | Unprocessable Entity | Data validation error |
| 429 | Too Many Requests | Request rate limit exceeded |
| 500 | Internal Server Error | Server-side error |

### Validation error

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

```json
{
  "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:**

```bash
# 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**

| Resource | Limit |
|--------|-------|
| Requests per second | 10 |
| Requests per minute | 300 |
| Request size | 10 MB |
| Items per page | Depends on endpoint (usually up to 100) |

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](https://docs.kinescope.com/developer-guides/file-upload-via-api/)** — uploading video and supplementary materials
2. **[Kinescope API](https://docs.kinescope.com/developer-guides/kinescope-api/)** — full API documentation
3. **[Analytics](https://docs.kinescope.com/catalog-and-video-management/analytics/)** — getting view statistics via API
4. **[JWT authentication for chat](https://docs.kinescope.com/developer-guides/jwt-authentication-for-stream-chat/)** — setting up stream chat authorization
5. **[Authorization backend](https://docs.kinescope.com/developer-guides/authorization-backend/)** — video access control

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