# generated: '2026-08-29'
# method: searched
# source: https://docs.soda.io/reference/soda-apis/rest-api/ — assembled from the OpenAPI 3.1.0
#   documents Soda publishes inline on each REST API reference page (16 pages, 103 operations,
#   zero conflicting definitions). Ownership: info.title 'Soda Cloud API v4', servers
#   https://cloud.soda.io + https://cloud.us.soda.io — Soda's own hosts.
openapi: 3.1.0
info:
  title: Soda Cloud API v4 — Runners
  version: v1
  description: The Runners surface of the Soda Cloud v4 public REST API — 4 operation(s). Harvested verbatim
    from the OpenAPI documents Soda publishes at https://docs.soda.io/reference/soda-apis/rest-api/.
  contact:
    name: Soda
    url: https://www.soda.io
servers:
- description: Cloud EU
  url: https://cloud.soda.io
- description: Cloud US
  url: https://cloud.us.soda.io
security:
- basicAuthApiKey: []
- cookieToken: []
tags:
- name: Runners
  description: Soda Cloud API Runner Endpoints
paths:
  /api/v1/runners:
    get:
      description: 'This endpoint allows you to list runners in your organization.


        This GET is a paginated API that uses the following parameters to request specific details:


        - `size`: Supply an integer value between 10 and 1000, inclusive. The default value is 10.


        - `page`: Supply an integer value. The default value is 0.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Tags


        `Runners`


        ## Rate limiting


        60 requests/60 seconds'
      operationId: GET/api/v1/runners
      parameters:
      - in: query
        name: page
        schema:
          type: integer
          format: int32
      - in: query
        name: size
        schema:
          type: integer
          format: int32
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiListRunnersResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: List runners
      tags:
      - Runners
    post:
      description: 'Creates an API key for a new self-hosted runner deployment.


        Returns the API key credentials (id and secret) to configure the runner. The credentials are only
        returned at creation time and cannot be retrieved later, so make sure to store them securely.


        After creation the runner does not immediately become visible in Soda Cloud. The runner needs
        to registers itself using the API key credentials before it becomes available.


        See [deployment instructions](https://go.soda.io/agent) for setting up the runner.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Runners`


        ## Rate limiting


        10 requests/60 seconds'
      operationId: POST/api/v1/runners
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiCreateRunnerResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Create a soda runner
      tags:
      - Runners
  /api/v1/runners/{runnerId}:
    get:
      description: 'This endpoint allows you to retrieve a specific runner by its ID.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Tags


        `Runners`


        ## Rate limiting


        1000 requests/60 seconds'
      operationId: GET/api/v1/runners/{runnerId}
      parameters:
      - in: path
        name: runnerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiGetRunnerResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get a runner
      tags:
      - Runners
    delete:
      description: "This endpoint allows you to delete a specific self-hosted runner by its ID. If the\
        \ runner is still in use, the request will fail with a `400 Bad Request` response. \n\nSoda-hosted\
        \ and virtual runners cannot be deleted through this endpoint.\n\n## Authentication\n\nUser authentication\
        \ required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication\
        \ header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically\
        \ on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_DATASOURCES_AND_AGENTS\
        \ to execute this call.\n\n## Tags\n\n`Runners`\n\n## Rate limiting\n\n10 requests/60 seconds"
      operationId: DELETE/api/v1/runners/{runnerId}
      parameters:
      - in: path
        name: runnerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiDeleteRunnerResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Delete a runner
      tags:
      - Runners
components:
  securitySchemes:
    basicAuthApiKey:
      scheme: basic
      type: http
    cookieToken:
      in: cookie
      name: token
      type: apiKey
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    PublicApiCreateRunnerResponse:
      type: object
      properties:
        apiKeyId:
          type: string
        apiKeySecret:
          type: string
    PublicApiDeleteRunnerResponse:
      type: object
    PublicApiGetRunnerResponse:
      type: object
      properties:
        runner:
          type: object
          $ref: '#/components/schemas/PublicApiRunnerDTO'
    PublicApiListRunnersResponse:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/PublicApiRunnerDTO'
        first:
          type: boolean
        last:
          type: boolean
        number:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
      required:
      - content
      - first
      - last
      - number
      - size
      - totalElements
      - totalPages
    PublicApiRunnerDTO:
      type: object
      properties:
        id:
          type: string
        isOnline:
          type: boolean
        label:
          type: string
        lastSeenTimestamp:
          type: string
          format: date-time
        name:
          type: string
        type:
          type: object
          $ref: '#/components/schemas/PublicApiRunnerTypeDTO'
        versions:
          type: object
          $ref: '#/components/schemas/PublicApiRunnerVersionsDTO'
    PublicApiRunnerTypeDTO:
      type: string
      enum:
      - SELF_HOSTED
      - SODA_HOSTED
    PublicApiRunnerVersionsDTO:
      type: object
      properties:
        agent:
          type: string
          deprecated: true
        library:
          type: string
        runner:
          type: string