Skip to content

Submissions API

Submit new timestamps to the OpenSkip database. All submissions go through a moderation queue before being added.

Authentication Required

All submission endpoints require authentication. See Authentication.

Submit Timestamp

POST /api/v1/submissions

Submit a new timestamp for review.

Request Body

You can submit for an existing episode or propose a new one:

{
  "episode_id": 42,
  "duration_ms": 3550000,
  "intro_start": 0.0,
  "intro_end": 45.5,
  "outro_start": 3420.0,
  "outro_end": 3480.0
}

{
  "proposed_tvdb_id": 81189,
  "proposed_show_title": "Breaking Bad",
  "proposed_season": 1,
  "proposed_episode": 1,
  "duration_ms": 3550000,
  "intro_start": 0.0,
  "intro_end": 45.5,
  "outro_start": 3420.0,
  "outro_end": 3480.0
}

Fields

Field Type Required Description
episode_id integer * Existing episode ID
proposed_tvdb_id integer * TVDB ID for new show
proposed_show_title string Show title (for new shows)
proposed_season integer * Season number
proposed_episode integer * Episode number
duration_ms integer Yes File duration in milliseconds
intro_start decimal Intro start (seconds)
intro_end decimal Intro end (seconds)
outro_start decimal Outro start (seconds)
outro_end decimal Outro end (seconds)
recap_start decimal Recap start (seconds)
recap_end decimal Recap end (seconds)
preview_start decimal Preview start (seconds)
preview_end decimal Preview end (seconds)
submitter_notes string Notes for moderators

*Either episode_id OR (proposed_tvdb_id + proposed_season + proposed_episode) required.

Response

{
  "id": 1,
  "user_id": 42,
  "episode_id": null,
  "proposed_tvdb_id": 81189,
  "proposed_show_title": "Breaking Bad",
  "proposed_season": 1,
  "proposed_episode": 1,
  "duration_ms": 3550000,
  "intro_start": 0.0,
  "intro_end": 45.5,
  "outro_start": 3420.0,
  "outro_end": 3480.0,
  "status": "pending",
  "submitted_at": "2024-01-15T10:30:00Z"
}

List Your Submissions

GET /api/v1/submissions

List submissions you've made.

Query Parameters

Parameter Type Description
status string Filter by status: pending, approved, rejected, needs_info

Example

curl -H "Authorization: Bearer <token>" \
  "https://api.openskip.io/api/v1/submissions?status=pending"

Response

{
  "items": [
    {
      "id": 1,
      "status": "pending",
      "proposed_show_title": "Breaking Bad",
      "proposed_season": 1,
      "proposed_episode": 1,
      "submitted_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Get Submission

GET /api/v1/submissions/{submission_id}

Get details of a specific submission.

Submission Status

Status Description
pending Awaiting moderator review
approved Accepted and added to database
rejected Not accepted
needs_info Moderator needs more information

Submission Guidelines

Do

  • Double-check your timestamps before submitting
  • Include accurate duration for your specific file
  • Use the TVDB ID when possible for new shows
  • Add notes if there's anything unusual

Don't

  • Submit timestamps for trailers or clips
  • Submit duplicate entries for episodes that already have data
  • Guess at timestamps - verify them

Accuracy Tips

Finding Intro End

The intro ends when the theme music stops and the episode content begins. Usually marked by a scene change or title card.

Finding Outro Start

The outro begins when the end credits start rolling, often accompanied by credits music.

Handling Variations

Some shows have:

  • Cold opens: Content before the intro
  • Mid-credits scenes: Content during outro
  • Post-credits scenes: Content after outro

For these cases, set timestamps to skip only the actual credits, not the content.