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

> Creates a Query and the child Watches that poll for it. The body, the plan limits, the interval floors and the multi-term rules are **exactly** the ones the dashboard applies — a Query this refuses is one the Configure screen would refuse too, with the same error code. Pass `backfill: true` to run one immediate, non-delivering poll per enabled source so the Query is not empty on day one: charged one tick per source at its rate, events come back marked `seeded`, and no webhook or channel fires.



## OpenAPI

````yaml /openapi.json post /v1/queries
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:
    post:
      tags:
        - Queries
      summary: Create a query
      description: >-
        Creates a Query and the child Watches that poll for it. The body, the
        plan limits, the interval floors and the multi-term rules are
        **exactly** the ones the dashboard applies — a Query this refuses is one
        the Configure screen would refuse too, with the same error code. Pass
        `backfill: true` to run one immediate, non-delivering poll per enabled
        source so the Query is not empty on day one: charged one tick per source
        at its rate, events come back marked `seeded`, and no webhook or channel
        fires.
      operationId: postV1Queries
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      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
                spikeAlert:
                  type:
                    - string
                    - 'null'
                  enum:
                    - low
                    - medium
                    - high
                    - null
                backfill:
                  type: boolean
                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
              required:
                - name
                - refreshIntervalSeconds
                - globalCriteria
                - sources
      responses:
        '201':
          description: Query created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '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
        '409':
          description: Plan limit reached
          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:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        Unique key (e.g. UUID) making this POST safe to retry for 24 hours.
        Replays return the original response with an `Idempotency-Replayed:
        true` header; reusing a key with a different body returns 422.
  schemas:
    AgentStep:
      type: object
      properties:
        instruction:
          type: string
          minLength: 1
          maxLength: 800
        schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentStepField'
      required:
        - instruction
        - schema
    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
    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
    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.

````