Koyeb Deployments API
The Deployments API from Koyeb — 5 operation(s) for deployments.
The Deployments API from Koyeb — 5 operation(s) for deployments.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/koyeb-deployments-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Koyeb Rest Deployments 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: Deployments
paths:
/v1/deployment/{id}/scaling:
get:
summary: Get Deployment Scaling
operationId: GetDeploymentScaling
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/GetDeploymentScalingReply'
'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
- name: region
description: (Optional) Filter on region
in: query
required: false
schema:
type: string
- name: replica_index
description: (Optional) Filter on replica_index
in: query
required: false
schema:
type: integer
format: int64
tags:
- Deployments
/v1/deployment_events:
get:
summary: List Deployment events
operationId: ListDeploymentEvents
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDeploymentEventsReply'
'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: deployment_id
description: (Optional) Filter on deployment id
in: query
required: false
schema:
type: string
- name: types
description: (Optional) Filter on deployment 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:
- Deployments
/v1/deployments:
get:
summary: List Deployments
operationId: ListDeployments
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDeploymentsReply'
'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) Filter on application id
in: query
required: false
schema:
type: string
- name: service_id
description: (Optional) Filter on service id
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: statuses
description: (Optional) Filter on statuses
in: query
required: false
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- PENDING
- PROVISIONING
- SCHEDULED
- CANCELING
- CANCELED
- ALLOCATING
- STARTING
- HEALTHY
- DEGRADED
- UNHEALTHY
- STOPPING
- STOPPED
- ERRORING
- ERROR
- STASHED
- SLEEPING
- name: ids
description: (Optional) Filter on deployment ids
in: query
required: false
style: form
explode: true
schema:
type: array
items:
type: string
tags:
- Deployments
/v1/deployments/{id}:
get:
summary: Get Deployment
operationId: GetDeployment
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/GetDeploymentReply'
'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 deployment
in: path
required: true
schema:
type: string
tags:
- Deployments
/v1/deployments/{id}/cancel:
post:
summary: Cancel Deployment
description: "Deployment cancellation is allowed for the following status:\n - pending\n - provisioning\n - scheduled"
operationId: CancelDeployment
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelDeploymentReply'
'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 deployment to cancel.
in: path
required: true
schema:
type: string
tags:
- Deployments
components:
schemas:
ListDeploymentsReply:
type: object
properties:
deployments:
type: array
items:
$ref: '#/components/schemas/DeploymentListItem'
title: The collection of deployments
limit:
type: integer
format: int64
title: The limit in the request
offset:
type: integer
format: int64
title: The offset in the request
count:
type: integer
format: int64
title: The total number of items
has_next:
type: boolean
title: If there is more items after in the collection
NeonPostgresDatabase:
type: object
properties:
pg_version:
type: integer
format: int64
region:
type: string
instance_type:
type: string
roles:
type: array
items:
$ref: '#/components/schemas/NeonPostgresDatabase.NeonRole'
databases:
type: array
items:
$ref: '#/components/schemas/NeonPostgresDatabase.NeonDatabase'
ArchiveSource:
type: object
properties:
id:
type: string
title: The ID of the archive to deploy
buildpack:
$ref: '#/components/schemas/BuildpackBuilder'
docker:
$ref: '#/components/schemas/DockerBuilder'
DeploymentRoute:
type: object
properties:
port:
type: integer
format: int64
path:
type: string
security_policies:
$ref: '#/components/schemas/SecurityPolicies'
Deployment.Status:
type: string
enum:
- PENDING
- PROVISIONING
- SCHEDULED
- CANCELING
- CANCELED
- ALLOCATING
- STARTING
- HEALTHY
- DEGRADED
- UNHEALTHY
- STOPPING
- STOPPED
- ERRORING
- ERROR
- STASHED
- SLEEPING
default: PENDING
GitSource:
type: object
properties:
repository:
type: string
description: 'A url to a git repository (contains the provider as well) .e.g: github.com/koyeb/test.'
branch:
type: string
title: A git branch that will be tracked for new commits and deployments will be created
tag:
type: string
title: A git tag that should be built
sha:
type: string
title: A git commit that should be built (useful for pinning to a commit, this will always be set when a deployment is created by a code push)
build_command:
type: string
title: A command used to override the build command, run after all build steps — deprecated, use buildpack.build_command instead
run_command:
type: string
title: A command used to override the default run command - deprecated, use buildpack.run_command instead
no_deploy_on_push:
type: boolean
title: A flag to disable a new deployment when a push event is detected
workdir:
type: string
title: A subdirectory to use as the build directory
buildpack:
$ref: '#/components/schemas/BuildpackBuilder'
docker:
$ref: '#/components/schemas/DockerBuilder'
NetworkPolicy:
type: object
properties:
egress:
$ref: '#/components/schemas/EgressPolicy'
mesh:
$ref: '#/components/schemas/Mesh'
description: 'Mesh configuration. Orthogonal to the top-level DeploymentDefinition.mesh
field, which only toggles the mesh on/off. This sub-message controls
WHICH services can reach each other over the mesh when it is on.'
DeploymentNeonPostgresDatabaseInfo:
type: object
properties:
active_time_seconds:
type: string
format: int64
compute_time_seconds:
type: string
format: int64
written_data_bytes:
type: string
format: int64
data_transfer_bytes:
type: string
format: int64
data_storage_bytes_hour:
type: string
format: int64
server_host:
type: string
server_port:
type: integer
format: int64
endpoint_state:
type: string
endpoint_last_active:
type: string
format: date-time
default_branch_id:
type: string
default_branch_name:
type: string
default_branch_state:
type: string
default_branch_logical_size:
type: string
format: int64
roles:
type: array
items:
$ref: '#/components/schemas/DeploymentNeonPostgresDatabaseInfoRole'
DockerBuilder:
type: object
properties:
dockerfile:
type: string
title: A path to the Dockerfile
entrypoint:
type: array
items:
type: string
title: The docker ENTRYPOINT
command:
type: string
title: The docker CMD
args:
type: array
items:
type: string
title: The docker CMD args
target:
type: string
title: The target for multi-stage builds
privileged:
type: boolean
title: A flag to run the container in privileged mode
DeploymentDatabaseInfo:
type: object
properties:
neon_postgres:
$ref: '#/components/schemas/DeploymentNeonPostgresDatabaseInfo'
DockerSource:
type: object
properties:
image:
type: string
command:
type: string
args:
type: array
items:
type: string
image_registry_secret:
type: string
entrypoint:
type: array
items:
type: string
privileged:
type: boolean
title: A flag to run the container in privileged mode
ProxyPortProtocol:
type: string
enum:
- tcp
default: tcp
Error:
type: object
properties:
status:
type: integer
format: int32
code:
type: string
message:
type: string
DeploymentHealthCheck:
type: object
properties:
grace_period:
type: integer
format: int64
title: An optional initial period in seconds to wait for the instance to become healthy, default is 5s
interval:
type: integer
format: int64
title: An optional period in seconds between two health checks, default is 60s
restart_limit:
type: integer
format: int64
title: An optional number of consecutive failures before attempting to restart the service, default is 3
timeout:
type: integer
format: int64
title: An optional maximum time to wait in seconds before considering the check as a failure, default is 5s
tcp:
$ref: '#/components/schemas/TCPHealthCheck'
http:
$ref: '#/components/schemas/HTTPHealthCheck'
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.
DeploymentProxyPortMetadata:
type: object
properties:
host:
type: string
public_port:
type: integer
format: int64
port:
type: integer
format: int64
protocol:
$ref: '#/components/schemas/ProxyPortProtocol'
ConfigFile:
type: object
properties:
path:
type: string
title: the path where the file is copied
permissions:
type: string
title: the permissions of the file in format 0644
content:
type: string
title: the content of the file
DeploymentEvent:
type: object
properties:
id:
type: string
when:
type: string
format: date-time
organization_id:
type: string
deployment_id:
type: string
type:
type: string
message:
type: string
metadata:
type: object
DeploymentProvisioningInfo.Stage:
type: object
properties:
name:
type: string
status:
$ref: '#/components/schemas/DeploymentProvisioningInfo.Stage.Status'
messages:
type: array
items:
type: string
started_at:
type: string
format: date-time
finished_at:
type: string
format: date-time
build_attempts:
type: array
items:
$ref: '#/components/schemas/DeploymentProvisioningInfo.Stage.BuildAttempt'
GitDeploymentMetadata:
type: object
properties:
last_provisioned_deployment_id:
type: string
git_env:
$ref: '#/components/schemas/GitEnvDeploymentMetadata'
GetDeploymentReply:
type: object
properties:
deployment:
$ref: '#/components/schemas/Deployment'
DeploymentDefinition.Type:
type: string
enum:
- INVALID
- WEB
- WORKER
- DATABASE
- SANDBOX
default: INVALID
DeploymentScalingTargetRequestsResponseTime:
type: object
properties:
value:
type: integer
format: int64
quantile:
type: integer
format: int64
description: 'The quantile to use for autoscaling. For example, set to 95 to use the 95th
percentile (p95) for autoscaling. Valid values are between 0 and 100.'
TriggerGitDeploymentMetadata.Provider:
type: string
enum:
- UNKNOWN
- GITHUB
default: UNKNOWN
SecurityPolicies:
type: object
properties:
basic_auths:
type: array
items:
$ref: '#/components/schemas/BasicAuthPolicy'
api_keys:
type: array
items:
type: string
CancelDeploymentReply:
type: object
DeploymentVolume:
type: object
properties:
id:
type: string
title: the id of the volume
path:
type: string
title: the path where the volume is mounted to
replica_index:
type: integer
format: int64
title: optionally, explicitly choose the replica index to mount the volume to
scopes:
type: array
items:
type: string
title: scope of the associated
DeploymentScalingTargetAverageMem:
type: object
properties:
value:
type: integer
format: int64
DeploymentProvisioningInfo:
type: object
properties:
sha:
type: string
description: The git sha for this build (we resolve the reference at the start of the build).
image:
type: string
description: The docker image built as a result of this build.
stages:
type: array
items:
$ref: '#/components/schemas/DeploymentProvisioningInfo.Stage'
description: Some info about the build.
DeploymentScalingTargetAverageCPU:
type: object
properties:
value:
type: integer
format: int64
google.protobuf.Any:
type: object
properties:
'@type':
type: string
description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
additionalProperties: {}
description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": <string>,\n \"lastName\": <string>\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }"
DeploymentMetadata:
type: object
properties:
trigger:
$ref: '#/components/schemas/TriggerDeploymentMetadata'
database:
$ref: '#/components/schemas/DatabaseDeploymentMetadata'
git:
$ref: '#/components/schemas/GitDeploymentMetadata'
archive:
$ref: '#/components/schemas/ArchiveDeploymentMetadata'
proxy_ports:
type: array
items:
$ref: '#/components/schemas/DeploymentProxyPortMetadata'
sandbox:
$ref: '#/components/schemas/SandboxMetadata'
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
TriggerDeploymentMetadata.ActorType:
type: string
enum:
- UNKNOWN_ACTOR
- USER
- SYSTEM
default: UNKNOWN_ACTOR
DeploymentScalingTarget:
type: object
properties:
average_cpu:
$ref: '#/components/schemas/DeploymentScalingTargetAverageCPU'
average_mem:
$ref: '#/components/schemas/DeploymentScalingTargetAverageMem'
requests_per_second:
$ref: '#/components/schemas/DeploymentScalingTargetRequestsPerSecond'
concurrent_requests:
$ref: '#/components/schemas/DeploymentScalingTargetConcurrentRequests'
requests_response_time:
$ref: '#/components/schemas/DeploymentScalingTargetRequestsResponseTime'
sleep_idle_delay:
$ref: '#/components/schemas/DeploymentScalingTargetSleepIdleDelay'
ArchiveDeploymentMetadata:
type: object
properties:
last_provisioned_deployment_id:
type: string
NeonPostgresDatabaseDeploymentMetadata:
type: object
properties:
reset_role_passwords:
type: array
items:
type: string
DeploymentProxyPort:
type: object
properties:
port:
type: integer
format: int64
protocol:
$ref: '#/components/schemas/ProxyPortProtocol'
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."
DeploymentScalingTargetRequestsPerSecond:
type: object
properties:
value:
type: integer
format: int64
SandboxMetadata:
type: object
properties:
public_url:
type: string
routing_key:
type: string
DeploymentStrategy:
type: object
properties:
type:
$ref: '#/components/schemas/DeploymentStrategyType'
title: Strategy type
DeploymentProvisioningInfo.Stage.BuildAttempt:
type: object
properties:
id:
type: integer
format: int64
status:
$ref: '#/components/schemas/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: '#/components/schemas/DeploymentProvisioningInfo.Stage.BuildAttempt.BuildStep'
image_pushed:
type: boolean
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/koyeb/refs/heads/main/openapi/koyeb-deployments-api-openapi.yml