> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techslayers.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Start run

> Start a new external RTS Builder run for an exposed kit slug.

# Start run

## Request body

The public contract expects an `inputs` object. The exact input names depend on the exposed kit's runtime variables.

## Success shape

<Warning>
  The external success payload could not be verified directly because the live environment rejected `POST /api/v1/external/{kit_slug}` for both:

  * the original user-provided key
  * a newly created team API key in the same tenant as an exposed kit
</Warning>

The schema rendered above is therefore based on the internally verified builder run-start payload and is labeled as inferred in the OpenAPI document.

## Related schemas

* [StartRunRequest](/rts-builder/schemas/start-run-request)
* [StartRunResponse (Inferred)](/rts-builder/schemas/start-run-response-inferred)
* [ErrorResponse](/rts-builder/schemas/error-response)


## OpenAPI

````yaml openapi/rts-builder.json POST /api/v1/external/{kitSlug}
openapi: 3.0.3
info:
  title: RTS Builder External API
  version: '2026-03-29'
  description: >-
    Public API for listing externally accessible RTS Builder kits, starting
    runs, polling run status, and retrieving parsed results. Verified against
    the live service on March 28, 2026 Pacific / March 29, 2026 UTC. The 201
    response for POST /api/v1/external/{kitSlug} is inferred from the internally
    verified builder run endpoint because external start access returned 403
    during live testing.
servers:
  - url: https://rts-builder.slayers.tech
    description: RTS Builder production
security:
  - ApiKeyAuth: []
tags:
  - name: External Kits
    description: Kit discovery and run creation.
  - name: Runs
    description: Run lifecycle and result retrieval.
paths:
  /api/v1/external/{kitSlug}:
    post:
      tags:
        - External Kits
      summary: Start a run
      description: >-
        Starts a new run for an exposed kit slug. The success schema below is
        inferred from the internally verified /api/kits/{id}/run payload because
        the external endpoint returned 403 for the live exposed test kit on
        March 29, 2026 UTC.
      operationId: startExternalRun
      parameters:
        - name: kitSlug
          in: path
          required: true
          description: Kit slug shown in RTS Builder.
          schema:
            type: string
            example: external-api-docs-probe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartRunRequest'
            examples:
              domainScan:
                summary: Single target input
                value:
                  inputs:
                    target: example.com
      responses:
        '201':
          description: >-
            Run started. Response body shape is inferred, not externally
            verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartRunResponseInferred'
              examples:
                inferred:
                  summary: Internally observed run start payload
                  value:
                    message: run started
                    run:
                      id: 86fb79ef-f82c-4e8b-b8ab-23d0ccbff71b
                      kit_id: 8d4be855-4208-40c7-9435-df8e2b35f8ad
                      kit_version: 1
                      status: pending
                      inputs:
                        target: techslayers.ca
                      use_proxy: false
                      created_at: '2026-03-29T02:31:49.292757Z'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingHeader:
                  value:
                    error: missing X-API-Key header
                invalidKey:
                  value:
                    error: invalid API key
        '403':
          description: The API key authenticated but does not have access to the kit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                accessDenied:
                  value:
                    error: API key does not have access to this kit
        '404':
          description: Kit slug not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  value:
                    error: kit not found
components:
  schemas:
    StartRunRequest:
      type: object
      required:
        - inputs
      properties:
        inputs:
          $ref: '#/components/schemas/InputMap'
      example:
        inputs:
          target: example.com
    StartRunResponseInferred:
      type: object
      description: >-
        Observed on the internal `/api/kits/{id}/run` endpoint. Expected to be
        close to the external response, but not externally verified as of March
        29, 2026 UTC.
      required:
        - message
        - run
      properties:
        message:
          type: string
          example: run started
        run:
          $ref: '#/components/schemas/RunRecord'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    InputMap:
      type: object
      description: Runtime variable values keyed by kit variable name.
      additionalProperties:
        description: >-
          Kit input value. Type depends on the kit variable definition and may
          be scalar, object, array, or null.
      example:
        target: example.com
    RunRecord:
      type: object
      required:
        - id
        - kit_id
        - kit_version
        - status
        - inputs
        - use_proxy
        - created_at
      properties:
        id:
          type: string
          format: uuid
        kit_id:
          type: string
          format: uuid
        kit_version:
          type: integer
          minimum: 1
        status:
          $ref: '#/components/schemas/RunState'
        inputs:
          $ref: '#/components/schemas/InputMap'
        use_proxy:
          type: boolean
        created_at:
          type: string
          format: date-time
    RunState:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Team-scoped RTS Builder API key.

````