Koyeb Services API

openapi: 3.2.0
info:
  title: Koyeb Rest Services API
  description: 'The Koyeb API allows you to interact with the Koyeb platform in a simple, programmatic way using conventional HTTP requests.

    '
  version: 1.0.0
servers:
- url: https://app.koyeb.com
security:
- Bearer: []
tags:
- name: Services
paths:
  /v1/service_events:
    get:
      summary: List Service events
      operationId: ListServiceEvents
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServiceEventsReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: service_id
        description: (Optional) Filter on service id
        in: query
        required: false
        schema:
          type: string
      - name: types
        description: (Optional) Filter on service event types
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: limit
        description: (Optional) The number of items to return
        in: query
        required: false
        schema:
          type: string
      - name: offset
        description: (Optional) The offset in the list of item to return
        in: query
        required: false
        schema:
          type: string
      - name: order
        description: (Optional) Sorts the list in the ascending or the descending order
        in: query
        required: false
        schema:
          type: string
      tags:
      - Services
  /v1/services:
    get:
      summary: List Services
      operationId: ListServices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServicesReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: app_id
        description: (Optional) The id of the app
        in: query
        required: false
        schema:
          type: string
      - name: limit
        description: (Optional) The number of items to return
        in: query
        required: false
        schema:
          type: string
      - name: offset
        description: (Optional) The offset in the list of item to return
        in: query
        required: false
        schema:
          type: string
      - name: name
        description: (Optional) A filter for name
        in: query
        required: false
        schema:
          type: string
      - name: types
        description: (Optional) Filter on service types
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - INVALID_TYPE
            - WEB
            - WORKER
            - DATABASE
            - SANDBOX
      - name: statuses
        description: (Optional) Filter on service statuses
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - STARTING
            - HEALTHY
            - DEGRADED
            - UNHEALTHY
            - DELETING
            - DELETED
            - PAUSING
            - PAUSED
            - RESUMING
      - name: regions
        description: (Optional) Filter on regions
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: project_id
        description: (Optional) A filter for the project ID
        in: query
        required: false
        schema:
          type: string
      - name: ids
        description: (Optional) Filter on service ids
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - Services
    post:
      summary: Create Service
      operationId: CreateService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: dry_run
        description: If set only run validation
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateService'
        required: true
  /v1/services-autocomplete:
    post:
      summary: Autocomplete definition
      description: Generate autocomplete definition for a service
      operationId: Autocomplete
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutocompleteRequest'
        required: true
  /v1/services/{id}:
    get:
      summary: Get Service
      operationId: GetService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the Service
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
    delete:
      summary: Delete Service
      description: Service deletion is allowed for all status.
      operationId: DeleteService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the entity to delete
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
    put:
      summary: Update Service
      operationId: UpdateService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the entity to update
        in: path
        required: true
        schema:
          type: string
      - name: update_mask
        in: query
        required: false
        schema:
          type: string
      - name: dry_run
        description: If set, run validation and check that the service exists
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateService'
        required: true
    patch:
      summary: Update Service
      operationId: UpdateService2
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the entity to update
        in: path
        required: true
        schema:
          type: string
      - name: update_mask
        in: query
        required: false
        schema:
          type: string
      - name: dry_run
        description: If set, run validation and check that the service exists
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateService'
        required: true
  /v1/services/{id}/pause:
    post:
      summary: Pause Service
      description: "Service pause action is allowed for the following status:\n - starting\n - healthy\n - degraded\n - unhealthy\n - resuming"
      operationId: PauseService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the service to pause.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
  /v1/services/{id}/redeploy:
    post:
      summary: ReDeploy Service
      operationId: ReDeploy
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeployReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeployRequest.Info'
        required: true
  /v1/services/{id}/resume:
    post:
      summary: Resume Service
      description: "Service resume action is allowed for the following status:\n - paused"
      operationId: ResumeService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeServiceReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the service to pause.
        in: path
        required: true
        schema:
          type: string
      - name: skip_build
        description: 'If set to true, the build stage will be skipped and the image coming from the last successful build step will be used instead.

          The call fails if no previous successful builds happened.'
        in: query
        required: false
        schema:
          type: boolean
      - name: use_cache
        in: query
        required: false
        schema:
          type: boolean
      tags:
      - Services
  /v1/services/{id}/scale:
    get:
      summary: Get Service Scaling
      description: Returns the current scaling configuration for a service
      operationId: GetServiceScaling
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServiceScalingReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the service
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
    delete:
      summary: Delete Service Scaling
      description: "Deletes the manual scaling configuration for a service, reverting to \nthe scaling defined in the deployment definition."
      operationId: DeleteServiceScaling
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteServiceScalingReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the service
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
    put:
      summary: Update Service Scaling
      description: Stores or updates the scaling configuration for a service to use manual scaling
      operationId: UpdateServiceScaling
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateServiceScalingReply'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFields'
        '401':
          description: Returned when the token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Returned when the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Returned in case of server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      parameters:
      - name: id
        description: The id of the service to scale
        in: path
        required: true
        schema:
          type: string
      tags:
      - Services
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                scalings:
                  type: array
                  items:
                    $ref: '#/components/schemas/ManualServiceScaling'
                  title: The new scaling configuration
        required: true
components:
  schemas:
    ServiceListItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/Service.Type'
        organization_id:
          type: string
        project_id:
          type: string
        app_id:
          type: string
        updated_at:
          type: string
          format: date-time
        created_at:
  

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/koyeb/refs/heads/main/openapi/koyeb-services-api-openapi.yml