API Reference

Methods & Parameters

Complete reference for the StockFlow v2 API — endpoints, filtering parameters, and JSON response examples. Base URL: https://api.stockflow.ru/v2

Endpoints

All API requests require an Authorization: Bearer <token> header. Responses are returned in JSON with UTF-8 encoding. Rate limit: 120 requests per minute per API key.

GET /clips

List clips with pagination and filtering. Returns up to 60 items per page. Supports category, duration, resolution, and license-type filters.

GET /clips/{id}

Retrieve a single clip by its numeric ID. Includes metadata, thumbnail URLs, available formats, and license details.

GET /categories

List all available clip categories. Returns 24 categories including nature-landscapes, urban-cinematic, food-preparation, and tech-workplace.

POST /search

Full-text search across clip titles, tags, and descriptions. Accepts a JSON body with query, filters, and sort fields. Supports Russian and English queries.

GET /users/me

Return the authenticated user's profile, remaining download quota, and active license tier (Starter, Professional, or Enterprise).

POST /downloads/{clip_id}

Initiate a clip download. Returns a signed pre-authenticated URL valid for 15 minutes. Accepts format (mp4, mov, webm) and resolution (1080p, 4k) in the request body.

Parameters

Query parameters for filtering and sorting. All parameters are optional unless marked as required.

page

Integer. Page number, default 1. Maximum value: 500. Used with per_page for cursor-style pagination.

per_page

Integer. Items per page, default 20. Allowed values: 10, 20, 40, 60. Values above 60 are silently capped.

category_id

String. Filter by category slug. Example: urban-cinematic or nature-landscapes. Must match a value from GET /categories.

duration_min / duration_max

Float. Minimum and maximum clip duration in seconds. Example: duration_min=3.5&duration_max=12.0. Useful for social-media cuts.

resolution

String. Filter by minimum resolution. Values: 720p, 1080p, 4k. A clip tagged 4k also appears under 1080p and 720p queries.

license_type

String. Filter by license. Values: standard, extended, editorial. Defaults to standard if omitted.

sort_by

String. Sort field. Values: relevance, newest, popular, duration. Default: relevance.

order

String. Sort direction. Values: asc or desc. Default: desc.

Response Examples

Sample JSON responses for the most commonly used endpoints. All timestamps use ISO 8601 format.

GET /clips — Success (200)

{
  "data": [
    {
      "id": 18742,
      "title": "Aerial view of Baikal shoreline at golden hour",
      "category_id": "nature-landscapes",
      "duration_sec": 8.4,
      "resolution": "4k",
      "fps": 30,
      "license_type": "standard",
      "thumbnail_url": "https://cdn.stockflow.ru/thumbs/18742_1080.jpg",
      "created_at": "2024-11-03T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_items": 14382,
    "total_pages": 719
  }
}

GET /clips/{id} — Success (200)

{
  "id": 18742,
  "title": "Aerial view of Baikal shoreline at golden hour",
  "description": "Drone footage of Lake Baikal ice formations near Listvyanka, shot on DJI Inspire 3 with Zenmuse X7.",
  "category_id": "nature-landscapes",
  "tags": ["drone", "lake", "winter", "aerial", "russia"],
  "duration_sec": 8.4,
  "resolution": "4k",
  "fps": 30,
  "format": "mp4",
  "codec": "H.265",
  "file_size_mb": 247,
  "license_type": "standard",
  "author": {
    "id": 391,
    "display_name": "Mikhail Volkov"
  },
  "formats_available": ["mp4", "mov", "webm"],
  "thumbnail_url": "https://cdn.stockflow.ru/thumbs/18742_1080.jpg",
  "created_at": "2024-11-03T14:22:00Z"
}

POST /search — Success (200)

{
  "query": "city timelapse night",
  "data": [
    {
      "id": 22105,
      "title": "Moscow Ring Road night timelapse",
      "relevance_score": 0.94,
      "category_id": "urban-cinematic",
      "duration_sec": 15.0,
      "resolution": "4k"
    },
    {
      "id": 19887,
      "title": "Saint Petersburg Admiralty embankment at dusk",
      "relevance_score": 0.87,
      "category_id": "urban-cinematic",
      "duration_sec": 10.2,
      "resolution": "1080p"
    }
  ],
  "pagination": {
    "page": 1,
    "total_items": 342
  }
}

Error — 401 Unauthorized

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Missing or invalid API key. Provide a Bearer token in the Authorization header.",
    "status": 401
  }
}

Error — 429 Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded 120 requests per minute. Retry after 42 seconds.",
    "status": 429,
    "retry_after": 42
  }
}