Eventory Watchlist API

HTTP API for managing a client's watchlist of monitored events. Each watchlist item describes an event you want to track on a ticketing marketplace — the website, event, region, and seat quantity. The API is request/response JSON over HTTPS and covers the full lifecycle: create, list, read, update, and delete items.

Written By yeet

Last updated 28 days ago

1. Overview

The Watchlist API exposes five endpoints for managing your watchlist plus a health probe. All responses are JSON. There is no client SDK — call it directly with any HTTP client.

The watchlist is the same one the Eventory Stream API reads when deciding which real-time notifications to push you; the two services are independent.

2. Base URL

https://api.eventory.ai/watchlist

TLS is required. Plain HTTP requests are rejected at the gateway. All paths below are relative to this host, e.g. POST https://api.eventory.ai/watchlist.

3. Authentication

Pass your API key on every request using the apikey HTTP header:

apikey: YOUR_API_KEY

The gateway authenticates the request and strips the credential before forwarding it internally; downstream services never see the key. A request with a missing or invalid key is rejected with 401.

4. The Watchlist Item

Read and write operations exchange watchlist item objects. A response includes every field below; most are optional and may be null when unset.

{
  "id": 123,
  "client_id": 42,
  "website": "ticketmaster",
  "event": "evt-1",
  "region": "US",
  "min_price_filter": null,
  "max_price_filter": 250.0,
  "min_avg_price_threshold": null,
  "max_avg_price_threshold": null,
  "stock_threshold_filter": 1,
  "stock_threshold_filter_max": null,
  "seat_quantity": 2,
  "priority": 0,
  "section": null,
  "keywords": null,
  "date_filter": null,
  "row_filter": null,
  "change_type": "stock_increase",
  "standard_tickets": true,
  "resale_tickets": false,
  "general_admission_tickets": false,
  "platinum_tickets": false,
  "no_restricted_view": false,
  "no_accessibility": false,
  "no_presale": false,
  "auto_add_to_watchlist": false,
  "task_active": true,
  "muted_until": null,
  "notes": null,
  "tm_did": null,
  "roles_json": null,
  "webhook_setting_id": null,
  "role_id": null,
  "website_id": null,
  "created_at": "2026-06-18T09:20:00Z",
  "updated_at": "2026-06-18T09:20:00Z",
  "deleted": false
}

Server-managed — present in responses, never accepted in a write body:

Field	Type	Description
`id`	int	Unique id, assigned on create. Use it in the URL path.
`client_id`	int	The client that owns this item.
`created_at`	datetime	When the item was created (ISO8601, UTC).
`updated_at`	datetime	When the item was last updated (ISO8601, UTC).
`deleted`	bool	Soft-delete flag; managed by `DELETE`.

Identity — required when creating an item:

Field	Type	Description
`website`	string	Ticketing marketplace to monitor, e.g. `"ticketmaster"`.
`event`	string	Event identifier to track.
`region`	string	Region/market, e.g. `"US"`.

Filters & options — all optional and writable; omit to keep the server default:

Field	Type	Description
`min_price_filter`	float \| null	Ignore tickets priced below this.
`max_price_filter`	float \| null	Ignore tickets priced above this.
`min_avg_price_threshold`	float \| null	Minimum average price threshold.
`max_avg_price_threshold`	float \| null	Maximum average price threshold.
`stock_threshold_filter`	int \| null	Minimum available stock to notify on.
`stock_threshold_filter_max`	int \| null	Maximum available stock to notify on.
`seat_quantity`	int \| null	Number of contiguous seats you're after.
`priority`	int \| null	Item priority.
`section`	string \| null	Restrict to a section name.
`keywords`	string \| null	Keyword filter.
`date_filter`	string \| null	Restrict to matching event dates.
`row_filter`	string \| null	Restrict to matching rows.
`change_type`	string \| null	Which change triggers a match, e.g.`"stock_increase"` `"stock_decrease"` `"price_decrease"` `"price_increase"`
`standard_tickets`	bool \| null	Include standard tickets.
`resale_tickets`	bool \| null	Include resale tickets.
`general_admission_tickets`	bool \| null	Include general-admission tickets.
`platinum_tickets`	bool \| null	Include platinum tickets.
`no_restricted_view`	bool \| null	Exclude restricted-view seats.
`no_accessibility`	bool \| null	Exclude accessibility seats.
`no_presale`	bool \| null	Exclude presale offers.
`task_active`	bool \| null	Whether monitoring for this item is active.
`muted_until`	datetime \| null	Suppress notifications until this time (ISO8601).
`notes`	string \| null	Free-form notes.
`tm_did`	string \| null	Ticketmaster device id.
`webhook_setting_id`	int \| null	FK to a webhook setting.
`role_id`	int \| null	FK to a role.

Validation is performed server-side; invalid values return 400 (see §6). On create, any field you omit takes the server default; sending an explicit null stores NULL.

5. Endpoints

`POST /watchlist`

Create a watchlist item. Send the writable fields as a JSON object.

curl -X POST -H "apikey: $KEY" -H "Content-Type: application/json" \
  -d '{"website":"ticketmaster","event":"evt-1","region":"US","seat_quantity":2}' \
  "https://api.eventory.ai/watchlist"

Response — 201 Created with the created item. The body carries the full object (see §4); abbreviated here:

{
  "id": 123,
  "website": "ticketmaster",
  "event": "evt-1",
  "region": "US",
  "seat_quantity": 2,
  "task_active": true,
  "notes": null
}

Keep the returned id — you need it to read, update, or delete the item.

`GET /watchlist`

Return the whole watchlist for your client. No body, no query parameters.

curl -H "apikey: $KEY" "https://api.eventory.ai/watchlist"

Response — 200 OK with an array of items (empty array if you have none). Each item is the full object (see §4); abbreviated here:

[
  { "id": 1, "website": "ticketmaster", "event": "evt-1", "region": "US", "seat_quantity": 2, "task_active": true, "notes": null },
  { "id": 2, "website": "ticketmaster", "event": "evt-2", "region": "UK", "seat_quantity": 4, "task_active": false, "notes": "front row only" }
]

`GET /watchlist/{id}`

Return a single item by id.

curl -H "apikey: $KEY" "https://api.eventory.ai/watchlist/123"

Response — 200 OK with the item, or 404 if no item with that id belongs to you.

`PATCH /watchlist/{id}`

Update an item. Send only the fields you want to change; omitted fields are left untouched. To clear a nullable field, send it explicitly as null.

curl -X PATCH -H "apikey: $KEY" -H "Content-Type: application/json" \
  -d '{"seat_quantity":4,"task_active":true}' \
  "https://api.eventory.ai/watchlist/123"

Response — 200 OK with the full, updated item.

`DELETE /watchlist/{id}`

Delete an item.

curl -X DELETE -H "apikey: $KEY" "https://api.eventory.ai/watchlist/123"

Response — 204 No Content on success, or 404 if the item doesn't exist for you.

`GET /watchlist/health`

Liveness probe. Authentication is required like any other call.

curl -H "apikey: $KEY" "https://api.eventory.ai/watchlist/health"

Response:

{ "status": "ok" }

6. Error Reference

Errors are returned as JSON.

Status	When
`400`	Invalid input (e.g. bad event id). Body carries the error message.
`401`	Missing or invalid API key.
`404`	No item with that id belongs to you (get / update / delete).
`500`	Unexpected server error. Safe to retry once with backoff.
`502`	Upstream temporarily unreachable. Retry with backoff.
`504`	Upstream timed out. Retry with backoff.