> ## 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.

# Update a query

> A real patch: **a key you do not send is left alone**, and a key sent as `null` clears it. The difference matters — sending `sources` rewrites every child Watch, and a recreated Watch has no poll baseline, so its next tick re-emits every currently matching result as new. The searches that happened to is what `resetSearches` names in the response.



## OpenAPI

````yaml /openapi.json patch /v1/queries/{id}
openapi: 3.1.0
info:
  title: Nephia API
  description: >-
    The brand-monitoring API. Create a **Query** and it polls the live Sources
    (X, Reddit, Youtube, TikTok, Bluesky, Hacker News, Mastodon, Lemmy, GitHub,
    Product Hunt, Stack Overflow, RSS, AI answers — and Vinted) on an interval,
    keeps what matches, reads each mention for sentiment and intent, sorts it
    into your buckets and answers your own agent step over it. Read the result
    back as **mentions** — `GET /v1/mentions` across the whole Account, or per
    Query — or have it pushed to you as signed webhook events and delivery
    channels. A search can carry several terms at once, OR'd into one upstream
    request at one tick's cost. Authenticate with an API key on your Account.
    Monitoring is sold as a subscription — queries, terms, freshness and AI —
    with credits as the meter underneath; credit packs are overflow and never
    change a limit. Reading your own mentions is free; the semantic search mode
    and the AI passes are what meter. Request quota is per Account (all API keys
    share one bucket), by Plan: Free 60/min, Solo 350/min, Growth 700/min, Pro
    1200/min.
  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: Mentions
    description: Everything your Queries caught, across every Source
  - name: Queries
    description: The saved searches that do the catching — read, create, edit, pause
  - name: AI
    description: Group, classify, agent and summarise passes over items you name
  - name: X — Watches
    description: X watches, events, and activity
  - name: Reddit — Watches
    description: Reddit watches, events, and activity
  - name: Youtube — Watches
    description: Youtube watches, events, and activity
  - name: TikTok — Watches
    description: TikTok watches, events, and activity
  - name: Bluesky — Watches
    description: Bluesky watches, events, and activity
  - name: Hacker News — Watches
    description: Hacker News watches, events, and activity
  - name: Mastodon — Watches
    description: Mastodon watches, events, and activity
  - name: Lemmy — Watches
    description: Lemmy watches, events, and activity
  - name: GitHub — Watches
    description: GitHub watches, events, and activity
  - name: Product Hunt — Watches
    description: Product Hunt watches, events, and activity
  - name: Stack Overflow — Watches
    description: Stack Overflow watches, events, and activity
  - name: RSS — Watches
    description: RSS watches, events, and activity
  - name: AI answers — Watches
    description: AI answers watches, runs, events, and activity
  - name: Vinted — Watches
    description: Vinted watches, events, and activity
  - name: Vinted — Analytics
    description: Observed price history and per-day market statistics
paths:
  /v1/queries/{id}:
    patch:
      tags:
        - Queries
      summary: Update a query
      description: >-
        A real patch: **a key you do not send is left alone**, and a key sent as
        `null` clears it. The difference matters — sending `sources` rewrites
        every child Watch, and a recreated Watch has no poll baseline, so its
        next tick re-emits every currently matching result as new. The searches
        that happened to is what `resetSearches` names in the response.
      operationId: patchV1QueriesById
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                refreshIntervalSeconds:
                  type: integer
                  exclusiveMinimum: 0
                webhookUrl:
                  anyOf:
                    - type: string
                      const: ''
                    - type: string
                      format: uri
                    - type: 'null'
                aiEnabled:
                  type: boolean
                aiPreset:
                  type:
                    - string
                    - 'null'
                  enum:
                    - product-model
                    - theme-sentiment
                    - seller
                    - duplicates
                    - custom
                    - null
                aiPrompt:
                  type:
                    - string
                    - 'null'
                  maxLength: 400
                aiStep:
                  oneOf:
                    - $ref: '#/components/schemas/AgentStep'
                    - type: 'null'
                sentimentEnabled:
                  type: boolean
                coBrandsEnabled:
                  type: boolean
                muteRules:
                  type: array
                  items:
                    anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 60
                      - type: object
                        properties:
                          target:
                            type: string
                            enum:
                              - text
                              - title
                              - body
                              - author
                              - community
                          value:
                            type: string
                            minLength: 1
                            maxLength: 60
                          source:
                            type:
                              - string
                              - 'null'
                            enum:
                              - x
                              - reddit
                              - youtube
                              - tiktok
                              - bluesky
                              - hackernews
                              - mastodon
                              - lemmy
                              - github
                              - producthunt
                              - stackoverflow
                              - rss
                              - ai_answers
                              - vinted
                              - null
                          match:
                            type: string
                            enum:
                              - word
                              - contains
                              - exact
                        required:
                          - value
                  maxItems: 50
                vipAuthors:
                  type: array
                  items:
                    anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 60
                      - type: object
                        properties:
                          handle:
                            type: string
                            minLength: 1
                            maxLength: 60
                          source:
                            type:
                              - string
                              - 'null'
                            enum:
                              - x
                              - reddit
                              - youtube
                              - tiktok
                              - bluesky
                              - hackernews
                              - mastodon
                              - lemmy
                              - github
                              - producthunt
                              - stackoverflow
                              - rss
                              - ai_answers
                              - vinted
                              - null
                          note:
                            type:
                              - string
                              - 'null'
                            maxLength: 120
                        required:
                          - handle
                  maxItems: 100
                rules:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                        minLength: 1
                        maxLength: 60
                      enabled:
                        type: boolean
                      source:
                        type:
                          - string
                          - 'null'
                        enum:
                          - x
                          - reddit
                          - youtube
                          - tiktok
                          - bluesky
                          - hackernews
                          - mastodon
                          - lemmy
                          - github
                          - producthunt
                          - stackoverflow
                          - rss
                          - ai_answers
                          - vinted
                          - null
                      when:
                        anyOf:
                          - type: object
                            properties:
                              kind:
                                type: string
                                const: item
                              all:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    field:
                                      type: string
                                      minLength: 1
                                    op:
                                      type: string
                                      enum:
                                        - eq
                                        - neq
                                        - lt
                                        - lte
                                        - gt
                                        - gte
                                        - contains
                                        - not_contains
                                        - word
                                        - in
                                        - exists
                                        - similar_to
                                    value:
                                      anyOf:
                                        - type: string
                                        - type: number
                                        - type: boolean
                                        - type: array
                                          items:
                                            type: string
                                        - type: object
                                          properties:
                                            text:
                                              type: string
                                            threshold:
                                              type: number
                                          required:
                                            - text
                                  required:
                                    - field
                                    - op
                                    - value
                                minItems: 1
                                maxItems: 8
                            required:
                              - kind
                              - all
                          - type: object
                            properties:
                              kind:
                                type: string
                                const: volume
                              window:
                                type: string
                                enum:
                                  - 1h
                                  - 24h
                              min:
                                type: integer
                                exclusiveMinimum: 0
                              multiple:
                                type: number
                                minimum: 1
                            required:
                              - kind
                              - window
                              - min
                              - multiple
                          - type: object
                            properties:
                              kind:
                                type: string
                                const: sentiment_shift
                              window:
                                type: string
                                enum:
                                  - 1h
                                  - 24h
                              min:
                                type: integer
                                exclusiveMinimum: 0
                              multiple:
                                type: number
                                minimum: 1
                            required:
                              - kind
                              - window
                              - min
                              - multiple
                      then:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                                - notify
                                - webhook
                                - mark
                                - stop
                            channelIds:
                              type: array
                              items:
                                type: string
                                format: uuid
                            label:
                              type: string
                              enum:
                                - to_reply
                                - starred
                                - flagged
                                - hidden
                          required:
                            - type
                        minItems: 1
                        maxItems: 4
                    required:
                      - name
                      - when
                      - then
                  maxItems: 20
                webhookMode:
                  type: string
                  enum:
                    - all
                    - rules
                channels:
                  type: array
                  items:
                    type: object
                    properties:
                      channelId:
                        type: string
                        format: uuid
                      mode:
                        type: string
                        enum:
                          - instant
                          - hourly
                          - daily
                          - daily_brief
                          - weekly_report
                    required:
                      - channelId
                      - mode
                  maxItems: 5
                globalCriteria:
                  type: object
                  properties:
                    market:
                      type: string
                      minLength: 1
                    query:
                      type: string
                    priceMin:
                      type: number
                    priceMax:
                      type: number
                    sort:
                      type: string
                    page:
                      type: number
                    perPage:
                      type: number
                    filters:
                      type: object
                      additionalProperties: {}
                    match:
                      type: string
                      enum:
                        - platform
                        - word
                        - contains
                    terms:
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 60
                      minItems: 2
                  required:
                    - market
                sources:
                  type: array
                  items:
                    type: object
                    properties:
                      source:
                        type: string
                        enum:
                          - x
                          - reddit
                          - youtube
                          - tiktok
                          - bluesky
                          - hackernews
                          - mastodon
                          - lemmy
                          - github
                          - producthunt
                          - stackoverflow
                          - rss
                          - ai_answers
                          - vinted
                      enabled:
                        type: boolean
                      searches:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            label:
                              type:
                                - string
                                - 'null'
                              maxLength: 80
                            overridesEnabled:
                              type: boolean
                            overrides:
                              type: object
                              properties:
                                market:
                                  type: string
                                  minLength: 1
                                query:
                                  type: string
                                priceMin:
                                  type: number
                                priceMax:
                                  type: number
                                sort:
                                  type: string
                                page:
                                  type: number
                                perPage:
                                  type: number
                                filters:
                                  type: object
                                  additionalProperties: {}
                                match:
                                  type: string
                                  enum:
                                    - platform
                                    - word
                                    - contains
                                terms:
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                    maxLength: 60
                                  minItems: 2
                      refreshIntervalSeconds:
                        type:
                          - integer
                          - 'null'
                        exclusiveMinimum: 0
                    required:
                      - source
                      - enabled
                  minItems: 1
                schedule:
                  type:
                    - object
                    - 'null'
                  properties:
                    startsAt:
                      type:
                        - string
                        - 'null'
                      format: date-time
                    endsAt:
                      type:
                        - string
                        - 'null'
                      format: date-time
                    timezone:
                      type: string
                      minLength: 1
                      maxLength: 64
                  required:
                    - startsAt
                    - endsAt
                    - timezone
      responses:
        '200':
          description: Query updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryUpdateResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '403':
          description: Your plan does not include this feature
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '404':
          description: Query not found
          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:
  schemas:
    AgentStep:
      type: object
      properties:
        instruction:
          type: string
          minLength: 1
          maxLength: 800
        schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentStepField'
      required:
        - instruction
        - schema
    QueryUpdateResponse:
      type: object
      properties:
        query:
          $ref: '#/components/schemas/Query'
        resetSearches:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                enum:
                  - x
                  - reddit
                  - youtube
                  - tiktok
                  - bluesky
                  - hackernews
                  - mastodon
                  - lemmy
                  - github
                  - producthunt
                  - stackoverflow
                  - rss
                  - ai_answers
                  - vinted
              searchId:
                type: string
              label:
                type: string
            required:
              - source
              - searchId
              - label
      required:
        - query
        - resetSearches
    AgentStepField:
      type: object
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - enum
        description:
          type: string
          maxLength: 200
        values:
          type: array
          items:
            type: string
          maxItems: 12
        maxLength:
          type: integer
          exclusiveMinimum: 0
      required:
        - type
    Query:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        kind:
          type: string
          enum:
            - catalog
            - listening
        globalCriteria:
          type: object
          additionalProperties: {}
        refreshIntervalSeconds:
          type: number
        sources:
          type: array
          items:
            $ref: '#/components/schemas/QuerySource'
        webhookUrl:
          type:
            - string
            - 'null'
        webhookMode:
          type: string
          enum:
            - all
            - rules
        aiEnabled:
          type: boolean
        aiPreset:
          type:
            - string
            - 'null'
        aiPrompt:
          type:
            - string
            - 'null'
        aiStep:
          type:
            - object
            - 'null'
          additionalProperties: {}
        sentimentEnabled:
          type: boolean
        coBrandsEnabled:
          type: boolean
        muteRules:
          type: array
          items: {}
        vipAuthors:
          type: array
          items: {}
        rules:
          type: array
          items: {}
        schedule:
          type:
            - object
            - 'null'
          additionalProperties: {}
        isActive:
          type: boolean
        pausedReason:
          type:
            - string
            - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - id
        - name
        - kind
        - globalCriteria
        - refreshIntervalSeconds
        - sources
        - webhookUrl
        - webhookMode
        - aiEnabled
        - aiPreset
        - aiPrompt
        - aiStep
        - sentimentEnabled
        - coBrandsEnabled
        - muteRules
        - vipAuthors
        - rules
        - schedule
        - isActive
        - pausedReason
        - createdAt
        - updatedAt
    QuerySource:
      type: object
      properties:
        source:
          type: string
          enum:
            - x
            - reddit
            - youtube
            - tiktok
            - bluesky
            - hackernews
            - mastodon
            - lemmy
            - github
            - producthunt
            - stackoverflow
            - rss
            - ai_answers
            - vinted
        enabled:
          type: boolean
        searches:
          type: array
          items:
            $ref: '#/components/schemas/QuerySearch'
        refreshIntervalSeconds:
          type:
            - number
            - 'null'
      required:
        - source
        - enabled
        - searches
        - refreshIntervalSeconds
    QuerySearch:
      type: object
      properties:
        id:
          type: string
        label:
          type:
            - string
            - 'null'
        overridesEnabled:
          type: boolean
        overrides:
          type: object
          additionalProperties: {}
        resolvedCriteria:
          type: object
          additionalProperties: {}
      required:
        - id
        - label
        - overridesEnabled
        - overrides
        - resolvedCriteria
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key created from the Nephia dashboard for your Account.

````