Developer docs

Sign in, open Integrations, and create a token with a name. Write access is off by default. A token is account-scoped: it covers the searches your account owns now and searches you create later.

The token value is returned only in the create response. Vinotify stores a one-way digest, so the full value is not returned by the token list route. Treat it like a password: keep it in a local environment variable or secret store, never in a URL, chat, log, or committed file.

Authorization: Bearer YOUR_TOKEN

Read access is available with every integration token. A token created with write access has can_write: true; the MCP write tools also require the server-side write feature to be enabled. Revoking a token from Integrations, or with either revoke route below, makes it unusable.

POST /api/v1/integrations/tokens/{token_id}/revoke
DELETE /api/v1/integrations/tokens/{token_id}/revoke

The hosted MCP endpoint is a stateless JSON-RPC endpoint. Send POST requests with JSON and the bearer header; it returns application/json. It supports MCP protocol versions 2025-06-18, 2025-03-26, and 2024-11-05.

{
  "mcpServers": {
    "vinotify": {
      "url": "https://vinotify.me/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

For a client that uses the standard JSON-RPC flow, call initialize, then tools/list, and use tools/call for a tool. Notifications are accepted without a response body.

Write tools are exposed only for a write-scoped token while the server write flag is enabled:

create_search.market accepts these verified market codes: uk, ie, fr, de, es, it, nl, be, at, lu, pt, us, au, pl, cz, se, dk, fi, gr, hr, hu, ro, si, sk, ee, lv, lt. Its filter field bounds are: name up to 100 characters; search_text up to 200; price fields from 0 to 10000; brand up to 200; size and blocked_sellers up to 500; excluded and included keywords up to 300; condition_filter up to 10 strings.

Dashboard token-management routes use the authenticated dashboard user. Discovery and event routes use the bearer header shown above.

For event routes, cursor defaults to 0-0 and is limited to 64 characters; limit defaults to 50 and is capped at 100; wait and wait_seconds are bounded to 30 seconds.

GET https://vinotify.me/api/v1/integrations/events?search_id=42&cursor=0-0&wait=30
Authorization: Bearer YOUR_TOKEN

{
  "schema_version": 2,
  "search_id": 42,
  "events": [
    {
      "schema_version": 2,
      "event_id": "evt_…",
      "detected_at": "2026-09-08T12:00:00+00:00",
      "search_id": 42,
      "item_id": "123456789",
      "search_name": "Nike trainers",
      "market": "uk",
      "currency": "GBP",
      "items": [{
        "id": "123456789",
        "item_id": "123456789",
        "price": 55,
        "currency": "GBP",
        "title": "Nike trainers",
        "url": "https://www.vinted.co.uk/items/123456789"
      }],
      "cursor": "1725796800000-0"
    }
  ],
  "cursor": "0-0",
  "next_cursor": "1725796800000-0",
  "has_more": false
}

Vinotify delivers new items two ways. Push posts each batch to a URL you own as soon as it is found. Pull lets your consumer read an event feed on its own schedule. Push is the lower-latency option; pull is the one that can catch up after downtime. Both require the Pro plan.

Push: outbound POST

Each Pro search has its own webhook secret. Read it, and set the destination that receives deliveries, with these routes. Both authenticate with your dashboard session rather than a bearer token, because they configure the search itself.

The destination must be a public HTTPS endpoint. Vinotify validates it when you save it and again immediately before each delivery, and rejects addresses that resolve to private or internal networks.

Vinotify posts this body when a search finds new items:

POST https://your-endpoint.example.com/vinotify
Content-Type: application/json

{
  "event": "new_items",
  "search_id": 42,
  "search_name": "Carhartt jackets",
  "item_count": 2,
  "items": [ /* matching listings */ ]
}

Push delivery is best effort and is not retried. Respond quickly and queue the work on your side. If you need a guarantee that nothing is missed, run the pull feed below alongside it, or fall back to the /webhook/latest route above.

Pull: the event feed

The bearer-authenticated event feed is the durable option. Poll https://vinotify.me/api/v1/integrations/events, or the per-search route /api/v1/integrations/searches/{search_id}/events, with wait=30 to hold the connection open until something arrives.

Events are delivered at least once, so a retry can repeat an event_id. Deduplicate on that value and persist next_cursor after every response. Streams keep 48 hours of history and 10,000 entries by default; a cursor older than the retained window returns 410 cursor_expired with reset_cursor: 0-0.

The event envelope contains schema_version, event_id, detected_at, search_id, item_id, market, currency, and an items array. Item fields can include id, item_id, price, currency, title, brand, size, condition, condition_code, url, and photo when present.

• Default request budget: 240 requests per minute per token.
• Default concurrent long-poll budget: 12 per token.
• Write budget: 10 attempted writes per minute and 100 per day per token.
• MCP discovery and list_searches cap active searches at 50; whats_new caps the combined response at 200 events.
• These budgets are configurable server-side. The values above are the source defaults.