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

# Run an AI pass over items

> Runs one of four passes over up to 200 items: **group** them by a plain-language instruction, **classify** them into buckets you define, run an **agent** step (your instruction plus your schema, answered per item), or **summarise** the set.

Items come from `items` inline, or from `watch_id` — the recent events of a watch you own.

Costs 1 credit per 50 items for group, classify and summarise, and 1 credit per 25 items for agent — the agent's output is generated text per field, not a single verdict. `meta.credits_used` reports what was actually charged: a batch the provider could not answer is not billed.



## OpenAPI

````yaml /openapi.json post /v1/analyses
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/analyses:
    post:
      tags:
        - AI
      summary: Run an AI pass over items
      description: >-
        Runs one of four passes over up to 200 items: **group** them by a
        plain-language instruction, **classify** them into buckets you define,
        run an **agent** step (your instruction plus your schema, answered per
        item), or **summarise** the set.


        Items come from `items` inline, or from `watch_id` — the recent events
        of a watch you own.


        Costs 1 credit per 50 items for group, classify and summarise, and 1
        credit per 25 items for agent — the agent's output is generated text per
        field, not a single verdict. `meta.credits_used` reports what was
        actually charged: a batch the provider could not answer is not billed.
      operationId: postV1Analyses
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalysesRequest'
      responses:
        '200':
          description: Analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysesResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
        '404':
          description: Watch 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
        '503':
          description: AI analysis is not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
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:
    AnalysesRequest:
      type: object
      properties:
        kind:
          type: string
          enum:
            - group
            - classify
            - agent
            - summarise
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisItem'
          minItems: 1
          maxItems: 200
        watch_id:
          type: string
          format: uuid
        since:
          type: string
          format: date-time
        limit:
          type: integer
          minimum: 1
          maximum: 200
        instruction:
          type: string
          minLength: 1
          maxLength: 800
        schema:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentStepField'
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisBucket'
          minItems: 1
          maxItems: 20
        question:
          type: string
          minLength: 1
          maxLength: 500
      required:
        - kind
    AnalysesResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            kind:
              type: string
            item_count:
              type: number
            batches:
              type: number
            credits_used:
              type: number
            model:
              type:
                - string
                - 'null'
          required:
            - kind
            - item_count
            - batches
            - credits_used
            - model
        data:
          type: object
          properties:
            groups:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  item_ids:
                    type: array
                    items:
                      type: string
                  rationale:
                    type: string
                  flag:
                    type:
                      - string
                      - 'null'
                  tone:
                    type: string
                required:
                  - title
                  - item_ids
                  - rationale
                  - flag
                  - tone
            verdicts:
              type: array
              items:
                type: object
                properties:
                  item_id:
                    type: string
                  bucket_id:
                    type:
                      - string
                      - 'null'
                  confidence:
                    type: number
                  rationale:
                    type: string
                  sentiment:
                    type:
                      - string
                      - 'null'
                required:
                  - item_id
                  - bucket_id
                  - confidence
                  - rationale
                  - sentiment
            outputs:
              type: array
              items:
                type: object
                properties:
                  item_id:
                    type: string
                  output:
                    type:
                      - object
                      - 'null'
                    additionalProperties: {}
                required:
                  - item_id
                  - output
            text:
              type: string
      required:
        - meta
        - data
    AnalysisItem:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        source:
          type: string
          enum:
            - x
            - reddit
            - youtube
            - tiktok
            - bluesky
            - hackernews
            - mastodon
            - lemmy
            - github
            - producthunt
            - stackoverflow
            - rss
            - ai_answers
            - vinted
        title:
          type: string
        body:
          type: string
        meta:
          type: object
          additionalProperties:
            type: string
      required:
        - id
        - source
        - title
    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
    AnalysisBucket:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        rule:
          type: string
          minLength: 1
      required:
        - id
        - label
        - rule
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key created from the Nephia dashboard for your Account.

````