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

# Update audience API

> Rename an audience, replace its membership, or set a re-crawl cadence. Renames are free; sending a definition rebuilds and costs 1 credit.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I refresh a computed audience?">
    Send its `definition` again. Presence of the field triggers a rebuild with no diffing — that is intentional, because an explicit re-`PATCH` is the only way to refresh a point-in-time snapshot. It costs 1 credit. A rename-only patch never touches membership and is free.
  </Accordion>

  <Accordion title="Is there a window where my audience is half-updated?">
    No. Membership replacement is a generation flip: the new set is written in full, and the pointer moves only after a verified complete insert. A reader during an update always sees the complete old membership, never a partial new one.
  </Accordion>

  <Accordion title="What does crawl_cadence do?">
    It schedules re-scans of the audience's member domains so the underlying detection data refreshes as fast as you need it, rather than waiting for the rolling corpus crawl. `weekly` and `daily` require a paid plan and are metered at 1 credit per dispatched domain. Set it to `none` to stop.
  </Accordion>

  <Accordion title="Can I edit a signal audience?">
    Not yet. Signal audiences are rejected on a definition change — save a new audience from Signals instead. `type` and `kind` are immutable on every audience.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml PATCH /v1/segments/{id}
openapi: 3.1.0
info:
  title: TechnologyChecker API
  description: >-
    Discover technology stacks, track market trends, and enrich data with
    company intelligence.
  version: 1.0.0
  contact:
    name: TechnologyChecker Support
    email: support@technologychecker.io
    url: https://technologychecker.io
servers:
  - url: https://api.technologychecker.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Domain technologies
    description: Look up technologies detected on any domain
  - name: Technology data
    description: Search, look up, and get details on tracked technologies
  - name: Market intelligence
    description: Technology stats, trends, and market share
  - name: Company data
    description: Firmographic and company intelligence
  - name: Live detection
    description: Real-time technology detection with browser rendering
  - name: Signals
    description: >-
      Intent signals derived from technology state transitions: who adopted, who
      churned, who switched, and who has a gap in their stack.
  - name: Alerts
    description: >-
      Saved signal queries delivered to your webhook. Every signal you can
      query, you can subscribe to.
  - name: Audiences
    description: >-
      Saved groups of domains — uploaded lists or computed recipes — that you
      can profile, slice and monitor.
  - name: Lead lists
    description: >-
      Build and export targeted domain lists combining technology detection with
      company data.
paths:
  /v1/segments/{id}:
    patch:
      tags:
        - Audiences
      summary: Update audience API
      description: >-
        Rename an audience, replace its membership, or set its crawl cadence.


        **Renaming alone is free** and never touches membership. Sending
        `definition` rebuilds the audience and **costs 1 credit** — presence of
        the field triggers the rebuild with no diffing, which is deliberately
        the only way to refresh a snapshot. Sending `domains` replaces an
        uploaded list's membership, also free.


        Membership replacement is a generation flip: the new set is written in
        full and the pointer moves only after a verified complete insert, so a
        reader mid-update always sees the complete old membership rather than a
        partial new one.


        `type` and `kind` are immutable. Signal audiences cannot be edited —
        save a new one from Signals instead.
      operationId: updateAudience
      parameters:
        - name: id
          in: path
          required: true
          description: The audience id.
          schema:
            type: string
            example: seg_8f3a2c1b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 120
                domains:
                  type: array
                  items:
                    type: string
                  description: List audiences only. Full replacement, not a delta.
                definition:
                  $ref: '#/components/schemas/AudienceDefinition'
                crawl_cadence:
                  type: string
                  enum:
                    - none
                    - weekly
                    - daily
                  description: >-
                    Re-scan cadence for this audience's members. Weekly and
                    daily require a paid plan and are metered at 1 credit per
                    dispatched domain.
              example:
                name: US ecommerce, 51-200 (refreshed)
                crawl_cadence: weekly
      responses:
        '200':
          description: The updated audience
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      segment:
                        $ref: '#/components/schemas/Audience'
                      coverage:
                        type: object
                        properties:
                          in_corpus:
                            type: integer
                            nullable: true
                          total:
                            type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/QueryTimeout'
components:
  schemas:
    AudienceDefinition:
      type: object
      description: >-
        A computed audience recipe. `kind` selects which shape applies;
        firmographic keys may be combined with any kind to narrow it further.
      properties:
        kind:
          type: string
          enum:
            - firmo
            - technology
            - signal
          default: firmo
          description: >-
            `firmo` builds from company attributes alone. `technology` builds
            from a technology expression. `signal` builds from a saved adoption
            or churn query.
        technologies:
          type: object
          description: >-
            Required for `kind: technology`. Combine technology ids at domain
            grain.
          properties:
            or:
              type: array
              items:
                type: integer
              description: Domains running any of these.
            and:
              type: array
              items:
                type: integer
              description: Domains running all of these.
            and_not:
              type: array
              items:
                type: integer
              description: Domains running none of these.
          example:
            and:
              - 2184
            and_not:
              - 402
        signal:
          type: object
          description: >-
            Required for `kind: signal`. Only adoption and churn queries can be
            saved as audiences.
          properties:
            type:
              type: string
              enum:
                - adoption
                - churn
            technology_id:
              type: integer
              description: Exactly one of `technology_id` or `category_id`.
            category_id:
              type: integer
            window:
              type: integer
              default: 30
              minimum: 1
              maximum: 365
            min_confidence:
              type: number
              format: float
              default: 0.5
            include_first_seen:
              type: boolean
              default: false
          example:
            type: adoption
            technology_id: 2184
            window: 90
        country:
          type: string
          example: united states
        city:
          type: string
        state:
          type: string
        industry:
          type: string
        industry_code:
          type: integer
        employees:
          type: string
          example: 51-200
        company_type:
          type: string
        founded_min:
          type: integer
        founded_max:
          type: integer
        has_email:
          type: boolean
        has_phone:
          type: boolean
        social:
          type: string
        language:
          type: string
        web_country:
          type: string
    Audience:
      type: object
      properties:
        id:
          type: string
          example: seg_8f3a2c1b
        name:
          type: string
          example: YC W25 portfolio
        type:
          type: string
          enum:
            - filter
            - list
          description: >-
            `list` for an uploaded set of domains, `filter` for a computed
            recipe. Immutable.
          example: list
        kind:
          type: string
          enum:
            - upload
            - firmo
            - technology
            - signal
          description: >-
            How membership was produced. `upload` is a pasted list; the rest are
            computed recipes.
          example: upload
        definition:
          type: object
          nullable: true
          description: The recipe that produced membership. `null`-ish for uploads.
        domain_count:
          type: integer
          description: Members in the current generation.
          example: 5914
        status:
          type: string
          enum:
            - uploading
            - ready
            - failed
          example: ready
        membership_at:
          type: string
          nullable: true
          description: >-
            When membership was last built. Computed audiences are point-in-time
            snapshots — re-send the definition to refresh.
          example: '2026-07-29T10:14:02.000Z'
        matched_total:
          type: integer
          nullable: true
        crawl_cadence:
          type: string
          enum:
            - none
            - weekly
            - daily
          default: none
          example: none
        last_dispatched_at:
          type: string
          nullable: true
        created_at:
          type: string
          example: '2026-07-29T10:12:00.000Z'
        updated_at:
          type: string
          example: '2026-07-29T10:14:02.000Z'
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: Missing or invalid API key
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: >-
                Provide exactly one scope: technology_id, technology or
                category_id.
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PaymentRequired:
      description: Not enough credits, or the plan does not include this feature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits for this request.
              details:
                required: 1
                available: 0
    Forbidden:
      description: The plan does not allow this action, or a plan limit was reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: PLAN_LIMIT
              message: >-
                Your plan allows up to 2 saved audiences. Delete one to create
                another.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    QueryTimeout:
      description: >-
        The query exceeded the 30-second server-side limit. Narrow the query and
        retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: SEGMENT_QUERY_TIMEOUT
              message: The segment query exceeded the 30s server-side limit.
              details:
                suggestion: >-
                  Narrow the segment — add an employees band, industry, or city
                  — and try again.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in format `tapi_live_[32-char]` (live) or `tapi_test_[32-char]`
        (test)

````