Quick Start

Terms

Data Model

The API is organized around these core entities:

Understanding Indexes & Positions

Ratings have index1, index2, and position fields whose meaning depends on the item type. The /itemtypes endpoint provides labels for each.

Walkthrough

1 Search for an item:

curl -H 'X-API-KEY: YOUR_KEY' 'https://www.doesthedogdie.com/api/v3/items?q=old%20yeller'

[
  {
    "id": 10752,
    "name": "Old Yeller",
    "genres": ["adventure"],
    "releaseYear": 1957,
    "itemTypeId": 15,
    "itemTypeName": "Movie",
    "tmdbId": 22660,
    "imdbId": "tt0050798",
    "posterImage": "https://www.doesthedogdie.com/content/cpmJy...",
    "overview": "Young Travis Coates is left to take care of..."
  }
]

2 Get full details and topic stats:

curl -H 'X-API-KEY: YOUR_KEY' 'https://www.doesthedogdie.com/api/v3/items/10752'

{
  "id": 10752,
  "name": "Old Yeller",
  ...
  "topicItemStats": [
    {
      "topicItemId": 395866,
      "yesSum": 57,
      "noSum": 3,
      "numComments": 7,
      "topicId": 153,
      "topicName": "a dog dies",
      "itemId": 10752
    }
  ]
}

The topicItemStats array shows yes/no vote totals and comment count per topic for the item.

3 Get detailed ratings for a specific topic (Startup tier+):

curl -H 'X-API-KEY: YOUR_KEY' 'https://www.doesthedogdie.com/api/v3/items/10752/ratings?topicId=153'

[
  {
    "id": 3369418,
    "yes": 1,
    "no": 0,
    "triggerDescription": "The dog is shot by his owner...",
    "cueDescription": "Travis picks up the gun.",
    "position1": 1,  // hours
    "position2": 18, // minutes
    "position3": 42, // seconds
    "safePosition1": 1,
    "safePosition2": 20,
    "safePosition3": 5,
    "isSceneAlert": true,
    "itemId": 10752,
    "topicId": 153
  }
]

Ratings where isSceneAlert is true are professionally produced Scene Alerts with precise timestamps and descriptions.

Authentication

All requests require an X-API-KEY header with your API key from your profile page.

curl -H 'X-API-KEY: ddd_abc123...' 'https://www.doesthedogdie.com/api/v3/items?q=jaws'

All responses are JSON. No Accept header required.

Tiers & Rate Limits

Each user account has a tier that determines rate limits and data access. Upgrade your tier →

Rate limit headers are included on every response:

When a limit is exceeded you'll receive 429 Too Many Requests with a Retry-After header.

Endpoints

Search Items

[
  {
    "id": 10752,
    "name": "Old Yeller",
    "genres": ["adventure"],
    "releaseYear": 1957,
    "itemTypeId": 15,
    "itemTypeName": "Movie",
    "tmdbId": 22660,
    "imdbId": "tt0050798",
    "backgroundImage": "https://www.doesthedogdie.com/content/dYxm...",
    "posterImage": "https://www.doesthedogdie.com/content/cpmJ...",
    "overview": "Young Travis Coates is left to take care of..."
  }
]

Item Detail

{
  "id": 10752,
  "name": "Old Yeller",
  "genres": ["adventure"],
  "releaseYear": 1957,
  "itemTypeId": 15,
  "itemTypeName": "Movie",
  "tmdbId": 22660,
  "imdbId": "tt0050798",
  "backgroundImage": "...",
  "posterImage": "...",
  "overview": "...",
  "topicItemStats": [
    {
      "topicItemId": 395866,
      "yesSum": 57,
      "noSum": 3,
      "numComments": 7,
      "topicId": 153,
      "topicName": "a dog dies",
      "itemId": 10752
    }
  ]
}

Item Ratings

Only ratings with substantive content are returned — those with a comment, cue description, or timestamp. Bare yes/no votes are excluded.

[
  {
    "id": 3369418,
    "yes": 1,
    "no": 0,
    "voteSum": 0,
    "triggerDescription": "The dog is shot by his owner...",
    "isRampant": false,
    "index1": -1,
    "index2": -1,
    "position1": 1,
    "position2": 18,
    "position3": 42,
    "safePosition1": 1,
    "safePosition2": 20,
    "safePosition3": 5,
    "cueDescription": "Travis picks up the gun.",
    "itemId": 10752,
    "topicId": 153,
    "isSceneAlert": true
  }
]

Topics

[
  {
    "id": 153,
    "name": "a dog dies",
    "notName": "no dogs die",
    "keywords": "Dog death, canine death...",
    "description": "...",
    "doesName": "Does the dog die",
    "listName": "where the dog dies",
    "minimalName": "dogs dying",
    "topicCategoryId": 56,
    "altTopicCategoryId": 22
  }
]

Item Types

Returns all item types with their field labels. Use these to interpret index1, index2, and position fields on ratings.

[
  {
    "id": 15,
    "name": "Movie",
    "slug": "movie",
    "verb": "watch",
    "pastTenseVerb": "watched",
    "index1Label": null,
    "index2Label": null,
    "position1Label": "Hours",
    "position2Label": "Minutes",
    "position3Label": "Seconds"
  },
  {
    "id": 16,
    "name": "TV",
    "slug": "tv",
    "verb": "watch",
    "pastTenseVerb": "watched",
    "index1Label": "Season",
    "index2Label": "Episode",
    "position1Label": "Hours",
    "position2Label": "Minutes",
    "position3Label": "Seconds"
  },
  {
    "id": 14,
    "name": "Book",
    "slug": "books",
    "verb": "read",
    "pastTenseVerb": "read",
    "index1Label": "chapter",
    "index2Label": null,
    "position1Label": null,
    "position2Label": null,
    "position3Label": null
  }
]

Topic Categories

[
  {
    "id": 56,
    "name": "Animal Injury or Death",
    "topicSuperCategoryId": 3
  },
  {
    "id": 22,
    "name": "Sad & Stressful Themes",
    "topicSuperCategoryId": 2
  }
]

Topic Super Categories

[
  {
    "id": 2,
    "name": "Emotional Spoilers",
    "shortName": "Emotional"
  },
  {
    "id": 3,
    "name": "Disturbing Content",
    "shortName": "Disturbing"
  }
]

Errors

All error responses follow this format:

{
  "error": "error_code",
  "message": "Human-readable description"
}