> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.eventory.ai. Send your API key in the apikey header. Market Data and Live Availability calls cost credits, pings included; GET /usage is free, so use it to test a key. Costs per endpoint: https://eventory.ai/docs/credits-and-access.md # Create watchlist item > Creates a watchlist item. `website`, `event`, and `region` are required; every other field is optional and takes the server default when omitted. Sending an explicit `null` stores `NULL`, except on boolean fields and `priority`, where it is ignored. Keep the returned `id`: you need it to read, update, or delete the item. The Notifications API picks up new items within 60 seconds. `event` may carry several ids separated by commas, which creates one item per id. Validation is all-or-nothing: if any one id fails the format check for that `website` and `region`, the whole request is rejected and nothing is created. Active items count toward your plan's limit of active events. A request that would go over it is rejected with `403` (`Event limit reached: …`), and nothing is created. **Unknown keys are rejected with `400`, not ignored.** The read-only fields returned by `GET` (`id`, `client_id`, `created_at`, `updated_at`, `deleted`, `website_id`) are accepted and ignored. A filter that the target `website` / `region` does not support is dropped and listed in `ignored_fields` — the request still succeeds. See [Watchlist platforms](/guides/watchlist-platforms). **Cost:** free. ## OpenAPI ````yaml /openapi.yaml post /watchlist openapi: 3.1.0 info: title: Eventory API version: '1.0' description: > Every HTTP endpoint of the Eventory platform, reached through the single public gateway at `https://api.eventory.ai`. The Notifications API is a WebSocket and is documented separately under **Notifications API**. Authenticate every request with the `apikey` header. Each endpoint lists its credit cost; see **Credits & access** for how billing works. contact: name: Eventory url: https://eventory.ai servers: - url: https://api.eventory.ai description: Production security: - apiKey: [] tags: - name: Market Data description: | Historical and aggregated marketplace data for events and artists, plus full-text search over the Eventory catalog. Polling API. **1 credit per request** (sales list scales with rows requested). - name: Live Availability description: > On-demand scrape of the current ticket availability for one event on one of the twelve supported platforms. **5 credits per request.** - name: Watchlist description: | Manage the events your account monitors. The watchlist drives the Notifications API. **Free.** - name: Account description: Your plan and credit usage, live from billing. **Free.** paths: /watchlist: post: tags: - Watchlist summary: Create watchlist item description: > Creates a watchlist item. `website`, `event`, and `region` are required; every other field is optional and takes the server default when omitted. Sending an explicit `null` stores `NULL`, except on boolean fields and `priority`, where it is ignored. Keep the returned `id`: you need it to read, update, or delete the item. The Notifications API picks up new items within 60 seconds. `event` may carry several ids separated by commas, which creates one item per id. Validation is all-or-nothing: if any one id fails the format check for that `website` and `region`, the whole request is rejected and nothing is created. Active items count toward your plan's limit of active events. A request that would go over it is rejected with `403` (`Event limit reached: …`), and nothing is created. **Unknown keys are rejected with `400`, not ignored.** The read-only fields returned by `GET` (`id`, `client_id`, `created_at`, `updated_at`, `deleted`, `website_id`) are accepted and ignored. A filter that the target `website` / `region` does not support is dropped and listed in `ignored_fields` — the request still succeeds. See [Watchlist platforms](/guides/watchlist-platforms). **Cost:** free. operationId: createWatchlistItem requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WatchlistItemCreate' example: website: ticketmaster event: 0200642CF18CAA24 region: US seat_quantity: 2 max_price_filter: 250 responses: '201': description: > Item created. `item` is the first created item and `items` carries all of them — the two differ only when `event` held several comma-separated ids. content: application/json: schema: $ref: '#/components/schemas/WatchlistCreateResponse' '400': description: >- Invalid input, or the body is not a JSON object. See [Errors](/errors#watchlist-errors) for the full message catalogue. content: application/json: schema: oneOf: - $ref: '#/components/schemas/WatchlistError' - $ref: '#/components/schemas/DetailError' examples: bad_event_id: value: error: >- One or more IDs are invalid for ticketmaster. Example: 0200642CF18CAA24 unknown_website: value: error: >- Unknown website: "vividseat". Use one of the supported website values listed at https://docs.eventory.ai/guides/watchlist-platforms. website: vividseat missing_field: value: error: Website is required unknown_field: value: error: 'Unknown field(s): max_price' unknown_fields: - max_price not_json: value: detail: request body is not valid JSON '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/Forbidden' '502': $ref: '#/components/responses/ServiceUnavailable' components: schemas: WatchlistItemCreate: allOf: - $ref: '#/components/schemas/WatchlistIdentity' - $ref: '#/components/schemas/WatchlistFilters' WatchlistCreateResponse: allOf: - type: object required: - item - items - createdIds properties: item: $ref: '#/components/schemas/WatchlistItem' items: type: array description: >- Every item created by this request — more than one when `event` held several comma-separated ids. items: $ref: '#/components/schemas/WatchlistItem' createdIds: type: array description: The ids of the created items, in the same order as `items`. items: type: integer example: - 123 - $ref: '#/components/schemas/WatchlistIgnoredFields' WatchlistError: type: object required: - error properties: error: type: string DetailError: type: object required: - detail properties: detail: type: string WatchlistIdentity: type: object required: - website - event - region properties: website: type: string description: > Platform to monitor, e.g. `ticketmaster`. An unknown value is rejected with `400` (`Unknown website: "". …`). For the platforms with a known id format, `event` is checked against that platform's (and often that region's) format. Some platforms are available on request: until one is enabled for your account, using it returns `403` (`Website "" is not available on this account`). See [Watchlist platforms](/guides/watchlist-platforms) for the recognised keys, the retired aliases, and the discovery monitors. example: ticketmaster event: type: string description: > Event identifier on that platform — a bare id or a full event URL depending on the platform. On create, several ids may be sent comma-separated to make one item each. For a discovery monitor this is the artist or venue URL rather than an event id. example: 0200642CF18CAA24 region: type: string description: Region or market, e.g. `US`. example: US WatchlistFilters: type: object description: > Optional filters and options. Omit a field to keep the server default. Boolean fields and `priority` are never `null`; sending `null` for one is ignored. properties: min_price_filter: type: - number - 'null' description: Ignore tickets priced below this. max_price_filter: type: - number - 'null' description: Ignore tickets priced above this. min_avg_price_threshold: type: - number - 'null' max_avg_price_threshold: type: - number - 'null' stock_threshold_filter: type: - integer - 'null' description: Minimum available stock to notify on. stock_threshold_filter_max: type: - integer - 'null' description: Maximum available stock to notify on. min_stock_increase_filter: type: - integer - 'null' description: > Only notify when the stock increase is at least this many tickets. Must be a positive integer; `null` turns the filter off. `0` or a negative value is rejected with `400`. example: 4 min_stock_decrease_filter: type: - integer - 'null' description: > Only notify when the stock decrease is at least this many tickets. Must be a positive integer; `null` turns the filter off. `0` or a negative value is rejected with `400`. example: 4 vip_tickets: type: boolean description: Include VIP tickets. seat_quantity: type: - integer - 'null' description: Number of contiguous seats wanted. priority: type: - integer - 'null' section: type: - string - 'null' description: Restrict to a section name. keywords: type: - string - 'null' date_filter: type: - string - 'null' row_filter: type: - string - 'null' change_type: type: - string - 'null' description: > Which change triggers a notification. The stream enforces this server-side. Any value outside this list is rejected with `400`. enum: - stock_increase - stock_decrease - price_decrease - price_increase - null default: stock_increase standard_tickets: type: boolean resale_tickets: type: boolean general_admission_tickets: type: boolean platinum_tickets: type: boolean no_restricted_view: type: boolean no_accessibility: type: boolean no_presale: type: boolean auto_add_to_watchlist: type: boolean task_active: type: boolean description: Whether monitoring for this item is active. muted_until: type: - string - 'null' format: date-time description: Suppress notifications until this time. notes: type: - string - 'null' tm_did: type: - string - 'null' description: Ticketmaster device id. roles_json: description: Pass-through JSON; treat as opaque. oneOf: - type: object additionalProperties: true - type: array items: {} - type: 'null' webhook_setting_id: type: - integer - 'null' role_id: type: - integer - 'null' website_id: type: - integer - 'null' readOnly: true description: Read-only. Accepted and ignored on write. WatchlistItem: allOf: - type: object required: - id - client_id - created_at - updated_at - deleted properties: id: type: integer description: Assigned on create. Use it in the URL path. client_id: type: integer description: The account that owns this item. created_at: type: string description: >- Timestamp without a UTC offset, e.g. `2026-06-18T09:20:00.123456`. updated_at: type: string description: >- Timestamp without a UTC offset, e.g. `2026-06-18T09:20:00.123456`. deleted: type: boolean description: >- Legacy field, always `false`. `DELETE` removes the item permanently. - $ref: '#/components/schemas/WatchlistIdentity' - $ref: '#/components/schemas/WatchlistFilters' example: id: 123 client_id: 42 website: ticketmaster event: 0200642CF18CAA24 region: US min_price_filter: null max_price_filter: 250 min_avg_price_threshold: null max_avg_price_threshold: null stock_threshold_filter: 1 stock_threshold_filter_max: null min_stock_increase_filter: 4 min_stock_decrease_filter: 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 vip_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:00.123456' updated_at: '2026-06-18T09:20:00.123456' deleted: false WatchlistIgnoredFields: type: object properties: ignored_fields: type: array description: > Filters that were reset because the target `website` / `region` does not support them. Only `seat_quantity`, `row_filter`, `tm_did`, `platinum_tickets` and `vip_tickets` are checked. The request still succeeds; the stored item has those filters switched off: `null`, or `true` for `platinum_tickets` and `vip_tickets`. Absent when nothing was reset. items: type: string example: - platinum_tickets - row_filter warning: type: string description: >- Human-readable summary of `ignored_fields`. Present only when `ignored_fields` is. example: >- Not supported on this website/region and reset: platinum_tickets, row_filter GatewayError: type: object description: > Envelope for every failure decided by the gateway (auth, ACL, billing, rate limit, unknown route, upstream 5xx). Key on `code`; `message` is prose and may change. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthenticated - invalid_credentials - forbidden - no_subscription - limit_reached - no_billing_account - plan_unavailable - payment_required - invalid_parameter - rate_limited - not_found - service_unavailable message: type: string responses: Unauthenticated: description: No credential was sent, or the key was rejected. content: application/json: schema: $ref: '#/components/schemas/GatewayError' examples: missing: value: error: code: unauthenticated message: Authentication is required to access this resource. invalid: value: error: code: invalid_credentials message: Your credentials are invalid or expired. Forbidden: description: >- The key is valid but not granted this route. Contact support to enable it. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: error: code: forbidden message: You do not have access to this service. ServiceUnavailable: description: The upstream service failed or is unreachable. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: error: code: service_unavailable message: The service is temporarily unavailable. securitySchemes: apiKey: type: apiKey in: header name: apikey description: Your Eventory API key. Sent as the `apikey` request header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.