Signadot Sandboxes API

openapi: 3.2.0
info:
  contact: {}
  description: API for Signadot Sandboxes
  title: Signadot Cluster Sandboxes API
  version: '2.0'
servers:
- url: https://api.signadot.com/api/v2
tags:
- name: Sandboxes
paths:
  /orgs/{orgName}/sandboxes:
    get:
      description: List all sandboxes under the specified Signadot org.
      operationId: list-sandboxes
      parameters:
      - description: Signadot Org Name
        in: path
        name: orgName
        required: true
        x-example: my-company
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Sandbox'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: List sandboxes
      tags:
      - Sandboxes
  /orgs/{orgName}/sandboxes/{sandboxName}:
    delete:
      description: Delete a given sandbox.
      operationId: delete-sandbox
      parameters:
      - description: Signadot Org Name
        in: path
        name: orgName
        required: true
        x-example: my-company
        schema:
          type: string
      - description: Sandbox Name
        in: path
        name: sandboxName
        required: true
        x-example: my-sandbox
        schema:
          type: string
      - description: force
        in: query
        name: force
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete a sandbox
      tags:
      - Sandboxes
    get:
      description: Fetch the details about a given sandbox.
      operationId: get-sandbox
      parameters:
      - description: Signadot Org Name
        in: path
        name: orgName
        required: true
        x-example: my-company
        schema:
          type: string
      - description: Sandbox Name
        in: path
        name: sandboxName
        required: true
        x-example: my-sandbox
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get a sandbox
      tags:
      - Sandboxes
    put:
      description: Creates or updates a sandbox with the provided parameters.
      operationId: apply-sandbox
      parameters:
      - description: Signadot Org Name
        in: path
        name: orgName
        required: true
        x-example: my-company
        schema:
          type: string
      - description: Sandbox Name
        in: path
        name: sandboxName
        required: true
        x-example: my-sandbox
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create or update a sandbox
      tags:
      - Sandboxes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sandbox'
        description: Request to create sandbox
        required: true
components:
  schemas:
    sandbox.ForkOf:
      properties:
        kind:
          description: Kind of the baseline workload.
          example: Deployment
          type: string
        name:
          description: Name of the entity within the Kubernetes cluster.
          example: my-frontend
          type: string
        namespace:
          description: Namespace within which the entity lives in the Kubernetes cluster.
          example: default
          type: string
      required:
      - kind
      - name
      - namespace
      type: object
    sandboxes.Argument:
      properties:
        name:
          description: Name indicates the name of the associated parameter.
          type: string
        value:
          description: 'Value indicates the value passed to the parameter of

            the same name.'
          type: string
        valueFrom:
          allOf:
          - $ref: '#/components/schemas/sandboxes.ArgValueFrom'
          description: ValueFrom indicates from where to grab the value
      type: object
    sandbox.EnvVar:
      properties:
        container:
          description: name of container to which it applies
          type: string
        name:
          description: environmental variable name
          type: string
        operation:
          allOf:
          - $ref: '#/components/schemas/sandboxes.EnvOpName'
          description: upsert or delete
        value:
          description: environmental variable value
          type: string
        valueFrom:
          allOf:
          - $ref: '#/components/schemas/sandbox.EnvValueFrom'
          description: environmental variable dynamic value
      type: object
    jobs.Phase:
      enum:
      - queued
      - running
      - failed
      - succeeded
      - canceled
      type: string
      x-enum-varnames:
      - QueuedPhase
      - RunningPhase
      - FailedPhase
      - SucceededPhase
      - CanceledPhase
    defaults.Default:
      properties:
        class:
          $ref: '#/components/schemas/defaults.DefaultClass'
        createdAt:
          type: string
        resourceKind:
          $ref: '#/components/schemas/defaults.ResourceKind'
        updatedAt:
          type: string
        value: {}
      type: object
    sandboxes.Routing:
      properties:
        forwards:
          items:
            $ref: '#/components/schemas/sandboxes.Forward'
          type: array
      type: object
    sandbox.ForkEndpoint:
      properties:
        name:
          description: Name of the endpoint
          type: string
        port:
          description: Port it will map to on the forked workload
          type: integer
        protocol:
          description: Protocol that this endpoint uses
          type: string
      type: object
    sandbox.Customizations:
      properties:
        env:
          description: Environment variable modifications that will be applied to the forked workload
          items:
            $ref: '#/components/schemas/sandbox.EnvVar'
          type: array
        images:
          description: One or more docker images that will be applied to the forked workload
          items:
            $ref: '#/components/schemas/sandbox.Image'
          type: array
        patch:
          $ref: '#/components/schemas/sandbox.CustomPatch'
      type: object
    ErrorResponse:
      properties:
        code:
          type: integer
        error:
          type: string
        requestId:
          type: string
      type: object
    sandbox.Spec:
      properties:
        cluster:
          description: Cluster within which this sandbox should be created
          type: string
        defaultRouteGroup:
          allOf:
          - $ref: '#/components/schemas/sandbox.DefaultRouteGroup'
          description: DefaultRouteGroup can be used to define route group endpoints for the sandbox.
        description:
          description: Description of the purpose of this sandbox
          type: string
        disableSandboxTrafficManager:
          description: 'DisableSandboxTrafficManager provides a way of turning off the sandbox

            traffic manager for forks in this sandbox.

            Deprecated in operators since v1.1. The sandbox traffic manager has been

            retired.'
          type: boolean
        endpoints:
          description: Deprecated. Use defaultRouteGroup.Endpoints instead.
          items:
            $ref: '#/components/schemas/sandbox.HostEndpoint'
          type: array
          x-omitempty: 'true'
        forks:
          description: Forks is the specification of each forked entity
          items:
            $ref: '#/components/schemas/sandbox.Fork'
          type: array
        labels:
          additionalProperties:
            type: string
          description: Labels are used to specify metadata associated with the sandbox as key-value pairs.
          type: object
        middleware:
          description: Request Middleware
          items:
            $ref: '#/components/schemas/sandboxes.Middleware'
          type: array
        resources:
          description: Resources specifies each required resource to spin up the sandbox
          items:
            $ref: '#/components/schemas/sandbox.Resource'
          type: array
        routing:
          allOf:
          - $ref: '#/components/schemas/sandboxes.Routing'
          description: Routing specification
        ttl:
          allOf:
          - $ref: '#/components/schemas/sandbox.TTL'
          description: 'TTL gives the maximum lifetime of the sandbox.

            It may be empty, in which case it defaults to forever.'
        virtual:
          description: Virtual Workloads
          items:
            $ref: '#/components/schemas/virtual'
          type: array
      required:
      - cluster
      - forks
      type: object
    sandboxes.Forward:
      properties:
        appProtocol:
          type: string
        name:
          type: string
        port:
          type: integer
        toLocal:
          type: string
      type: object
    sandboxes.MiddlewareMatch:
      properties:
        workload:
          description: 'Workload specifies a glob which matches

            each workload name in the spec.'
          type: string
      type: object
    sandboxes.EnvOpName:
      enum:
      - upsert
      - delete
      type: string
      x-enum-varnames:
      - EnvOpUpsert
      - EnvOpDelete
    defaults.DefaultClass:
      enum:
      - ttl
      type: string
      x-enum-varnames:
      - TTL
    sandbox.TunnelStatus:
      properties:
        health:
          properties:
            connected:
              type: boolean
            lastCheckTime:
              type: string
            lastConnectedTime:
              type: string
          type: object
      type: object
    sandbox.TTL:
      properties:
        duration:
          description: "Duration represents the duration until sandbox end of life.\nIt should be an unsigned integer not exceeding 32 bits followed by\na units character, which can be one of the following.\n  - 'm' for minutes\n  - 'h' for hours\n  - 'd' for days\n  - 'w' for weeks"
          type: string
        offsetFrom:
          description: 'OffsetFrom indicates what the Duration is relative to.  It

            may be the empty string, "createdAt" or "updatedAt".  The empty string

            defaults to meaning "createdAt".'
          type: string
      type: object
    sandbox.EnvValueFrom:
      properties:
        configMap:
          $ref: '#/components/schemas/sandbox.EnvValueFromMap'
        fork:
          $ref: '#/components/schemas/sandbox.EnvValueFromFork'
        resource:
          $ref: '#/components/schemas/sandbox.EnvValueFromResource'
        secret:
          $ref: '#/components/schemas/sandbox.EnvValueFromMap'
      type: object
    sandbox.CustomPatch:
      properties:
        type:
          $ref: '#/components/schemas/sandboxes.PatchType'
        value:
          type: string
      type: object
    testexecutions.Phase:
      enum:
      - pending
      - in_progress
      - failed
      - succeeded
      - canceled
      type: string
      x-enum-varnames:
      - PendingPhase
      - InProgressPhase
      - FailedPhase
      - SucceededPhase
      - CanceledPhase
    sandbox.Fork:
      properties:
        customizations:
          allOf:
          - $ref: '#/components/schemas/sandbox.Customizations'
          description: Customizations specify the customizations we will apply on the fork
        endpoints:
          description: Deprecated. Use defaultRouteGroup.Endpoints instead.
          items:
            $ref: '#/components/schemas/sandbox.ForkEndpoint'
          type: array
          x-omitempty: 'true'
        forkOf:
          allOf:
          - $ref: '#/components/schemas/sandbox.ForkOf'
          description: 'ForkOf specifies the target workload that we will be forking.  In this usage

            the Kind of the ForkOf object must not be a service.'
        name:
          type: string
      type: object
    sandbox.Readiness:
      properties:
        forwards:
          description: Forwards status
          items:
            $ref: '#/components/schemas/sandboxes.ForwardStatus'
          type: array
        jobs:
          allOf:
          - $ref: '#/components/schemas/sandboxes.JobsSummary'
          description: status of the jobs running in the context of the given sandbox
        message:
          description: 'Message is a human readable explanation of why

            the sandbox is healthy or not.'
          type: string
        ready:
          description: 'Ready indicates whether the sandbox is ready,

            meaning that it can be used for testing.'
          type: boolean
        reason:
          description: 'Reason is a machine readable explanation of why

            the sandbox is healthy or not.'
          type: string
        scheduledDeleteTime:
          description: 'ScheduledDeleteTime returns the formatted and computed ttl based on the Duration

            and OffsetFrom'
          type: string
        testExecutions:
          allOf:
          - $ref: '#/components/schemas/sandbox.TestExecutionsSummary'
          description: status of the test executions running in the context of the given sandbox
      type: object
    sandbox.Endpoint:
      properties:
        baselineUrl:
          type: string
        host:
          type: string
        name:
          type: string
        port:
          type: integer
        protocol:
          type: string
        routeType:
          type: string
        target:
          type: string
        url:
          type: string
      type: object
    defaults.ResourceKind:
      enum:
      - sandbox
      - routegroup
      type: string
      x-enum-varnames:
      - SandboxResourceKind
      - RouteGroupResourceKind
    EmptyResponse:
      type: object
    sandbox.EnvValueFromResource:
      properties:
        name:
          type: string
        outputKey:
          type: string
      type: object
    sandboxes.ArgValueFrom:
      properties:
        forward:
          type: string
      type: object
    sandbox.HostEndpoint:
      properties:
        host:
          description: Hostname that this endpoint points to
          type: string
        name:
          description: Name of the endpoint
          type: string
        port:
          description: Port it will map to on the specified host
          type: integer
        protocol:
          description: Protocol that this endpoint uses
          type: string
      type: object
    sandbox.TestExecutionsSummaryChecks:
      properties:
        failed:
          type: integer
        passed:
          type: integer
      type: object
    jobs.PhaseCount:
      properties:
        count:
          type: integer
        phase:
          $ref: '#/components/schemas/jobs.Phase'
      type: object
    sandbox.EnvValueFromFork:
      properties:
        expression:
          type: string
        forkOf:
          $ref: '#/components/schemas/sandbox.ForkOf'
      type: object
    sandbox.TestExecutionsSummary:
      properties:
        checks:
          $ref: '#/components/schemas/sandbox.TestExecutionsSummaryChecks'
        phaseCounts:
          items:
            $ref: '#/components/schemas/testexecutions.PhaseCount'
          type: array
        trafficDiffs:
          $ref: '#/components/schemas/sandbox.TestExecutionsSummaryTrafficDiffs'
      type: object
    local.From:
      properties:
        kind:
          description: Kind of the baseline workload.
          example: Deployment
          type: string
        name:
          description: Name of the entity within the Kubernetes cluster.
          example: my-frontend
          type: string
        namespace:
          description: Namespace within which the entity lives in the Kubernetes cluster.
          example: default
          type: string
      required:
      - kind
      - name
      - namespace
      type: object
    sandboxes.PatchType:
      enum:
      - strategic
      - merge
      - json
      - signadot/env
      - signadot/image
      type: string
      x-enum-varnames:
      - PatchTypeStrategic
      - PatchTypeMerge
      - PatchTypeJSON
      - PatchTypeSDEnv
      - PatchTypeSDImage
    Sandbox:
      properties:
        createdAt:
          type: string
        defaults:
          $ref: '#/components/schemas/defaults.CompositeDefaults'
        endpoints:
          items:
            $ref: '#/components/schemas/sandbox.Endpoint'
          type: array
        name:
          description: Human-readable name of this sandbox
          type: string
        routingKey:
          type: string
        spec:
          $ref: '#/components/schemas/sandbox.Spec'
        status:
          allOf:
          - $ref: '#/components/schemas/sandbox.Readiness'
          description: Status *sdv1.SandboxReadiness `json:"status,omitempty"`
        updatedAt:
          type: string
      type: object
    sandboxes.ForwardStatus:
      properties:
        name:
          type: string
        tunnel:
          $ref: '#/components/schemas/sandbox.TunnelStatus'
      type: object
    sandboxes.JobsSummary:
      properties:
        phaseCounts:
          items:
            $ref: '#/components/schemas/jobs.PhaseCount'
          type: array
      type: object
    sandbox.Image:
      properties:
        container:
          description: Container is the container this image must apply to in the forked workload
          type: string
        image:
          description: Name of the image (e.g. gcr.io/my-image/repo:my-tag)
          type: string
      type: object
    sandbox.DefaultRouteGroup:
      properties:
        endpoints:
          items:
            $ref: '#/components/schemas/endpoints.Endpoint'
          type: array
      type: object
    sandbox.TestExecutionsSummaryTrafficDiffs:
      properties:
        green:
          type: integer
        red:
          type: integer
        yellow:
          type: integer
      type: object
    sandbox.EnvValueFromMap:
      properties:
        key:
          type: string
        name:
          type: string
        optional:
          type: boolean
      type: object
    sandbox.Resource:
      properties:
        name:
          description: Unique name for this resource (used to reference it in env vars and files)
          type: string
        params:
          additionalProperties:
            type: string
          description: Plugin-specific parameters as key-value pairs
          type: object
        plugin:
          description: Plugin name, optionally suffixed with @version (e.g. my-plugin@1.2.0)
          type: string
      type: object
    defaults.CompositeDefaults:
      properties:
        cluster:
          items:
            $ref: '#/components/schemas/defaults.Default'
          type: array
      type: object
    virtual:
      properties:
        name:
          type: string
        workload:
          $ref: '#/components/schemas/local.From'
      type: object
    endpoints.Endpoint:
      properties:
        name:
          type: string
        target:
          type: string
      type: object
    testexecutions.PhaseCount:
      properties:
        count:
          type: integer
        phase:
          $ref: '#/components/schemas/testexecutions.Phase'
      type: object
    sandboxes.Middleware:
      properties:
        args:
          description: Middleware arguments
          items:
            $ref: '#/components/schemas/sandboxes.Argument'
          type: array
        match:
          description: 'Matches specifies a disjunction of matching criteria for dispatching

            the middleware.  Any empty list means don''t dispatch anything.'
          items:
            $ref: '#/components/schemas/sandboxes.MiddlewareMatch'
          type: array
        name:
          description: Middleware name
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: signadot-api-key
      type: apiKey