General Services Administration Website API

openapi: 3.2.0
info:
  title: Site Scanning Website API
  description: Site Scanning API provides information about sites in the federal web presence.
  version: '2.0'
  contact: {}
servers: []
tags:
- name: Website
paths:
  /websites:
    get:
      operationId: WebsiteController_getResults
      parameters:
      - name: target_url_domain
        required: false
        in: query
        description: '`target_url_domain` is the domain name plus the top-level domain (TLD) of the target url.

          The `target_url` is the url that the scanner starts with. This is in constrast to the `final_url` which

          is the url where the scanner ends up, after following redirects.'
        schema:
          format: uri
          example: gsa.gov
          type: string
      - name: final_url_domain
        required: false
        in: query
        description: '`final_url_domain` is the domain name plus the top-level domain (TLD) of the final url.

          The final url is the url where the scanner ends up, after following redirects. This is in contrast to

          the target url, which is the url the scanner starts with.'
        schema:
          format: uri
          example: gsa.gov
          type: string
      - name: final_url_live
        required: false
        in: query
        description: '`final_url_live` is a boolean that records whether the final url returns an HTTP status code that is in the 2xx

          family.'
        schema:
          example: true
          type: boolean
      - name: target_url_redirects
        required: false
        in: query
        description: '`target_url_redirects` is a boolean that records whether the target url redirects. Another way of thinking about this

          is that when `true`, the target url returned a `3xx` HTTP status code. Technical Note: the scanners have caching disabled, so

          `304` HTTP status codes are not present in the system.'
        schema:
          example: true
          type: boolean
      - name: target_url_agency_owner
        required: false
        in: query
        description: '`target_url_agency_owner` is the agency that owns/operates the website associated with the target url.

          _Note: The agency name must be url encoded (aka %20 encoded)._'
        schema:
          example: Department of Energy
          type: string
      - name: target_url_bureau_owner
        required: false
        in: query
        description: '`target_url_bureau_owner` is the bureau that owns/operates the website associated with the target url.

          _Note: The bureau name must be url encoded (aka %20 encoded)._'
        schema:
          example: Argonne National Laboratory
          type: string
      - name: scan_status
        required: false
        in: query
        description: '`scan_status` captures the status of the scan and any reason for failure (if known). _Note that `unknown_error`

          is reserved for errors that aren''t yet encoded in the system._'
        schema:
          example: completed
          type: string
          enum:
          - address_unreachable
          - completed
          - connection_closed
          - connection_refused
          - connection_reset
          - dns_resolution_error
          - empty_response
          - invalid_response
          - evaluation_failed
          - execution_context_destroyed
          - http2_error
          - invalid_ssl_cert
          - not_applicable
          - page_frame_not_ready
          - skipped
          - ssl_version_cipher_mismatch
          - timeout
          - too_many_redirects
          - invalid_auth_credentials
          - ssl_protocol_error
          - aborted
          - unknown_error
      - name: dap_detected_final_url
        required: false
        in: query
        description: '`dap_detected_final_url` is a boolean that records whether the Digital Analytics Program is detected at the final url.'
        schema:
          example: true
          type: boolean
      - name: page
        required: false
        in: query
        description: 'page denotes the page number of the results to display. The default value and the

          minimum value are 1.


          page works in conjunction with the limit parameter. For example, if there are

          1000 results, and a limit of 10, there would be 100 pages. A value of page=2

          would show you the second page (results 10-19 in a zero-index system).'
        schema:
          $ref: '#/components/schemas/Object'
      - name: limit
        required: false
        in: query
        description: 'limit denotes the number of items that will be returned from the API in the `items` array.

          The default value is 10. The maximum is 100.'
        schema:
          $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: A successful response from the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedWebsiteResponseDto'
        '500':
          description: This response type indicates an internal error.
      tags:
      - Website
      summary: Website controller get results
      x-summary-source: derived
  /websites/{url}:
    get:
      operationId: WebsiteController_getResultByUrl
      parameters:
      - name: url
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: A successful response from the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsiteApiResultDto'
        '404':
          description: This response indicated that there is no matching `target_url` in the database
        '500':
          description: This response type indicates an internal error.
      tags:
      - Website
      summary: Website controller get result by url
      x-summary-source: derived
components:
  schemas:
    Meta:
      type: object
      properties:
        totalItems:
          type: number
          description: '`totalItems` is the total number of items that match the query.'
          example: 1000
        itemCount:
          type: number
          description: '`itemCount` is number of items in the `PaginationResponseDto.items` array.'
          example: 1
        itemsPerPage:
          type: number
          description: '`itemsPerPage` is the number of items per page. This should be the same as the `limit` query parameter.'
          example: 1
        totalPages:
          type: number
          description: '`totalPages` is the total number of pages. Should be equal to `floor(totalItems / itemsPerPage)`'
          example: 1000
        currentPage:
          type: number
          description: '`currentPage` is the page the cursor is currently on.'
          example: 2
      required:
      - totalItems
      - itemCount
      - itemsPerPage
      - totalPages
      - currentPage
    WebsiteApiResultDto:
      type: object
      properties:
        scan_date:
          type: string
          description: '`scan_date` is a datetime string that records when the scan was performed.'
          example: '2020-12-30T00:00:03.821Z'
        secondary_data_dates:
          type: string
          description: '`secondary_data_dates` is a minified JSON object with data freshness dates

            for DAP (Digital Analytics Program) and HTTPS certificate data.

            Both keys are always present; null indicates missing data.'
          example: '{dap:2026-05-16,https:2026-05-21}'
        target_url_domain:
          type: string
          description: '`target_url_domain` is the base domain (domain name + top-level domain) of the target url.'
          example: 18f.gov
        scan_status:
          description: '`scan_status` is the success status of the Core Scan.'
          example: completed
          enum:
          - address_unreachable
          - completed
          - connection_closed
          - connection_refused
          - connection_reset
          - dns_resolution_error
          - empty_response
          - invalid_response
          - evaluation_failed
          - execution_context_destroyed
          - http2_error
          - invalid_ssl_cert
          - not_applicable
          - page_frame_not_ready
          - skipped
          - ssl_version_cipher_mismatch
          - timeout
          - too_many_redirects
          - invalid_auth_credentials
          - ssl_protocol_error
          - aborted
          - unknown_error
          type: string
        final_url:
          type: string
          description: '`final_url` is the url after any redirects from the target url.'
          example: https://18f.gsa.gov/
        final_url_live:
          type: boolean
          description: '`final_url_live` is a boolean representing whether the final url returned a

            2xx family HTTP status code.'
          example: true
        final_url_domain:
          type: string
          description: '`final_url_domain` is the domain name + top-level domain of the final url.'
          example: gsa.gov
        final_url_website:
          type: string
          description: '`final_url_domain` includes the submdomain and the top-level domain of the final url.'
          example: www.gsa.gov
        final_url_MIMEType:
          type: string
          description: '`final_url_MIMEType` is the MIME type of the final url extracted from the Content-Type header.'
          example: text/html
        final_url_same_domain:
          type: string
          description: '`final_url_same_domain` is a boolean field representing whether the final url is in the

            same domain as the target url. If false, this implies a redirect.'
          example: 'false'
        final_url_status_code:
          type: number
          description: '`final_url_status_code` is the HTTP status code of the final url.'
          example: 200
        final_url_same_website:
          type: boolean
          description: '`final_url_same_website` is a boolean that indicates if the final url has a different path or domain

            from the target url.'
          example: false
        target_url_404_test:
          type: boolean
          description: '`target_url_404_test` tests whether the target URL properly handles 404s by called a UUID-based pathname,'
          example: true
        target_url_redirects:
          type: boolean
          description: '`target_url_redirects` is a boolean that indicates whether the target url redirects.'
          example: true
        uswds_usa_classes:
          type: number
          description: '`uswds_usa_classes` is the number of CSS classes found that start with ".usa-".'
          example: 50
        uswds_usa_class_list:
          description: '`uswds_usa_class_list` is the list of USWDS CSS classes detected on the page (sorted).'
          example:
          - usa-accordion
          - usa-banner
          - usa-button
          type: array
          items:
            type: string
        uswds_usa_elements_list:
          description: '`uswds_usa_elements_list` is the list of USWDS custom HTML element tags detected on the page

            (e.g. `usa-banner`). Only elements from a known allow-list are reported.'
          example:
          - usa-banner
          type: array
          items:
            type: string
        uswds_banner_heres_how:
          type: boolean
          description: '`uswds_banner_heres_how` is a boolean indicating whether the "Here''s how you know" banner was detected.'
          example: true
        uswds_string:
          type: number
          description: '`uswds_string` is the number of times the string "uswds" occurs in the HTML source.'
          example: 1
        uswds_tables:
          type: number
          description: '`uswds_tables` is a calculation of the (number of html `<table>` elements) * -10. <table> elements

            are a negative heuristic indicator of the presence of USWDS.'
          example: 0
        uswds_inpage_css:
          type: number
          description: '`uswds_inpage_css` is the number of occurrences of ".usa-" CSS classes in inline html source.'
          example: 0
        uswds_favicon:
          type: number
          description: '`uswds_favicon` is the presence of the USWDS US Flag favicon in HTML source. Presence adds 20 points to

            the USWDS likelihood heuristic.'
          example: 20
        uswds_string_in_css:
          type: number
          description: '`uswds_string_in_css` is the number of occurences of "uswds" in the CSS source.'
          example: 20
        uswds_favicon_in_css:
          type: number
          description: '`uswds_favicon_in_css` is the presence of the USWDS US Flag favicon in CSS source. Presence adds 20 points to

            the uswds likelihood heuristic.'
          example: 0
        uswds_publicsans_font:
          type: number
          description: '`uswds_publicsans_font` is the presence of the Public Sans font in CSS source.

            Presence adds 20 points to the USWDS likelihood heuristic.'
          example: 20
        uswds_source_sans_font:
          type: number
          description: '`uswds_source_sans_font` is the presence of the Source Sans font in CSS soure.

            Presence adds 5 points to the USWDS likelihood heuristic.'
        uswds_semantic_version:
          type: string
          description: '`uswds_semantic_version` is the semantic version string of USWDS.'
          example: 2.9.0
        uswds_version:
          type: number
          description: '`uswds_version` is the presence of the USWDS version in CSS source.

            Presence adds 20 points to the USWDS likelihood heuristic.'
          example: 20
        uswds_count:
          type: number
          description: '`uswds_count` is the total of all USWDS likelihood heuristics in a sum.'
          example: 141
        dap_detected_final_url:
          type: boolean
          description: '`dap_detected_final_url` is a boolean representing the presence of the Digital Analytics Program

            on the final url.'
          example: true
        dap_parameters_final_url:
          type: object
          description: '`dap_parameters_final_url` is the an object with Digital Analytics Program parameter keys and values.'
        og_title_final_url:
          type: string
          description: '`og_title_final_url` is the Open Graph title tag if found on the final url.'
          example: '18F: Digital service delivery | Home'
        og_description_final_url:
          type: string
          description: '`og_description_final_url` is the Open Graph description tag if found on the final url.'
          example: 18F builds effective, user-centric digital services focused on the interaction between government and the people and businesses it serves.
        og_article_published_final_url:
          type: string
          description: '`og_article_published_final_url` is the Open Graph article published tag.'
          example: ''
        og_article_modified_final_url:
          type: string
          description: '`og_article_modified_final_url` is the Open Graph article modified tag.'
          example: ''
        main_element_present_final_url:
          type: boolean
          description: '`main_element_present_final_url` is a boolean indicating whether the <main> element is present at the final url.'
          example: true
        robots_txt_final_url:
          type: string
          description: '`robots_txt_final_url` is the final url of the robots.txt after any redirects.'
          example: https://18f.gsa.gov/robots.txt
        robots_txt_final_url_status_code:
          type: number
          description: '`robots_txt_final_url_status_code` is the HTTP status code of the robots.txt final url.'
          example: 200
        robots_txt_final_url_live:
          type: boolean
          description: '`robots_txt_final_url_live` is a boolean indicating whether the robots.txt final url HTTP is in the 2xx family.'
          example: true
        robots_txt_detected:
          type: boolean
          description: '`robots_txt_detected` is boolean represent whether the robots.txt file is detected.'
          example: true
        robots_txt_final_url_MIMETYPE:
          type: string
          description: '`robots_txt_final_url_MIMETYPE` is the MIME type of the robots.txt page extracted from Content-Type header.'
          example: text/plain
        robots_txt_target_url_redirects:
          type: boolean
          description: '`robots_txt_target_url_redirects` is boolean indicating whether the target robots.txt field redirects.

            Note that the target robots.txt is the target url with robots.txt as the pathname.'
          example: true
        robots_txt_final_url_size_in_bytes:
          type: number
          description: '`robots_txt_final_url_size_in_bytes` is file size of the robots.txt file in bytes.'
          example: 65
        robots_txt_crawl_delay:
          type: number
          description: '`robots_txt_crawl_delay` is the crawl delay value in seconds, if present.'
          example: 3
        sitemap_xml_detected:
          type: boolean
          description: '`sitemap_xml_detected` is a boolean indicating whether the sitemap.xml file is found.'
          example: true
        sitemap_xml_final_url_status_code:
          type: number
          description: '`sitemap_xml_final_url_status_code` is the HTTP status code of the sitemap.xml page.'
          example: 200
        sitemap_xml_final_url:
          type: string
          description: '`sitemap_xml_final_url` is the final url of the sitemap.xml page after any redirects.'
          example: https://18f.gsa.gov/sitemap.xml
        sitemap_xml_final_url_live:
          type: boolean
          description: '`sitemap_xml_final_url_live` is a boolean indicating whether the sitemap.xml final url status code

            is in the 2xx family.'
          example: true
        sitemap_xml_target_url_redirects:
          type: boolean
          description: '`sitemap_xml_target_url_redirects` is a boolean indicating whether the sitemap.xml page redirects. Note that

            the target url is {targetUrl}/sitemap.xml.'
          example: true
        sitemap_xml_final_url_filesize:
          type: number
          description: '`sitemap_xml_final_url_filesize` is a number indicating the filesize of the sitemap.xml page in bytes.'
          example: 95598
        sitemap_xml_final_url_MIMETYPE:
          type: string
          description: '`sitemap_xml_final_url_MIMETYPE` is the MIME type of the sitemap.xml final url extracted from the Content-Type header.'
          example: application/xml
        sitemap_xml_count:
          type: number
          description: '`sitemap_xml_count` indicates the number of `<url>` elements found in the sitemap.xml file.'
          example: 600
        sitemap_xml_pdf_count:
          type: number
          description: '`sitemap_xml_pdf_count` is the number of urls that have the PDF extension.'
          example: 0
        third_party_service_domains:
          description: '`third_party_service_domains` is a list of third party services that make outbound calls from the final url. Third party

            is defined as not matching the hostname of the URL.'
          example:
          - dap.digitalgov.gov
          - fonts.googleapis.com
          - www.google-analytics.com
          type: array
          items:
            type: string
        third_party_service_count:
          type: number
          description: '`third_party_service_count` is the number of third party services found.'
          example: 3
        hyperlink_domains:
          description: '`hyperlink_domains` is the list of distinct domains found in hyperlinks (`<a href>`) on the page.'
          example:
          - gsa.gov
          - usa.gov
          - data.gov
          type: array
          items:
            type: string
        dns_hostname:
          type: string
          description: '`dns_hostname` is the domain of underlying system, which often suggests use of a cloud or CDN provider.'
          example: cloudfront.net
        canonical_link:
          type: string
          description: '`canonical_link` indicates the presence of a canonical link tag.'
          example: https://18f.gsa.gov/
        cms:
          type: string
          description: '`cms` indicates the content management system used to host the final url.'
          example: WordPress
        target_url:
          type: string
          description: '`target_url` is the url the scanner starts the scan with.'
          example: 18f.gov
        target_url_branch:
          type: string
          description: '`target_url_branch` is the branch of government that the URL is associated with.'
          example: Executive
        target_url_agency_owner:
          type: string
          description: '`target_url_agency_owner` is the agency that owns the target url.'
          example: General Services Administration
        target_url_bureau_owner:
          type: string
          description: '`target_url_bureau_owner` is the name of the bureau that owns the target url.'
          example: GSA,FAS,Technology Transformation Service
        source_list_federal_domains:
          type: boolean
          description: '`source_list_federal_domains` indicates whether the List of Federal Domains provided this URL for the Target URL List.'
          example: true
        source_list_dap:
          type: boolean
          description: '`source_list_dap` indicates whether the Digital Analytics Program provided this URL for the Target URL List.'
          example: true
        source_list_pulse:
          type: boolean
          description: '`source_list_pulse` indicates whether the pulse.cio.gov Snapshot provided this URL for the Target URL List.'
          example: true
        source_list_other:
          type: boolean
          description: '`source_list_other` indicates whether the manually maintained list of additiona websites provided this URL for the Target URL List.'
          example: true
      required:
      - scan_date
      - secondary_data_dates
      - target_url_domain
      - scan_status
      - final_url
      - final_url_live
      - final_url_domain
      - final_url_website
      - final_url_MIMEType
      - final_url_same_domain
      - final_url_status_code
      - final_url_same_website
      - target_url_404_test
      - target_url_redirects
      - uswds_usa_classes
      - uswds_usa_class_list
      - uswds_usa_elements_list
      - uswds_banner_heres_how
      - uswds_string
      - uswds_tables
      - uswds_inpage_css
      - uswds_favicon
      - uswds_string_in_css
      - uswds_favicon_in_css
      - uswds_publicsans_font
      - uswds_source_sans_font
      - uswds_semantic_version
      - uswds_version
      - uswds_count
      - dap_detected_final_url
      - dap_parameters_final_url
      - og_title_final_url
      - og_description_final_url
      - og_article_published_final_url
      - og_article_modified_final_url
      - main_element_present_final_url
      - robots_txt_final_url
      - robots_txt_final_url_status_code
      - robots_txt_final_url_live
      - robots_txt_detected
      - robots_txt_final_url_MIMETYPE
      - robots_txt_target_url_redirects
      - robots_txt_final_url_size_in_bytes
      - robots_txt_crawl_delay
      - sitemap_xml_detected
      - sitemap_xml_final_url_status_code
      - sitemap_xml_final_url
      - sitemap_xml_final_url_live
      - sitemap_xml_target_url_redirects
      - sitemap_xml_final_url_filesize
      - sitemap_xml_final_url_MIMETYPE
      - sitemap_xml_count
      - sitemap_xml_pdf_count
      - third_party_service_domains
      - third_party_service_count
      - hyperlink_domains
      - dns_hostname
      - canonical_link
      - cms
      - target_url
      - target_url_branch
      - target_url_agency_owner
      - target_url_bureau_owner
      - source_list_federal_domains
      - source_list_dap
      - source_list_pulse
      - source_list_other
    Object:
      type: object
      properties: {}
    Links:
      type: object
      properties:
        first:
          type: string
          description: '`first` is a link to the first page of results.'
          example: /websites/?page=1&limit=1
        previous:
          type: string
          description: '`previous` is a link to the previous page of results. On the first page of results this will be an empty string `""`.'
          example: /websites/?page=1&limit=1
        next:
          type: string
          description: '`next` is a link to the next page of results. On the last page of results this will be an empty string `""`.'
          example: /websites/?page=3&limit=1
        last:
          type: string
          description: '`last` is a link to the last page of results.'
          example: /websites/?page=1000&limit=1
      required:
      - first
      - previous
      - next
      - last
    PaginatedWebsiteResponseDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebsiteApiResultDto'
        meta:
          description: '`meta` contains information various counts related to items and pages.'
          allOf:
          - $ref: '#/components/schemas/Meta'
        links:
          description: '`links` provides cursors for pagination (next and previous) and links to the first and last page of results.'
          allOf:
          - $ref: '#/components/schemas/Links'
      required:
      - items
      - meta
      - links