mark a film watched

report to spooky.mov that you watched a film. it will be added to your list of watches so that you can use it to inform future recommendations on your recents page, and optionally sort it out of recommendations that spooky makes.

POSThttps://spooky.mov/api/v1/watches

request

headers

header	value
Authorization	Bearer spk_your_key
Content-Type	application/json

body parameters

parameter	type	description
tmdb_id	integer	the film’s tmdb id. the surest match.
imdb_id	string	the film’s imdb id, e.g. "tt0081505".
title	string	the film’s title.
year	integer	optional. the year it came out; makes a title match safer.
watched_date	string	optional. a day, "2026-10-17".
watched_at	string or integer	optional. a time, "2026-10-17T21:30:00Z", or unix seconds.

send one of tmdb_id, imdb_id or title. optionally submit a watch date. default value: when the request is received.

to send up to 100 at once, put them in watches:

{"watches": [{"tmdb_id": 694}, {"title": "Alien", "year": 1979, "watched_date": "2026-10-12"}]}

example

curl https://spooky.mov/api/v1/watches \
  -H "Authorization: Bearer spk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "The Shining", "year": 1980, "watched_date": "2026-10-17"}'

response

200 OK

{"received": 1, "saved": 1, "not_horror": 0, "not_found": 0}

field	type	description
received	integer	watches in the request.
saved	integer	horror films marked watched.
not_horror	integer	films found that aren’t horror (not saved).
not_found	integer	films that couldn’t be matched.

errors

400 Bad Request

{"error": "bad_watch", "index": 1}

status	error	description
400	bad_json	the body isn’t json.
400	bad_watch	a watch has no film, or a date that can’t be used (in the future, or not yyyy-mm-dd). index is its position. nothing is saved.
401	bad_key	no key, or a revoked one.
404	not_found	no such endpoint.
405	method_not_allowed	use POST.
413	too_large	over 64 kb.
415	bad_type	send Content-Type: application/json.
429	rate_limited	too many requests: wait a minute (Retry-After).
503	unavailable	try again in a minute.