> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a watch

> Subscribe to listing changes matching search criteria. Webhook delivery and billing are documented separately.



## OpenAPI

````yaml /openapi.json post /v1/vinted/watches
openapi: 3.1.0
info:
  title: Nephia API
  description: >-
    B2B API for structured data from live Sources (Vinted, X, Reddit).
    Authenticate with an API key on your Account. Pull endpoints charge credits
    per request. Watches poll on an interval and deliver webhook events. Product
    request quota is per Account (all API keys share one bucket), by Plan: Free
    60/min, Starter 350/min, Growth 700/min, Pro 1,200/min. Credit packs do not
    raise the quota.
  version: 1.0.0
servers:
  - url: https://api.nephia.cc
    description: Production
  - url: http://localhost:3000
    description: Local
security:
  - ApiKeyAuth: []
tags:
  - name: Account
    description: Account balance
  - name: Vinted — Search
    description: Vinted catalog search
  - name: Vinted — Items
    description: Vinted listing detail
  - name: Vinted — Users
    description: Vinted sellers and wardrobes
  - name: Vinted — Reference
    description: Vinted filter metadata
  - name: Vinted — Watches
    description: Vinted watches, events, and activity
  - name: X — Tweets
    description: Tweet lookup, replies, thread, quotes, and engagers
  - name: X — Users
    description: X profiles, timelines, and social graphs
  - name: X — Search
    description: Tweet search
  - name: X — Lists
    description: X list timelines
  - name: X — Trends
    description: Trend places and snapshots
  - name: X — Watches
    description: X watches, events, and activity
  - name: Reddit — Search
    description: Reddit post, subreddit, and user search
  - name: Reddit — Posts
    description: Reddit posts, comments, duplicates, and trending
  - name: Reddit — Subreddits
    description: Subreddit profiles, listings, and rules
  - name: Reddit — Users
    description: Reddit user profiles and activity
  - name: Reddit — Watches
    description: Reddit watches, events, and activity
paths:
  /v1/vinted/watches:
    post:
      tags:
        - Vinted — Watches
      summary: Create a watch
      description: >-
        Subscribe to listing changes matching search criteria. Webhook delivery
        and billing are documented separately.
      operationId: postV1VintedWatches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                market:
                  type: string
                  default: fr
                criteria:
                  type: object
                  properties:
                    market:
                      type: string
                      default: fr
                    query:
                      type: string
                    price_min:
                      type: number
                    price_max:
                      type: number
                    sort:
                      type: string
                    page:
                      type: number
                    per_page:
                      type: number
                      maximum: 96
                    brand_ids:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: number
                    size_ids:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: number
                    catalog_ids:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: number
                    color_ids:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: number
                    status_ids:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: number
                refresh_interval_seconds:
                  type: number
                  minimum: 15
                  maximum: 3600
                webhook_url:
                  type: string
                  format: uri
              required:
                - criteria
                - refresh_interval_seconds
                - webhook_url
      responses:
        '201':
          description: Watch created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  accountId:
                    type: string
                  source:
                    type: string
                    enum:
                      - vinted
                      - x
                      - reddit
                  market:
                    type: string
                  criteria:
                    type: object
                    properties:
                      market:
                        type: string
                      query:
                        type: string
                      priceMin:
                        type: number
                      priceMax:
                        type: number
                      sort:
                        type: string
                      page:
                        type: number
                      perPage:
                        type: number
                      filters:
                        type: object
                        additionalProperties: {}
                    required:
                      - market
                  criteriaHash:
                    type: string
                  refreshIntervalSeconds:
                    type: number
                  webhookUrl:
                    type: string
                  billingMode:
                    type: string
                    enum:
                      - subscription
                      - payg
                      - deferred
                      - metered
                  isActive:
                    type: boolean
                  pausedReason:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                  - id
                  - accountId
                  - source
                  - market
                  - criteria
                  - criteriaHash
                  - refreshIntervalSeconds
                  - webhookUrl
                  - billingMode
                  - isActive
                  - createdAt
                  - updatedAt
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '409':
          description: Active watch already exists for these criteria
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '429':
          description: >-
            Request quota exceeded. Retry after the `Retry-After` header
            (seconds). Response includes `RateLimit-*` headers (IETF draft-7).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
              example:
                error: Rate limit exceeded
                code: TOO_MANY_REQUESTS
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key created from the Nephia dashboard for your Account.

````