API Overview¶

The OpenSkip API provides access to TV show intro/outro timestamps. It's a RESTful API that returns JSON responses.

Base URL¶

https://api.openskip.io/api/v1

For self-hosted instances, replace with your own domain.

Authentication¶

Reading data is public - no authentication required for querying timestamps, shows, or episodes.

Writing data requires authentication - submitting timestamps requires either:

• JWT Token - Obtained by logging in with username/password
• API Key - Generated from your account for programmatic access

See Authentication for details.

Rate Limits¶

To ensure fair usage and prevent abuse, the API implements rate limiting:

When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header.

Common Response Formats¶

Success Response¶

{
  "items": [...],
  "total": 42
}

Error Response¶

{
  "detail": "Error message describing what went wrong"
}

Validation Error¶

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "Validation error message",
      "type": "error_type"
    }
  ]
}

Endpoints Summary¶

Shows¶

Timestamps¶

Authentication¶

Submissions¶

Data Types¶

Timestamps¶

All timestamp values are in seconds with millisecond precision (up to 3 decimal places).

{
  "intro_start": 0.0,
  "intro_end": 45.500,
  "outro_start": 3420.0,
  "outro_end": 3480.0
}

Duration¶

File duration is provided in milliseconds for precise matching:

{
  "duration_ms": 3600000
}

Interactive Documentation¶

The API includes built-in interactive documentation:

• Swagger UI: /docs - Interactive API explorer
• ReDoc: /redoc - Alternative documentation view