openapi: 3.1.0
info:
  title: Kilotest Agent API
  description: Kilotest tests web pages for front-end quality (i.e. accessibility, usability, and standards conformity) using an ensemble of ten independent rule engines that employ rule-based and machine-learning-based methods. This API enables AI agents to recommend web pages for testing, discover available test reports, and retrieve data from reports. Each report describes results of one job that tested one web page. For background on Kilotest and the advantages of ensemble testing, visit https://kilotest.com.
  version: 1.0.0
  contact:
    name: Kilotest
    url: https://kilotest.com
    email: info@kilotest.com

servers:
  - url: https://kilotest.com
    description: Kilotest production server

paths:
  /api/target:
    post:
      operationId: summarizeQualityOfMatchingWebPages
      summary: Summarize the quality of matching web pages
      description: Get summary data from the available reports about web pages whose descriptions or hostnames match your specifications. Matching is case-insensitive and succeeds if at least 1 specification is included by or includes the corresponding property of a tested page. The data include the name and URL of each tested web page, when the testing was performed, how many front-end quality (i.e. accessibility, usability, and standards conformity) issues were reported, and URLs for retrieving more detailed data from the report.
      requestBody:
        description: Page specifications
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Target'
      responses:
        '200':
          description: Summary of the quality of matching web pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetsResponse'

  /api/reportList:
    get:
      operationId: listAllAvailableReports
      summary: List all available reports
      description: List all available reports. Each report describes the results of a job that tested a web page for front-end quality (i.e. accessibility, usability, and standards conformity). For each report, the list identifies which page was tested and when and provides URLs to begin incremental retrieval of the test results.
      responses:
        '200':
          description: List of all available reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportListResponse'

  /api/testRecForm:
    post:
      operationId: recommendQualityTestingOfOneWebPage
      summary: Recommend quality testing of one web page
      description: Submit a recommendation for Kilotest to test, for the first time, a particular web page for front-end quality (i.e. accessibility, usability, and standards conformity). Recommendations are typically approved and the testing completed within a day, whereupon the results can be found with the listAllAvailableReports operation. Before submitting a recommendation, use the listAllAvailableReports operation to ensure that no report about the page is available, and also to see the stylistic rules for the naming of pages. An attempt to recommend a page for testing will fail if a report about the page is already available.
      requestBody:
        description: Test recommendation specifications
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestRecForm'
      responses:
        '200':
          description: Acknowledgement of test recommendation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestRecFormResponse'

  /api/reportFacts/{timeStamp}/{jobID}:
    get:
      operationId: summarizeOneReport
      summary: Summarize one report
      description: Summarize one report. The summary should briefly describe the testing job and the results, including the rule engines that tested the web page and the issues that were revealed by the reported rule violations, and should provide URLs for getting more detailed facts about any of the issues. The timeStamp and jobID parameters identify the report and were obtained from the response to a listAllAvailableReports operation.
      parameters:
        - name: timeStamp
          in: path
          required: true
          description: timeStamp component of the report identifier, in the format YYMMDDTHHMM (e.g., 260503T0432).
          schema:
            type: string
            pattern: '^\d{6}T\d{4}$'
            examples:
              - 260503T0432
        - name: jobID
          in: path
          required: true
          description: Job identifier component of the report identifier (e.g., xx0).
          schema:
            type: string
            examples:
              - xx0
      responses:
        '200':
          description: Summary of the specified report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportFactsResponse'
        '404':
          description: No report with the specified identifier is available

  /api/reportIssue/{issueID}/{timeStamp}/{jobID}:
    get:
      operationId: describeOneIssueFromOneReport
      summary: Describe one issue from one report
      description: Get issue-specific data from a specified report about the front-end quality (i.e. accessibility, usability, and standards conformity) of a web page. The data describe the issue, all of the HTML elements of the page that have the issue, and, for each such element, URLs for retrieving diagnoses by rule engines of the issue on the element.
      parameters:
        - name: issueID
          in: path
          required: true
          description: Issue identifier (e.g., imageNoText). Available under "response content" > "issues revealed" > [item] > "identifier" in the summarizeOneReport response.
          schema:
            type: string
            examples:
              - imageNoText
        - name: timeStamp
          in: path
          required: true
          schema:
            type: string
            examples:
              - 20271124T1647
        - name: jobID
          in: path
          required: true
          schema:
            type: string
            examples:
              - x58
      responses:
        '200':
          description: Details about the specified issue from the specified report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportIssueResponse'
        '404':
          description: No report or issue found with the specified identifiers

components:
  schemas:

    CommonResponseFields:
      type: object
      properties:
        summary:
          type: string
          description: Natural-language description of this response and of Kilotest. Provides context for an agent encountering Kilotest for the first time.
        tool collection name:
          type: string
          examples:
            - Kilotest
        tool name:
          type: string
          examples:
            - listAllAvailableReports
        request:
          type: object
          properties:
            type of request:
              type: object
              properties:
                identifier:
                  type: string
                  examples:
                    - reportList
                description:
                  type: string
            method:
              type: string
              enum:
                - GET
                - POST
            payload:
              type: object
              description: The request payload, if method type is POST, or otherwise omitted.
            URLs:
              type: object
              properties:
                'for you':
                  type: string
                'for humans':
                  type: string
            closest ancestor request:
              oneOf:
                - type: 'null'
                - type: object
                  properties:
                    identifier:
                      type: string
                    description:
                      type: string
                    URLs:
                      type: object
                      properties:
                        'for you':
                          type: string
                        'for humans':
                          type: string
        response metadata:
          type: object
          properties:
            identifier:
              type: string
              description: Unique identifier for this response instance.
            date and time:
              type: string
              description: UTC date and time when the response was generated, in ISO 8601 format.
              format: date-time

    SharedFacts:
      type: object
      properties:
        summary:
          type: string
          description: Natural-language facts about the request, the response, and Kilotest.
        tool collection name:
          type: string
          examples:
            - Kilotest
        tool name:
          type: string
          examples:
            - listAllAvailableReports
        request:
          type: object
          properties:
            description:
              type: string
            method:
              type: string
              enum:
                - GET
                - POST
            payload:
              type: object
              description: The request payload, if method is POST, or otherwise omitted.
            URLs:
              type: object
              properties:
                'for you':
                  type: string
                'for humans':
                  type: string
            closest ancestor request:
              oneOf:
                - type: 'null'
                - type: object
                  properties:
                    'tool name':
                      type: string
                    description:
                      type: string
                    URLs:
                      type: object
                      properties:
                        'for you':
                          type: string
                        'for humans':
                          type: string
        response metadata:
          type: object
          properties:
            identifier:
              type: string
              description: Unique identifier for this response instance.
            date and time:
              type: string
              description: UTC date and time when the response was generated, in ISO 8601 format.
              format: date-time

    TestRecForm:
      type: object
      properties:
        description of the web page:
          type: string
          description: Description of the web page to be tested.
        URL of the web page:
          type: string
          description: URL of the web page to be tested.
        reason for testing the web page:
          type: string
          description: Reason for testing the page.

    TestRecFormResponse:
      $ref: '#/components/schemas/CommonResponseFields'

    RuleEngineInfo:
      type: object
      description: A rule engine in the Kilotest ensemble.
      properties:
        identifier:
          type: string
          description: Short programmatic identifier for the rule engine.
          examples:
            - alfa
        name:
          type: string
          description: Display name of the rule engine.
          examples:
            - Alfa
        sponsor:
          type: string
          description: Organization that created, initially sponsored, or now sponsors the rule engine.
          examples:
            - Siteimprove

    RuleEngineFailure:
      type: object
      description: A rule engine that was unable to complete testing of the page.
      properties:
        name:
          type: string
          examples:
            - WAVE
        reason for failure:
          type: string
          examples:
            - Not enough credits.

    RuleEnginesSummary:
      type: object
      description: Count and names of a set of rule engines.
      properties:
        number:
          type: integer
        names:
          type: array
          items:
            type: string

    NextTierURLs:
      type: object
      description: URLs for retrieving the next level of detail.
      properties:
        for you:
          type: string
          format: uri
          description: URL for an LLM to request the next tier of detail.
        for humans:
          type: string
          format: uri
          description: URL for a human to view the next tier of detail.

    TargetsItem:
      type: object
      description: Summary data about a single available report.
      properties:
        identifier:
          type: string
          examples:
            - 260504T1659-029
        creation date:
          type: string
          format: date-time
        days since the creation date:
          type: integer
        tested web page:
          type: object
          properties:
            description:
              type: string
            URL:
              type: string
              format: uri
        whether a later report about the same page exists:
          type: boolean
          description: If true, a more recent report about this page is available. If you want the latest results, use that report instead.
        number of issues reported:
          type: integer
        number of HTML elements reported as exhibiting issues:
          type: integer
        rule engines that tried to test the page:
          $ref: '#/components/schemas/RuleEnginesSummary'
        rule engines that were unable to test the page:
          $ref: '#/components/schemas/RuleEnginesSummary'
        rule engines that reported issues:
          $ref: '#/components/schemas/RuleEnginesSummary'
        URLs for getting data about the reported issues:
          $ref: '#/components/schemas/NextTierURLs'
        URL for getting the full technical report as JSON:
          type: string
          format: uri

    ReportListItem:
      type: object
      description: Summary data about a single available report.
      properties:
        identifier:
          type: string
          examples:
            - 260504T1659-029
        creation date and time:
          type: string
          format: date-time
        days since the creation date:
          type: integer
        tested web page:
          type: object
          properties:
            description:
              type: string
            URL:
              type: string
              format: uri
        whether a later report about the same page exists:
          type: boolean
          description: If true, a more recent report about this page is available. If you want the latest results, use that report instead.
        URLs for more details:
          $ref: '#/components/schemas/NextTierURLs'
        size of the report in bytes:
          type: integer
        URL to get the entire report as machine-oriented JSON:
          type: string
          format: uri

    Target:
      type: object
      properties:
        description:
          type: string
          description: All or part of a description of the web page. If the page is the home page of an organization, the description is the name of the organization (e.g., “Earthjustice”). Otherwise, the description appends minimal differentiating words to the name of the organization (e.g., “Earthjustice Donate”), without the word “page”.
        hostname:
          type: string
          description: All or part of the hostname of the web page. The hostname omits the scheme and the path.

    ReportListResponse:
      allOf:
        - $ref: '#/components/schemas/SharedFacts'
        - type: object
          properties:
            response content:
              type: array
              description: One entry per available Kilotest report, in alphabetical order by page description and, in case of multiple reports per page, in order of creation date and time. Whether two reports are about the same page is determined by the page descriptions, not page URLs.
              items:
                $ref: '#/components/schemas/ReportListItem'

    TargetsResponse:
      allOf:
        - $ref: '#/components/schemas/CommonResponseFields'
        - type: object
          properties:
            matching reports:
              type: array
              description: One entry per available matching Kilotest report. A report is matching if its page description or hostname contains or is contained by a specified description or hostname fragment, respectively.
              items:
                $ref: '#/components/schemas/TargetsItem'

    IssueEntry:
      type: object
      description: Details about a specific front-end quality issue found on a page.
      properties:
        identifier:
          type: string
          examples:
            - imageNoText
        summary:
          type: string
          description: Brief natural-language label for the issue.
          examples:
            - image not named
        related WCAG 2.2 standard:
          type: object
          description: The WCAG 2.2 success criterion or guideline most closely related to this issue.
          properties:
            layer:
              type: string
              enum:
                - guideline
                - success criterion
            'numeric identifier':
              type: string
              pattern: '^\d\.\d(\.\d+)?$'
              examples:
                - 1.1.1
        impact on a user:
          type: string
          description: How this issue is likely to affect users.
        rule engines reporting the issue:
          $ref: '#/components/schemas/RuleEnginesSummary'
        number of HTML elements reported as exhibiting the issue:
          type: integer
        URLs for details about the issue on the page:
          $ref: '#/components/schemas/NextTierURLs'

    IssuesByPriority:
      type: object
      properties:
        highest priority:
          type: array
          items:
            $ref: '#/components/schemas/IssueEntry'
        high priority:
          type: array
          items:
            $ref: '#/components/schemas/IssueEntry'
        low priority:
          type: array
          items:
            $ref: '#/components/schemas/IssueEntry'
        lowest priority:
          type: array
          items:
            $ref: '#/components/schemas/IssueEntry'

    IssueSummary:
      type: object
      properties:
        identifier:
          type: string
        summary:
          type: string
        impact on a user:
          type: string
        priority:
          type: string
          enum:
            - lowest
            - low
            - high
            - highest
        URLs for more details:
          $ref: '#/components/schemas/NextTierURLs'

    ReportFactsResponse:
      allOf:
        - $ref: '#/components/schemas/SharedFacts'
        - type: object
          properties:
            response content:
              allOf:
                - $ref: '#/components/schemas/ReportListItem'
                - type: object
                  properties:
                    identifier:
                      type: string
                    rule engines that tried to test the page:
                      type: array
                      items:
                        $ref: '#/components/schemas/RuleEngineInfo'
                    rule engines that could not test the page:
                      type: array
                      items:
                        $ref: '#/components/schemas/RuleEngineFailure'
                    names of rule engines that reported rule violations:
                      type: array
                      items:
                        type: string
                    number of elements reported as violators:
                      type: integer
                    issues revealed:
                      type: array
                      items:
                        $ref: '#/components/schemas/IssueSummary'

    HTMLElementDetail:
      type: object
      description: Details about an HTML element reported as exhibiting an issue.
      properties:
        identifier:
          type: string
          description: Unique identifier of the element in the catalog of the report.
        tag name:
          type: string
          examples:
            - IMG
        id attribute:
          type: string
          description: Value of the element's id attribute, if any.
        start tag:
          type: string
          description: The opening tag of the element, including attributes.
        inner text:
          type: string
          description: First and last lines of the inner text, if any, of the element.
        inner text usable as a text fragment for linking:
          type: boolean
          description: Whether the inner text can be used as a text fragment for URL linking.
        x, y, width, height in pixels:
          type: array
          items:
            type: string
          description: Bounding box coordinates and dimensions of the element.
        XPath:
          type: string
          description: XPath of the element in the document.

    ReportIssueResponse:
      allOf:
        - $ref: '#/components/schemas/CommonResponseFields'
        - type: object
          properties:
            report:
              type: object
              properties:
                identifier:
                  type: string
                  examples:
                    - 20280216T1353-4r9
                creation date:
                  type: string
                  format: date-time
                days since the creation date:
                  type: integer
            tested web page:
              type: object
              properties:
                description:
                  type: string
                  examples:
                    - ARQ Space Exploration Corporation
                    - Edlir Velaj PF
                URL:
                  type: string
                  format: uri
                  examples:
                    - https://tiendalibros.com/
            rule engines that tried to test the page:
              type: array
              items:
                $ref: '#/components/schemas/RuleEngineInfo'
            rule engines that were unable to test the page:
              type: array
              items:
                $ref: '#/components/schemas/RuleEngineFailure'
            rule engines that reported issues:
              $ref: '#/components/schemas/RuleEnginesSummary'
            number of issues reported:
              type: object
              properties:
                total:
                  type: integer
                by priority:
                  type: object
                  properties:
                    highest priority:
                      type: integer
                    high priority:
                      type: integer
                    low priority:
                      type: integer
                    lowest priority:
                      type: integer
            number of HTML elements reported as exhibiting issues:
              type: integer
            level of the issue:
              type: integer
              enum:
                - 1
                - 2
                - 3
                - 4
              description: Priority level of the issue (4 = highest, 1 = lowest).
            facts about the issue:
              type: object
              description: Details about the specified issue and the HTML elements exhibiting it.
              properties:
                identifier:
                  type: string
                  examples:
                    - imageNoText
                summary:
                  type: string
                  description: Brief natural-language label for the issue.
                  examples:
                    - image not named
                related WCAG 2.2 standard:
                  type: object
                  description: The WCAG 2.2 success criterion or guideline most closely related to the issue.
                  properties:
                    layer:
                      type: string
                      enum:
                        - guideline
                        - success criterion
                    'numeric identifier':
                      type: string
                      pattern: '^\d\.\d(\.\d+)?$'
                      examples:
                        - 1.1.1
                impact on a user:
                  type: string
                  description: How this issue is likely to affect users.
                rule engines reporting the issue:
                  $ref: '#/components/schemas/RuleEnginesSummary'
                number of HTML elements reported as exhibiting the issue:
                  type: integer
                HTML elements reported as exhibiting the issue:
                  type: array
                  items:
                    $ref: '#/components/schemas/HTMLElementDetail'