openapi: 3.1.0
info:
  title: HiRafi Public API
  version: 1.4.0
  description: >
    Public automation API for API-key and session based access.
    This reference covers generation, scenarios, runs, reports, and public sharing flows.
servers:
  - url: https://api.therafi.ai/api
    description: Current Environment
tags:
  - name: Generate
    description: AI-assisted scenario generation helpers
  - name: Scenarios
    description: Scenario listing and creation endpoints
  - name: API Context
    description: Collections and environments used to generate or organize API scenarios
  - name: Runs
    description: Run listing, execution, status, and scenario report endpoints
  - name: Monitoring
    description: Live run monitoring and step progress endpoints
  - name: Reports
    description: Report detail endpoints
  - name: Sharing
    description: Public report sharing and public report retrieval endpoints
  - name: Accessibility
    description: WCAG accessibility audit automation — create tests, execute audits, retrieve compliance reports and share results
components:
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: hrf_live_*
  schemas:
    AccessibilityTestCreateRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        urls:
          type: array
          items:
            type: string
        suites:
          type: object
          properties:
            wcag:            { type: object, properties: { enabled: { type: boolean } } }
            visualBugs:      { type: object, properties: { enabled: { type: boolean } } }
            resourceChecker: { type: object, properties: { enabled: { type: boolean } } }
            performance:     { type: object, properties: { enabled: { type: boolean } } }
            security:        { type: object, properties: { enabled: { type: boolean } } }
            seo:             { type: object, properties: { enabled: { type: boolean } } }
            advanced:        { type: object, properties: { enabled: { type: boolean } } }
    AccessibilityExecuteRequest:
      type: object
      properties:
        mode:
          type: string
          enum: [restart, resume]
          default: restart
    AccessibilityShareEnableRequest:
      type: object
      properties:
        expiresIn:
          type: integer
          nullable: true
        allowComments:
          type: boolean
    AccessibilityPdfRequest:
      type: object
      properties:
        language:
          type: string
          enum: [en, tr]
          default: en
        includeIssueDetails:
          type: boolean
          default: true
        includePerPageBreakdown:
          type: boolean
          default: true
        severityFilter:
          type: array
          items:
            type: string
            enum: [critical, serious, moderate, minor]
        fullReport:
          type: boolean
          default: false
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
    GenerateStepsRequest:
      type: object
      required: [prompt]
      properties:
        prompt:
          type: string
          description: Plain-language instruction used to generate the first draft of a test.
        platform:
          type: string
          enum: [web, api, android, ios]
        name:
          type: string
        description:
          type: string
        aiModelId:
          type: string
    GenerateStepsResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        name:
          type: string
        description:
          type: string
        steps:
          type: array
          items:
            type: object
    ScenarioCreateRequest:
      type: object
      required: [name, steps]
      properties:
        name:
          type: string
        description:
          type: string
        platform:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        testType:
          type: string
        steps:
          type: array
          items:
            type: object
    ScenarioGenerateRequest:
      type: object
      required: [userPrompt, platform]
      properties:
        userPrompt:
          type: string
          description: Plain-language prompt used to generate a scenario draft and persist it immediately.
        platform:
          type: string
          enum: [web, api, android, ios]
        name:
          type: string
          description: Optional preferred scenario name. AI output uses this when provided.
        description:
          type: string
          description: Optional preferred scenario description.
        folderId:
          type: string
          description: Optional folder id to place the created scenario under.
        targetTeamId:
          type: string
          description: Required only for users working with all-team scope and creating under a specific team.
    ScenarioFoldersResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            count:
              type: integer
            total:
              type: integer
            folders:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                  color:
                    type: string
                  parentId:
                    type: string
                    nullable: true
    RunCreateRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        description:
          type: string
        scenarios:
          type: array
          items:
            type: string
        scenarioIds:
          type: array
          items:
            type: string
        platform:
          type: string
        reportSettings:
          type: object
        environment:
          type: object
    GenerateAndExecuteRunRequest:
      type: object
      required: [prompt, platform]
      properties:
        prompt:
          type: string
          description: Natural-language scenario description. This endpoint does not return generated steps.
        platform:
          type: string
          enum: [web, api, android, ios]
        startUrl:
          type: string
          description: Optional initial URL used during scenario generation.
        name:
          type: string
        description:
          type: string
        folderId:
          type: string
        targetTeamId:
          type: string
        tags:
          type: array
          items:
            type: string
        shareReport:
          type: boolean
          default: true
        expiresIn:
          type: integer
          nullable: true
        password:
          type: string
        allowComments:
          type: boolean
    ShareRunReportRequest:
      type: object
      required: [reportId]
      properties:
        reportId:
          type: string
        expiresIn:
          type: integer
          nullable: true
        password:
          type: string
        allowComments:
          type: boolean
    ShareReportRequest:
      type: object
      properties:
        expiresIn:
          type: integer
          nullable: true
        password:
          type: string
        allowComments:
          type: boolean
paths:
  /generate-steps:
    post:
      tags: [Generate]
      summary: Generate test steps
      description: >
        Creates an initial generated test draft from a plain-language prompt.
        Use this when you want to inspect or edit the generated steps before saving a scenario.
        Requires `scenario:create`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateStepsRequest'
            example:
              prompt: Create an API login flow and validate the token response.
              platform: api
      responses:
        '200':
          description: A generated step draft that can be turned into a scenario.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateStepsResponse'
              example:
                success: true
                name: API Login Flow
                description: Validates successful login and token creation.
                steps:
                  - type: apiRequest
                    method: POST
                    url: https://example.com/api/login
                    headers:
                      Content-Type: application/json
                    body:
                      email: qa@example.com
                      password: secret123
                  - type: responseAssertion
                    path: $.token
                    operator: exists
        '403':
          description: Missing scope or quota exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Insufficient permissions. Required scope: scenario:create"
  /generate-steps/details-from-steps:
    post:
      tags: [Generate]
      summary: Generate scenario metadata from manual steps
      description: >
        Converts manual steps into a cleaner scenario name and description.
        Useful when you already have steps and only need a polished title and description.
        Requires `scenario:create`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              steps:
                - type: goto
                  url: https://example.com
                - type: aiTap
                  target: Login button
      responses:
        '200':
          description: Suggested scenario metadata for the given steps.
          content:
            application/json:
              example:
                success: true
                data:
                  name: API Login Smoke Test
                  description: Validates that login succeeds and required response fields exist.
  /scenarios:
    get:
      tags: [Scenarios]
      summary: List scenarios
      description: Lists scenarios visible to the authenticated scope. Requires `scenario:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: status
          schema:
            type: string
      responses:
        '200':
          description: Scenario list without heavy metadata.
          content:
            application/json:
              example:
                success: true
                data:
                  count: 2
                  total: 2
                  scenarios:
                    - id: scenario-123
                      name: API Login Flow
                      description: Validates login response token.
                      status: active
                      platform: api
                      updatedAt: '2026-03-16T09:45:12.000Z'
                    - id: scenario-456
                      name: Refresh Token Flow
                      description: Validates token refresh flow.
                      status: active
                      platform: api
                      updatedAt: '2026-03-15T17:20:00.000Z'
    post:
      tags: [Scenarios]
      summary: Create a scenario
      description: >
        Persists a scenario that can later be executed in runs.
        Use this after `/generate-steps` when you want to review or modify the draft before saving.
        Requires `scenario:create`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScenarioCreateRequest'
            example:
              name: API Login Scenario
              description: Validates the login response token.
              platform: api
              testType: api
              steps:
                - type: apiRequest
                  method: POST
                  url: https://example.com/login
                  headers:
                    Content-Type: application/json
                  body:
                    email: qa@example.com
                    password: secret123
                - type: responseAssertion
                  path: $.token
                  operator: exists
      responses:
        '201':
          description: Scenario created successfully.
          content:
            application/json:
              example:
                success: true
                data:
                  scenarioId: scenario-123
                  message: Senaryo başarıyla oluşturuldu
  /scenarios/generate:
    post:
      tags: [Scenarios]
      summary: Generate and create a scenario
      description: >
        Generates scenario steps from a prompt and immediately persists the resulting scenario.
        Requires `scenario:create`. If the AI needs follow-up clarification, this endpoint returns
        `AI_GENERATION_REQUIRES_CLARIFICATION`; use `/generate-steps` for conversational generation in that case.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScenarioGenerateRequest'
            example:
              userPrompt: Create an API login flow, assert that the token exists, and store the scenario under the API folder.
              platform: api
              folderId: folder-001
              name: API Login Smoke
              description: Quick smoke coverage for login token creation.
      responses:
        '201':
          description: Scenario generated and created successfully.
          content:
            application/json:
              example:
                success: true
                data:
                  scenario:
                    id: scenario-789
                    name: API Login Smoke
                    description: Quick smoke coverage for login token creation.
                    platform: api
                    folderId: folder-001
                    status: active
                    createdAt: '2026-03-16T11:42:00.000Z'
                  generation:
                    prompt: Create an API login flow, assert that the token exists, and store the scenario under the API folder.
                    aiModelId: model-123
                    stepsCount: 4
                    remainingGenerations: 27
        '422':
          description: The AI needs clarification and the scenario was not created.
          content:
            application/json:
              example:
                success: false
                code: AI_GENERATION_REQUIRES_CLARIFICATION
                error: AI generation requires additional clarification. Use /api/generate-steps for conversational generation.
                data:
                  questionType: missing_parameter
                  title: Which environment should be used?
                  inputType: select
                  options:
                    - staging
                    - production
  /scenarios/basic:
    get:
      tags: [Scenarios]
      summary: List lightweight scenarios
      description: Returns scenario list without heavy step payloads. Requires `scenario:read`.
      security:
        - BearerApiKey: []
      responses:
        '200':
          description: Lightweight scenario list.
          content:
            application/json:
              example:
                success: true
                data:
                  count: 1
                  total: 1
                  scenarios:
                    - id: scenario-123
                      name: API Login Flow
                      status: active
                      platform: api
  /scenarios/{scenarioId}:
    get:
      tags: [Scenarios]
      summary: Get scenario by id
      description: Returns the full scenario payload, including steps and metadata. Requires `scenario:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: scenarioId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Full scenario detail.
          content:
            application/json:
              example:
                success: true
                data:
                  scenario:
                    id: scenario-123
                    name: API Login Flow
                    description: Validates login response token.
                    platform: api
                    status: active
                    steps:
                      - id: step-1
                        type: apiRequest
                        method: POST
                        url: https://example.com/api/login
                      - id: step-2
                        type: responseAssertion
                        path: $.token
                        operator: exists
  /scenarios/folders:
    get:
      tags: [Scenarios]
      summary: List scenario folders
      description: >
        Returns scenario folders visible to the authenticated scope.
        Useful before scenario creation when you want to place generated scenarios into a specific folder.
        Requires `folder:view`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: skip
          schema:
            type: integer
      responses:
        '200':
          description: Scenario folder list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioFoldersResponse'
              example:
                success: true
                data:
                  count: 2
                  total: 2
                  folders:
                    - id: folder-001
                      name: API Smoke
                      description: Fast API coverage scenarios
                      color: '#0ea5e9'
                      parentId: null
                    - id: folder-002
                      name: Regression
                      description: Full API regression scenarios
                      color: '#22c55e'
                      parentId: null
  /collections:
    get:
      tags: [API Context]
      summary: List API collections
      description: >
        Returns the API collections visible to the authenticated user.
        Useful for API scenario generation flows where collections provide endpoint and variable context.
        Requires `scenario:read`.
      security:
        - BearerApiKey: []
      responses:
        '200':
          description: Collection list.
          content:
            application/json:
              example:
                collections:
                  - id: collection-101
                    name: Auth API
                    baseUrl: https://example.com/api
                    endpointCount: 12
                  - id: collection-102
                    name: Profile API
                    baseUrl: https://example.com/profile
                    endpointCount: 7
  /collections/{collectionId}:
    get:
      tags: [API Context]
      summary: Get API collection by id
      description: Returns a single API collection with its request definitions and variables. Requires `scenario:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: collectionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection detail.
          content:
            application/json:
              example:
                collection:
                  id: collection-101
                  name: Auth API
                  variables:
                    baseUrl: https://example.com/api
                  requests:
                    - id: request-1
                      name: Login
                      method: POST
                      path: /login
  /environments:
    get:
      tags: [API Context]
      summary: List environments
      description: >
        Returns saved API environments and variables for the authenticated user.
        Useful for API scenario generation when selecting the right base URL or token variables.
        Requires `scenario:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: collectionId
          schema:
            type: string
      responses:
        '200':
          description: Environment list.
          content:
            application/json:
              example:
                environments:
                  - id: env-101
                    name: Staging
                    baseUrl: https://staging.example.com/api
                    isDefault: true
                  - id: env-102
                    name: Production
                    baseUrl: https://api.example.com
                    isDefault: false
  /environments/{environmentId}:
    get:
      tags: [API Context]
      summary: Get environment by id
      description: Returns a single environment including its variable set. Requires `scenario:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: environmentId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Environment detail.
          content:
            application/json:
              example:
                environment:
                  id: env-101
                  name: Staging
                  baseUrl: https://staging.example.com/api
                  isDefault: true
                  variables:
                    token: '{{auth_token}}'
                    accountId: '12345'
  /runs:
    get:
      tags: [Runs]
      summary: List runs
      description: >
        Lists runs visible to the authenticated team or company scope.
        Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: platform
          schema:
            type: string
        - in: query
          name: sortBy
          schema:
            type: string
            enum: [priority, date, name, status]
        - in: query
          name: sortOrder
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: Paginated run list.
          content:
            application/json:
              example:
                success: true
                data:
                  runs:
                    - id: run-123
                      name: API smoke run
                      status: running
                      platform: api
                      createdAt: '2026-03-16T10:05:00.000Z'
                      queueAssistCount: 0
                    - id: run-122
                      name: Nightly regression
                      status: completed
                      platform: api
                      createdAt: '2026-03-15T23:10:00.000Z'
                      queueAssistCount: 0
                  total: 2
                  limit: 20
                  skip: 0
    post:
      tags: [Runs]
      summary: Create a run
      description: >
        Creates a run from one or more scenarios.
        Use the returned run id with `/runs/{runId}/execute` to start execution.
        Requires `run:create`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunCreateRequest'
            example:
              name: API smoke run
              scenarioIds: [scenario-123]
              platform: api
              reportSettings:
                captureScreenshots: true
      responses:
        '201':
          description: Run created successfully.
          content:
            application/json:
              example:
                success: true
                data:
                  run:
                    id: run-123
                    name: API smoke run
                    status: created
                    platform: api
                    scenarioIds: [scenario-123]
  /runs/generate-and-execute:
    post:
      tags: [Runs]
      summary: Generate a scenario, execute it, and return a public report link
      description: >
        Creates a persistent scenario from a prompt, creates a run, starts execution,
        guarantees a run report, and immediately returns a shareable public run-report link.
        The response does not include generated steps.
        Requires `scenario:create`, `run:create`, `run:read`, `run:execute`, and `report:read`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAndExecuteRunRequest'
            example:
              prompt: |
                Senaryo 1: Tek Yön Bilet Arama ve Seçimi
                1. Kalkış noktasını "İstanbul-Sabiha Gökçen", varış noktasını "Ankara" olarak seçin.
                2. Yakın bir tarihe gidiş günü belirleyin.
                3. "Ucuz Bilet Bul" butonuna tıklayın.
                4. Beklenen Sonuç: Seçilen kriterlere uygun uçuş listesi ve fiyatlar görüntülenmelidir.
              platform: web
              name: Tek Yon Bilet Arama
              folderId: folder-001
              shareReport: true
              allowComments: false
      responses:
        '201':
          description: Scenario was generated, run execution started, and public link created.
          content:
            application/json:
              example:
                success: true
                data:
                  scenarioId: scenario-790
                  runId: run-790
                  reportId: report-790
                  executionId: execution-790
                  status: running
                  publicShareUrl: https://dev.hirafi.ai/shared/run-reports/share-token-790
                  shareToken: share-token-790
                  message: Scenario generated, run created, execution started, and public report link prepared successfully
        '422':
          description: AI generation requires clarification before a scenario can be created.
          content:
            application/json:
              example:
                success: false
                code: AI_GENERATION_REQUIRES_CLARIFICATION
                error: AI generation requires additional clarification. Use /api/generate-steps for conversational generation.
                data:
                  questionType: missing_parameter
                  title: Hangi tarih secilmeli?
                  inputType: text
  /runs/{runId}:
    get:
      tags: [Runs]
      summary: Get run by id
      description: Returns a single run payload. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Full run payload.
          content:
            application/json:
              example:
                success: true
                data:
                  run:
                    id: run-123
                    name: API smoke run
                    status: running
                    platform: api
                    scenarioIds: [scenario-123]
                    createdAt: '2026-03-16T10:05:00.000Z'
  /runs/{runId}/execute:
    post:
      tags: [Runs]
      summary: Execute a run
      description: Starts execution for a prepared run. Requires `run:execute`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Run execution accepted.
          content:
            application/json:
              example:
                success: true
                data:
                  message: Run execution started
                  runId: run-123
  /runs/{runId}/stop:
    post:
      tags: [Runs]
      summary: Stop a run
      description: Stops an active run. Requires `run:stop`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stop request accepted.
          content:
            application/json:
              example:
                success: true
                data:
                  message: Stop request accepted
                  runId: run-123
  /runs/{runId}/retry-failed:
    post:
      tags: [Runs]
      summary: Retry failed scenarios
      description: Requeues only failed scenarios in the selected run. Requires `run:execute`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retry request accepted.
          content:
            application/json:
              example:
                success: true
                data:
                  message: Retry flow started
                  runId: run-123
  /runs/{runId}/status:
    get:
      tags: [Runs]
      summary: Get live run status
      description: >
        Returns current run status and live progress summary.
        Poll this endpoint for dashboard-style progress updates while a run is active.
        Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Live run status summary.
          content:
            application/json:
              example:
                success: true
                data:
                  runId: run-123
                  status: running
                  completedScenarios: 1
                  totalScenarios: 3
                  queueStage: executing
                  progressPercentage: 33
  /runs/{runId}/scenario-reports:
    get:
      tags: [Runs]
      summary: Get scenario reports for a run
      description: Returns per-scenario reports for a run. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
        - in: query
          name: executionId
          schema:
            type: string
      responses:
        '200':
          description: Scenario report list for the run.
          content:
            application/json:
              example:
                success: true
                data:
                  reports:
                    - reportId: report-101
                      scenarioId: scenario-123
                      status: passed
                    - reportId: report-102
                      scenarioId: scenario-456
                      status: failed
  /runs/{runId}/active-tests:
    get:
      tags: [Monitoring]
      summary: Get active tests in a run
      description: Returns currently queued or running tests for the specified run. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Active test list.
          content:
            application/json:
              example:
                success: true
                data:
                  activeTests:
                    - id: test-101
                      runId: run-790
                      scenarioId: scenario-790
                      status: running
                      nodeId: node-1
                      platform: web
  /step-progress/run/{runId}:
    get:
      tags: [Monitoring]
      summary: Get step progress for all tests in a run
      description: Returns raw step-progress records for every active test in the run. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Per-test step progress.
          content:
            application/json:
              example:
                success: true
                data:
                  - testId: test-101
                    currentStep: 2
                    totalSteps: 5
                    currentStepName: Ucus arama formunu doldur
                    currentStepType: aiType
                    currentStepStatus: started
                    runId: run-790
                    scenarioId: scenario-790
  /step-progress/run/{runId}/summary:
    get:
      tags: [Monitoring]
      summary: Get aggregated step progress summary for a run
      description: Returns progress percentage, current step information, and blocker state across tests. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Aggregated run step-progress summary.
          content:
            application/json:
              example:
                success: true
                data:
                  totalTests: 1
                  testsInProgress: 1
                  testsCompleted: 0
                  testsFailed: 0
                  averageProgress: 40
                  tests:
                    - testId: test-101
                      scenarioId: scenario-790
                      scenarioName: Tek Yon Bilet Arama
                      currentStep: 2
                      totalSteps: 5
                      currentStepName: Ucus arama formunu doldur
                      currentStepType: aiType
                      currentStepStatus: started
                      progress: 40
                      activeBlocker: null
  /step-progress/test/{testId}:
    get:
      tags: [Monitoring]
      summary: Get step progress for a single test
      description: Returns current step, nested step info, and runtime blockers for a single test. Requires `run:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Single-test step progress.
          content:
            application/json:
              example:
                success: true
                data:
                  testId: test-101
                  currentStep: 2
                  totalSteps: 5
                  currentStepName: Ucus arama formunu doldur
                  currentStepType: aiType
                  currentStepStatus: started
                  runtimeEventCounts:
                    blockersStarted: 0
                    blockersResolved: 0
                  activeBlocker: null
  /runs/{runId}/sharing/enable:
    post:
      tags: [Sharing]
      summary: Enable run report sharing
      description: Creates or refreshes a public share token for a run-level report.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareRunReportRequest'
            example:
              reportId: report-201
              expiresIn: 7
              allowComments: true
      responses:
        '200':
          description: Public sharing enabled.
          content:
            application/json:
              example:
                success: true
                data:
                  shareToken: share-token
                  shareUrl: https://hirafi.ai/shared/run-reports/share-token
  /runs/{runId}/sharing/status:
    get:
      tags: [Sharing]
      summary: Get run report sharing status
      description: Returns whether a run-level report is currently shared.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
        - in: query
          name: reportId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current sharing state.
          content:
            application/json:
              example:
                success: true
                data:
                  enabled: true
                  shareToken: share-token
                  shareUrl: https://hirafi.ai/shared/run-reports/share-token
  /runs/{runId}/sharing/disable:
    delete:
      tags: [Sharing]
      summary: Disable run report sharing
      description: Revokes a public share token for a run-level report.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            example:
              reportId: report-201
      responses:
        '200':
          description: Sharing disabled.
          content:
            application/json:
              example:
                success: true
                data:
                  disabled: true
  /reports/{reportId}:
    get:
      tags: [Reports]
      summary: Get single report
      description: Returns the raw report payload for a single scenario execution. Requires `report:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: reportId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Single report detail.
          content:
            application/json:
              example:
                success: true
                data:
                  report:
                    id: report-101
                    status: passed
                    url: https://example.com/login
                    duration: 1840
                    createdAt: '2026-03-16T10:06:10.000Z'
  /reports/run-detail/{reportId}:
    get:
      tags: [Reports]
      summary: Get run report detail
      description: Aggregates the run-level summary and scenario-level reports in one payload. Requires `report:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: reportId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Aggregated run report detail.
          content:
            application/json:
              example:
                success: true
                data:
                  runReport:
                    id: report-201
                    status: running
                    runId: run-123
                  scenarioReports:
                    - reportId: report-101
                      scenarioId: scenario-123
                      status: passed
                    - reportId: report-102
                      scenarioId: scenario-456
                      status: running
  /reports/{reportId}/share:
    post:
      tags: [Sharing]
      summary: Enable single report sharing
      description: Creates or refreshes a public token for a single scenario report.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: reportId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareReportRequest'
            example:
              expiresIn: 7
              allowComments: true
      responses:
        '200':
          description: Sharing enabled.
          content:
            application/json:
              example:
                success: true
                data:
                  shareToken: share-token
                  shareUrl: https://hirafi.ai/shared/reports/share-token
    delete:
      tags: [Sharing]
      summary: Disable single report sharing
      description: Revokes the public token for a single scenario report.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: reportId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sharing disabled.
          content:
            application/json:
              example:
                success: true
                data:
                  disabled: true
  /shared-run-reports/{token}:
    get:
      tags: [Sharing]
      summary: Fetch shared run report
      description: Public endpoint for reading a shared run report.
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
        - in: query
          name: password
          schema:
            type: string
      responses:
        '200':
          description: Public run report payload.
          content:
            application/json:
              example:
                success: true
                data:
                  report:
                    id: report-201
                    status: completed
                  scenarioReports:
                    - reportId: report-101
                      status: passed
  /shared-reports/{token}:
    get:
      tags: [Sharing]
      summary: Fetch shared single report
      description: Public endpoint for reading a shared scenario report.
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
        - in: query
          name: password
          schema:
            type: string
      responses:
        '200':
          description: Public scenario report payload.
          content:
            application/json:
              example:
                success: true
                data:
                  report:
                    id: report-101
                    status: passed

  # ──────────────────────────────────────────────────────────────────────────
  # Accessibility
  # ──────────────────────────────────────────────────────────────────────────

  /accessibility/limits:
    get:
      tags: [Accessibility]
      summary: Get usage limits
      description: Returns the run limit, max URLs per test, and remaining runs for the authenticated account. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      responses:
        '200':
          description: Current accessibility usage limits.
          content:
            application/json:
              example:
                success: true
                data:
                  runLimit: 5
                  maxUrls: 10
                  remainingRuns: 3

  /accessibility/dashboard:
    get:
      tags: [Accessibility]
      summary: Get accessibility dashboard
      description: Returns aggregated accessibility metrics, trend data, severity breakdown and top issues. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      responses:
        '200':
          description: Dashboard metrics.
          content:
            application/json:
              example:
                success: true
                data:
                  averageScore: 84
                  totalIssues: 47
                  criticalIssues: 3
                  remainingRunsLabel: "3 / 5"
                  reportCount: 12
                  rangeLabel: "Last 30 days"
                  trend:
                    - date: "2026-03-10"
                      score: 81
                    - date: "2026-03-15"
                      score: 84
                  severity:
                    critical: 3
                    serious: 14
                    moderate: 22
                    minor: 8
                  topPages: []
                  topRules: []
                  recentReports: []

  /accessibility/tests:
    get:
      tags: [Accessibility]
      summary: List accessibility tests
      description: Returns all accessibility tests visible to the authenticated user. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
        - in: query
          name: status
          schema:
            type: string
            enum: [created, running, completed, stopped, failed]
      responses:
        '200':
          description: Paginated accessibility test list.
          content:
            application/json:
              example:
                success: true
                data:
                  tests:
                    - id: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                      name: Homepage WCAG Audit
                      status: created
                      config:
                        urls: ["https://example.com"]
                        suites:
                          wcag: { enabled: true }
                      createdAt: "2026-03-10T12:00:00Z"
                  total: 42
                  page: 1
                  limit: 20
    post:
      tags: [Accessibility]
      summary: Create accessibility test
      description: Creates a new accessibility test definition. Requires `a11y:write`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessibilityTestCreateRequest'
            example:
              name: Homepage WCAG Audit
              urls:
                - https://example.com
                - https://example.com/about
              suites:
                wcag:            { enabled: true }
                visualBugs:      { enabled: false }
                resourceChecker: { enabled: false }
                performance:     { enabled: false }
                security:        { enabled: false }
                seo:             { enabled: false }
                advanced:        { enabled: false }
      responses:
        '201':
          description: Test created successfully.
          content:
            application/json:
              example:
                success: true
                data:
                  id: xxxxxxxx-xxxx-xxxx-xxxx-test00000001

  /accessibility/tests/{testId}:
    get:
      tags: [Accessibility]
      summary: Get accessibility test
      description: Returns the full test configuration and current status. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Full test detail.
          content:
            application/json:
              example:
                success: true
                data:
                  id: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                  name: Homepage Audit
                  status: created
                  config:
                    urls: ["https://example.com"]
                    suites:
                      wcag: { enabled: true }
                    advanced:
                      timeout: 30000
                      maxPages: 200
                      waitTimeout: 5000
                  progress:
                    current: 0
                    total: 1
                  createdAt: "2026-03-16T09:00:00Z"
                  updatedAt: "2026-03-16T09:00:00Z"
    put:
      tags: [Accessibility]
      summary: Update accessibility test
      description: Updates the test name, URLs or suite configuration. Requires `a11y:write`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Homepage Audit v2
              urls:
                - https://example.com
                - https://example.com/about
              suites:
                wcag: { enabled: true }
                seo:  { enabled: true }
      responses:
        '200':
          description: Test updated.
          content:
            application/json:
              example:
                success: true
                data:
                  id: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                  name: Homepage Audit v2
                  config:
                    urls: ["https://example.com", "https://example.com/about"]
                    suites:
                      wcag: { enabled: true }
                      seo:  { enabled: true }
                  updatedAt: "2026-03-16T10:00:00Z"
    delete:
      tags: [Accessibility]
      summary: Delete accessibility test
      description: Permanently deletes the test and its associated data. Requires `a11y:delete`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Test deleted.
          content:
            application/json:
              example:
                success: true

  /accessibility/tests/{testId}/resume-preview:
    get:
      tags: [Accessibility]
      summary: Get resume preview
      description: Returns remaining URLs and progress info to preview what a resume would re-scan. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Resume preview data.
          content:
            application/json:
              example:
                success: true
                data:
                  resumable: true
                  status: stopped
                  totalCount: 12
                  completedCount: 7
                  remainingCount: 5
                  remainingUrls:
                    - https://example.com/page8
                    - https://example.com/page9
                  lastRunId: xxxxxxxx-xxxx-xxxx-xxxx-report000001
                  updatedAt: "2026-03-16T09:18:00Z"

  /accessibility/tests/{testId}/execute:
    post:
      tags: [Accessibility]
      summary: Execute accessibility test
      description: >
        Starts a new audit run for the given test. Use `mode: restart` to start fresh or `mode: resume`
        to continue from remaining URLs after a stop. Requires `a11y:execute`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessibilityExecuteRequest'
            example:
              mode: restart
      responses:
        '200':
          description: Execution started.
          content:
            application/json:
              example:
                success: true
                data:
                  runId: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                  executionId: exec_xyz789
                  jobId: job_000111
                  reportId: xxxxxxxx-xxxx-xxxx-xxxx-report000001
                  mode: restart

  /accessibility/tests/{testId}/stop:
    post:
      tags: [Accessibility]
      summary: Stop accessibility test
      description: Requests a graceful stop for an active audit run. Requires `a11y:execute`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stop requested.
          content:
            application/json:
              example:
                success: true
                message: Run stop requested

  /accessibility/tests/{testId}/status:
    get:
      tags: [Accessibility]
      summary: Get test execution status
      description: >
        Returns current status and page-level progress. Poll this endpoint while an audit is running.
        Possible status values: `created`, `running`, `completed`, `stopped`, `failed`.
        Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Live execution status.
          content:
            application/json:
              example:
                success: true
                data:
                  status: running
                  progress:
                    current: 5
                    total: 12
                    currentUrl: https://example.com/about
                    percentage: 42

  /accessibility/tests/{testId}/report:
    get:
      tags: [Accessibility]
      summary: Get latest accessibility report
      description: Returns the most recent audit report for the given test, including summary metrics and per-page results. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Latest report data.
          content:
            application/json:
              example:
                success: true
                data:
                  id: xxxxxxxx-xxxx-xxxx-xxxx-report000001
                  testId: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                  name: Homepage Audit
                  status: completed
                  progress:
                    currentPage: 1
                    totalPages: 1
                    currentUrl: null
                    percentage: 100
                  summary:
                    totalPages: 1
                    scannedPages: 1
                    totalIssues: 7
                    issuesBySeverity:
                      critical: 1
                      serious: 3
                      moderate: 2
                      minor: 1
                    accessibilityScore: 87
                  moduleResults: {}
                  pages: []
                  metadata:
                    config:
                      urls: ["https://example.com"]
                  recentReports: []
                  createdAt: "2026-03-15T14:30:00Z"
                  updatedAt: "2026-03-15T14:35:00Z"
    delete:
      tags: [Accessibility]
      summary: Delete accessibility report
      description: Deletes the current report data for the given test. Requires `a11y:delete`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Report deleted.
          content:
            application/json:
              example:
                success: true
                message: Report deleted successfully

  /accessibility/tests/{testId}/report/pdf:
    post:
      tags: [Accessibility]
      summary: Generate PDF report
      description: >
        Generates and streams a PDF audit report. Use the `-o` flag in curl to save directly to disk.
        Set `fullReport: true` to include all issues without limits. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessibilityPdfRequest'
            example:
              language: en
              includeIssueDetails: true
              includePerPageBreakdown: true
              severityFilter: [critical, serious, moderate, minor]
              fullReport: false
      responses:
        '200':
          description: PDF binary stream.
          content:
            application/pdf:
              schema:
                type: string
                format: binary

  /accessibility/tests/{testId}/report/history:
    get:
      tags: [Accessibility]
      summary: Get report history
      description: Returns a list of past audit reports for the given test, ordered by most recent. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Report history list.
          content:
            application/json:
              example:
                - id: xxxxxxxx-xxxx-xxxx-xxxx-report000001
                  testId: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                  name: Homepage Audit
                  status: completed
                  summary:
                    accessibilityScore: 87
                    totalIssues: 7
                    issuesBySeverity:
                      critical: 1
                      serious: 3
                      moderate: 2
                      minor: 1
                  createdAt: "2026-03-15T14:30:00Z"
                - id: report_def123
                  status: completed
                  summary:
                    accessibilityScore: 81
                    totalIssues: 12
                  createdAt: "2026-03-08T10:00:00Z"

  /accessibility/reports:
    get:
      tags: [Accessibility]
      summary: List all accessibility reports
      description: Returns paginated reports across all tests for the authenticated account. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Paginated report list.
          content:
            application/json:
              example:
                success: true
                data:
                  reports:
                    - id: xxxxxxxx-xxxx-xxxx-xxxx-report000001
                      testId: xxxxxxxx-xxxx-xxxx-xxxx-test00000001
                      name: Homepage Audit
                      status: completed
                      summary:
                        totalPages: 1
                        scannedPages: 1
                        totalIssues: 7
                        issuesBySeverity:
                          critical: 1
                          serious: 3
                          moderate: 2
                          minor: 1
                        accessibilityScore: 87
                      createdAt: "2026-03-15T14:30:00Z"
                  total: 15
                  page: 1
                  limit: 20

  /accessibility/parse-sitemap:
    post:
      tags: [Accessibility]
      summary: Parse sitemap
      description: Fetches and parses an XML sitemap, returning the list of page URLs found. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              url: https://example.com/sitemap.xml
      responses:
        '200':
          description: Parsed page URL list.
          content:
            application/json:
              example:
                url: https://example.com/sitemap.xml
                pages:
                  - https://example.com/
                  - https://example.com/about
                  - https://example.com/contact
                count: 3

  /accessibility/validate-url:
    post:
      tags: [Accessibility]
      summary: Validate URL
      description: Checks whether a given URL is reachable before adding it to a test. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              url: https://example.com
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              example:
                success: true
                data:
                  valid: true

  /accessibility/tests/{testId}/sharing/enable:
    post:
      tags: [Accessibility]
      summary: Enable report sharing
      description: Creates or refreshes a public share token for the accessibility report. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessibilityShareEnableRequest'
            example:
              expiresIn: 7
              allowComments: false
      responses:
        '200':
          description: Share token created.
          content:
            application/json:
              example:
                success: true
                data:
                  shareToken: tok_abc123xyz
                  shareUrl: https://dev.hirafi.ai/shared/accessibility-reports/tok_abc123xyz

  /accessibility/tests/{testId}/sharing/disable:
    delete:
      tags: [Accessibility]
      summary: Disable report sharing
      description: Revokes the public share token for the accessibility report. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sharing disabled.
          content:
            application/json:
              example:
                success: true
                message: Accessibility report sharing disabled successfully

  /accessibility/tests/{testId}/sharing/status:
    get:
      tags: [Accessibility]
      summary: Get sharing status
      description: Returns whether sharing is enabled, and the active token/URL if so. Requires `a11y:read`.
      security:
        - BearerApiKey: []
      parameters:
        - in: path
          name: testId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sharing status.
          content:
            application/json:
              examples:
                not_shared:
                  summary: Sharing disabled
                  value:
                    success: true
                    data:
                      isShared: false
                shared:
                  summary: Sharing enabled
                  value:
                    success: true
                    data:
                      isShared: true
                      shareToken: tok_abc123xyz
                      shareUrl: https://dev.hirafi.ai/shared/accessibility-reports/tok_abc123xyz
