openapi: 3.0.3
info:
  title: BuiltWith Change Bulk Processing Domain Relationships API
  description: 'Track technology additions and removals on websites with business context. Returns AI-generated summaries explaining the business significance of technology changes. Credits are only consumed when changes are found.

    '
  version: change1
  contact:
    name: BuiltWith Support
    url: https://builtwith.com/contact
  termsOfService: https://builtwith.com/terms
  license:
    name: Commercial
    url: https://builtwith.com/plans
servers:
- url: https://api.builtwith.com/change1
  description: BuiltWith Change API v1
security:
- apiKeyQuery: []
- apiKeyHeader: []
tags:
- name: Domain Relationships
  description: Identify domain interconnections via shared identifiers
paths:
  /api.json:
    get:
      summary: Get domain relationships (JSON)
      description: 'Returns relationships for one or more domains based on shared identifiers such as analytics IDs, IP addresses, and other attributes. Paginate using the next_skip value from the response.

        '
      operationId: getDomainRelationshipsJson
      tags:
      - Domain Relationships
      parameters:
      - $ref: '#/components/parameters/KEY'
      - $ref: '#/components/parameters/LOOKUP'
      - $ref: '#/components/parameters/OFFSET'
      - $ref: '#/components/parameters/IP'
      responses:
        '200':
          description: Domain relationship data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationshipsResponse'
              example:
                results: 1250
                max_per_page: 500
                next_skip: 500
                more_results: true
                Relationships:
                - Domain: builtwith.com
                  Identifiers:
                  - Type: google-analytics
                    Value: UA-12345678-1
                    First: 1451606400000
                    Last: 1748736000000
                    Matches:
                    - Domain: related-site.com
                      First: 1451606400000
                      Last: 1748736000000
                      Overlap: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api.xml:
    get:
      summary: Get domain relationships (XML)
      operationId: getDomainRelationshipsXml
      tags:
      - Domain Relationships
      parameters:
      - $ref: '#/components/parameters/KEY'
      - $ref: '#/components/parameters/LOOKUP'
      - $ref: '#/components/parameters/OFFSET'
      responses:
        '200':
          description: Domain relationships in XML
          content:
            application/xml:
              schema:
                type: object
  /api.csv:
    get:
      summary: Get domain relationships (CSV)
      operationId: getDomainRelationshipsCsv
      tags:
      - Domain Relationships
      parameters:
      - $ref: '#/components/parameters/KEY'
      - $ref: '#/components/parameters/LOOKUP'
      responses:
        '200':
          description: Domain relationships in CSV
          content:
            text/csv:
              schema:
                type: string
  /api.tsv:
    get:
      summary: Get domain relationships (TSV)
      operationId: getDomainRelationshipsTsv
      tags:
      - Domain Relationships
      parameters:
      - $ref: '#/components/parameters/KEY'
      - $ref: '#/components/parameters/LOOKUP'
      responses:
        '200':
          description: Domain relationships in TSV
          content:
            text/tab-separated-values:
              schema:
                type: string
components:
  parameters:
    OFFSET:
      name: OFFSET
      in: query
      description: Pagination offset; use next_skip value from previous response
      required: false
      schema:
        type: integer
        example: 500
    LOOKUP:
      name: LOOKUP
      in: query
      description: Domain or comma-separated list of up to 16 domains
      required: true
      schema:
        type: string
        example: builtwith.com
    IP:
      name: IP
      in: query
      description: Set to 'yes' to include IP address data in results
      required: false
      schema:
        type: string
        enum:
        - 'yes'
    KEY:
      name: KEY
      in: query
      required: false
      schema:
        type: string
        format: uuid
        example: 00000000-0000-0000-0000-000000000000
  schemas:
    RelationshipsResponse:
      type: object
      properties:
        results:
          type: integer
          description: Total number of relationship results
        max_per_page:
          type: integer
          description: Maximum results per page
          example: 500
        next_skip:
          type: integer
          description: Offset value for retrieving the next page
        more_results:
          type: boolean
          description: Whether additional pages of results exist
        Relationships:
          type: array
          items:
            $ref: '#/components/schemas/Relationship'
    Identifier:
      type: object
      properties:
        Type:
          type: string
          description: Identifier type (e.g. google-analytics, ip-address)
          example: google-analytics
        Value:
          type: string
          description: Identifier value
          example: UA-12345678-1
        First:
          type: integer
          format: int64
          description: First detection timestamp (ms)
        Last:
          type: integer
          format: int64
          description: Last detection timestamp (ms)
        Matches:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipMatch'
    Relationship:
      type: object
      properties:
        Domain:
          type: string
          description: The queried domain
        Identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
    RelationshipMatch:
      type: object
      properties:
        Domain:
          type: string
          description: Related domain sharing the identifier
        First:
          type: integer
          format: int64
          description: First detection timestamp (ms)
        Last:
          type: integer
          format: int64
          description: Last detection timestamp (ms)
        Overlap:
          type: boolean
          description: Whether the domains simultaneously used the identifier
    ErrorResponse:
      type: object
      properties:
        Errors:
          type: array
          items:
            type: object
            properties:
              Code:
                type: integer
              Message:
                type: string
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: KEY
    apiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: ''Authorization: API {key}'''
externalDocs:
  description: BuiltWith Change API Documentation
  url: https://api.builtwith.com/change-api