Koyeb Services API
The Services API from Koyeb — 8 operation(s) for services.
The Services API from Koyeb — 8 operation(s) for services.
swagger: '2.0'
info:
title: Koyeb Rest activity 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
host: app.koyeb.com
schemes:
- https
security:
- Bearer: []
tags:
- name: Services
paths:
/v1/service_events:
get:
summary: List Service events
operationId: ListServiceEvents
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/ListServiceEventsReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: service_id
description: (Optional) Filter on service id
in: query
required: false
type: string
- name: types
description: (Optional) Filter on service event types
in: query
required: false
type: array
items:
type: string
collectionFormat: multi
- name: limit
description: (Optional) The number of items to return
in: query
required: false
type: string
- name: offset
description: (Optional) The offset in the list of item to return
in: query
required: false
type: string
- name: order
description: (Optional) Sorts the list in the ascending or the descending order
in: query
required: false
type: string
tags:
- Services
/v1/services:
get:
summary: List Services
operationId: ListServices
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/ListServicesReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: app_id
description: (Optional) The id of the app
in: query
required: false
type: string
- name: limit
description: (Optional) The number of items to return
in: query
required: false
type: string
- name: offset
description: (Optional) The offset in the list of item to return
in: query
required: false
type: string
- name: name
description: (Optional) A filter for name
in: query
required: false
type: string
- name: types
description: (Optional) Filter on service types
in: query
required: false
type: array
items:
type: string
enum:
- INVALID_TYPE
- WEB
- WORKER
- DATABASE
- SANDBOX
collectionFormat: multi
- name: statuses
description: (Optional) Filter on service statuses
in: query
required: false
type: array
items:
type: string
enum:
- STARTING
- HEALTHY
- DEGRADED
- UNHEALTHY
- DELETING
- DELETED
- PAUSING
- PAUSED
- RESUMING
collectionFormat: multi
- name: regions
description: (Optional) Filter on regions
in: query
required: false
type: array
items:
type: string
collectionFormat: multi
- name: project_id
description: (Optional) A filter for the project ID
in: query
required: false
type: string
tags:
- Services
post:
summary: Create Service
operationId: CreateService
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/CreateServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: service
in: body
required: true
schema:
$ref: '#/definitions/CreateService'
- name: dry_run
description: If set only run validation
in: query
required: false
type: boolean
tags:
- Services
/v1/services-autocomplete:
post:
summary: Autocomplete definition
description: Generate autocomplete definition for a service
operationId: Autocomplete
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/AutocompleteReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/AutocompleteRequest'
tags:
- Services
/v1/services/{id}:
get:
summary: Get Service
operationId: GetService
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/GetServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the Service
in: path
required: true
type: string
tags:
- Services
delete:
summary: Delete Service
description: Service deletion is allowed for all status.
operationId: DeleteService
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/DeleteServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the entity to delete
in: path
required: true
type: string
tags:
- Services
put:
summary: Update Service
operationId: UpdateService
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/UpdateServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the entity to update
in: path
required: true
type: string
- name: service
in: body
required: true
schema:
$ref: '#/definitions/UpdateService'
- name: update_mask
in: query
required: false
type: string
- name: dry_run
description: If set, run validation and check that the service exists
in: query
required: false
type: boolean
tags:
- Services
patch:
summary: Update Service
operationId: UpdateService2
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/UpdateServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the entity to update
in: path
required: true
type: string
- name: service
in: body
required: true
schema:
$ref: '#/definitions/UpdateService'
- name: update_mask
in: query
required: false
type: string
- name: dry_run
description: If set, run validation and check that the service exists
in: query
required: false
type: boolean
tags:
- Services
/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.
schema:
$ref: '#/definitions/PauseServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the service to pause.
in: path
required: true
type: string
tags:
- Services
/v1/services/{id}/redeploy:
post:
summary: ReDeploy Service
operationId: ReDeploy
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/RedeployReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
in: path
required: true
type: string
- name: info
in: body
required: true
schema:
$ref: '#/definitions/RedeployRequest.Info'
tags:
- Services
/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.
schema:
$ref: '#/definitions/ResumeServiceReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the service to pause.
in: path
required: true
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
type: boolean
- name: use_cache
in: query
required: false
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.
schema:
$ref: '#/definitions/GetServiceScalingReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the service
in: path
required: true
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.
schema:
$ref: '#/definitions/DeleteServiceScalingReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the service
in: path
required: true
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.
schema:
$ref: '#/definitions/UpdateServiceScalingReply'
'400':
description: Validation error
schema:
$ref: '#/definitions/ErrorWithFields'
'401':
description: Returned when the token is not valid.
schema:
$ref: '#/definitions/Error'
'403':
description: Returned when the user does not have permission to access the resource.
schema:
$ref: '#/definitions/Error'
'404':
description: Returned when the resource does not exist.
schema:
$ref: '#/definitions/Error'
'500':
description: Returned in case of server error.
schema:
$ref: '#/definitions/Error'
'503':
description: Service is unavailable.
schema:
$ref: '#/definitions/Error'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/google.rpc.Status'
parameters:
- name: id
description: The id of the service to scale
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
properties:
scalings:
type: array
items:
$ref: '#/definitions/ManualServiceScaling'
title: The new scaling configuration
tags:
- Services
definitions:
DeploymentProvisioningInfo.Stage.BuildAttempt:
type: object
properties:
id:
type: integer
format: int64
status:
$ref: '#/definitions/DeploymentProvisioningInfo.Stage.Status'
messages:
type: array
items:
type: string
started_at:
type: string
format: date-time
finished_at:
type: string
format: date-time
steps:
type: array
items:
$ref: '#/definitions/DeploymentProvisioningInfo.Stage.BuildAttempt.BuildStep'
image_pushed:
type: boolean
internal_failure:
type: boolean
retryable_failure:
type: boolean
wait_completion:
type: boolean
description: This flag is used to finalize the build, and continue the deployment in case of success, or cancel and potentially retry the build in case of failure.
DeploymentScalingTargetSleepIdleDelay:
type: object
properties:
value:
type: integer
format: int64
description: 'DEPRECATED: use deep_sleep_value instead.
Delay in seconds after which a service which received 0 request is put to deep sleep.'
deep_sleep_value:
type: integer
format: int64
description: Delay in seconds after which a service which received 0 request is put to deep sleep.
light_sleep_value:
type: integer
format: int64
description: Delay in seconds after which a service which received 0 request is put to light sleep.
DeploymentProxyPort:
type: object
properties:
port:
type: integer
format: int64
protocol:
$ref: '#/definitions/ProxyPortProtocol'
RedeployRequest.Info:
type: object
properties:
deployment_group:
type: string
sha:
type: string
use_cache:
type: boolean
skip_build:
type: boolean
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.'
ErrorWithFields:
type: object
properties:
status:
type: integer
format: int32
code:
type: string
message:
type: string
fields:
type: array
items:
$ref: '#/definitions/ErrorField'
DeleteServiceScalingReply:
type: object
title: Empty reply - success is indicated by no error
GitDeploymentMetadata:
type: object
properties:
last_provisioned_deployment_id:
type: string
git_env:
$ref: '#/definitions/GitEnvDeploymentMetadata'
ArchiveSource:
type: object
properties:
id:
type: string
title: The ID of the archive to deploy
buildpack:
$ref: '#/definitions/BuildpackBuilder'
docker:
$ref: '#/definitions/DockerBuilder'
UpdateServiceReply:
type: object
properties:
service:
$ref: '#/definitions/Service'
title: The entity updated
UpdateService:
type: object
properties:
definition:
$ref: '#/definitions/DeploymentDefinition'
metadata:
$ref: '#/definitions/DeploymentMetadata'
skip_build:
type: boolean
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.'
save_only:
type: boolean
title: If set, do not trigger a deployment, only store the new settings
life_cycle:
$ref: '#/definitions/ServiceLifeCycle'
DeleteServiceReply:
type: object
DeploymentDefinition.Type:
type: string
enum:
- INVALID
- WEB
- WORKER
- DATABASE
- SANDBOX
default: INVALID
DeploymentDatabaseInfo:
type: object
properties:
neon_postgres:
$ref: '#/definitions/DeploymentNeonPostgresDatabaseInfo'
ServiceListItem:
type: object
properties:
id:
type: string
name:
type: string
type:
$ref: '#/definitions/Service.Type'
organization_id:
type: string
app_id:
type: string
updated_at:
type: string
format: date-time
created_at:
type: string
format: date-time
status:
$ref: '#/definitions/Service.Status'
messages:
type: array
items:
type: string
version:
type: string
format: uint64
title: A version updated whenever this state changes (useful for caching)
state:
$ref: '#/definitions/ServiceState'
active_deployment_id:
type: string
latest_deployment_id:
type: string
life_cycle:
$ref: '#/definitions/ServiceLifeCycle'
HTTPHealthCheck:
type: object
properties:
port:
type: integer
format: int64
title: The port to use to perform the health check, must be declared in the ports section
path:
type: string
title: The path to use to perform the HTTP health check
method:
type: string
title: An optional HTTP method to use to perform the health check, default is GET
headers:
type: array
items:
$ref: '#/definitions/HTTPHeader'
title: An optional list of HTTP headers to provide when performing the request, default is empty
TriggerGitDeploymentMetadata:
type: object
properties:
provider:
$ref: '#/definitions/TriggerGitDeploymentMetadata.Provider'
repository:
type: string
branch:
type: string
sha:
type: string
message:
type: string
sender_username:
type: string
sender_avatar_url:
type: string
sender_profile_url:
type: string
DesiredDeployment.Group:
type: object
properties:
name:
type: string
deployment_ids:
type: array
items:
type: string
BasicAuthPolicy:
type: object
properties:
username:
type: string
password:
type: string
Deployment.Role:
type: string
enum:
- INVALID
- ACTIVE
- UPCOMING
- CURRENT
default: INVALID
RedeployReply:
type: object
properties:
deployment:
$ref: '#/definitions/Deployment'
title: The entity updated
DeploymentMetadata:
type: object
properties:
trigger:
$ref: '#/definitions/TriggerDeploymentMetadata'
database:
$ref: '#/definitions/DatabaseDeploymentMetadata'
git:
$ref: '#/definitions/GitDeploymentMetadata'
archive:
$ref: '#/definitions/ArchiveDeploymentMetadata'
proxy_ports:
type: array
items:
$ref: '#/definitions/DeploymentProxyPortMetadata'
DeploymentProvisioningInfo.Stage.BuildAttempt.BuildStep:
type: object
properties:
name:
type: string
status:
$ref: '#/definitions/DeploymentProvisioningInfo.Stage.Status'
messages:
type: array
items:
type: string
started_at:
type: string
format: date-time
finished_at:
type: string
format: date-time
BuildpackBuilder:
type: object
properties:
build_command:
type: string
title: A command used to override the build command, run after all build steps
run_command:
type: string
title: A command used to override the default run command
privileged:
type: boolean
title: A flag to run the container in privileged mode
DeploymentStrategyType:
type: string
enum:
- DEPLOYMENT_STRATEGY_TYPE_INVALID
- DEPLOYMENT_STRATEGY_TYPE_DEFAULT
- DEPLOYMENT_STRATEGY_TYPE_CANARY
- DEPLOYMENT_STRATEGY_TYPE_ROLLING
- DEPLOYMENT_STRATEGY_TYPE_BLUE_GREEN
- DEPLOYMENT_STRATEGY_TYPE_IMMEDIATE
default: DEPLOYMENT_STRATEGY_TYPE_INVALID
description: " - DEPLOYMENT_STRATEGY_TYPE_INVALID: DEPRECATED: Use DEPLOYMENT_STRATEGY_TYPE_DEFAULT instead.\n - DEPLOYMENT_STRATEGY_TYPE_DEFAULT: Default/unspecified strategy (resolves to platform default, currently ROLLING).\n - DEPLOYMENT_STRATEGY_TYPE_CANARY: Use canary strategy.\n - DEPLOYMENT_STRATEGY_TYPE_ROLLING: Use rolling strategy.\n - DEPLOYMENT_STRATEGY_TYPE_BLUE_GREEN: Use blue green strategy.\n - DEPLOYMENT_STRATEGY_TYPE_IMMEDIATE: Use immediate strategy."
NeonPostgresDatabase.NeonDatabase:
type: object
properties:
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/koyeb/refs/heads/main/openapi/koyeb-services-api-openapi.yml