openapi: 3.0.3
info:
  title: BuiltWith Relationships API
  description: >
    Website interconnection data revealing domain relationships via shared IPs,
    analytics identifiers, and other attributes. Supports up to 16 domains per
    request and pagination with up to 500 relationships per page.
    1 API credit per 500 relationships returned.
  version: rv4
  contact:
    name: BuiltWith Support
    url: https://builtwith.com/contact
  termsOfService: https://builtwith.com/terms
  license:
    name: Commercial
    url: https://builtwith.com/plans
externalDocs:
  description: BuiltWith Relationships API Documentation
  url: https://api.builtwith.com/relationships-api
servers:
  - url: https://api.builtwith.com/rv4
    description: BuiltWith Relationships API v4

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:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: KEY
    apiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: "Format: 'Authorization: API {key}'"

  parameters:
    KEY:
      name: KEY
      in: query
      required: false
      schema:
        type: string
        format: uuid
        example: "00000000-0000-0000-0000-000000000000"

    LOOKUP:
      name: LOOKUP
      in: query
      description: Domain or comma-separated list of up to 16 domains
      required: true
      schema:
        type: string
        example: "builtwith.com"

    OFFSET:
      name: OFFSET
      in: query
      description: Pagination offset; use next_skip value from previous response
      required: false
      schema:
        type: integer
        example: 500

    IP:
      name: IP
      in: query
      description: Set to 'yes' to include IP address data in results
      required: false
      schema:
        type: string
        enum: ["yes"]

  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'

    Relationship:
      type: object
      properties:
        Domain:
          type: string
          description: The queried domain
        Identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'

    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'

    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:
    BadRequest:
      description: Bad request — invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'