Koyeb REST API
Welcome to the Koyeb API documentation. The Koyeb API allows you to interact with the Koyeb platform in a simple, programmatic way using conventional HTTP…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Welcome to the Koyeb API documentation.
The Koyeb API allows you to interact with the Koyeb platform in a simple, programmatic way using conventional HTTP requests.
The API has predictable resource-oriented URLs, allowing you to request, retrieve and execute actions on resources efficiently.
The API returns JSON-encoded responses and uses standard HTTP response codes, and verbs.
All of the functionality available in the Koyeb Control Panel is also available via the API, allowing you to automate repetitive and complex actions as required.
All production API requests are made to:
- https://app.koyeb.com/
All data is sent and received as JSON.
Constructing Requests
Requests are made of three components:
- Base URL:
https://app.koyeb.com - API Version:
v1 - Resource path:
apps
To construct a proper request, you need to format the URL as follows:
https://app.koyeb.com/{version}/{resource}
Example: https://app.koyeb.com/v1/apps
The following code is an example request to retrieve the list of Apps.
$ curl -H 'Authorization: Bearer 1111-1111-1111-1111-1111' https://app.koyeb.com/v1/apps
{
"apps": [
{
"id": "e267e09d-a2ef-4672-95c7-bf88d787a274",
"name": "demo",
"organization_id": "c402bcad-d06d-4fd6-8af2-08b790c0e249",
"updated_at": "2021-04-26T08:28:59.221274Z",
"created_at": "2021-04-26T08:28:59.221274Z",
"domains": [
{
"name": "demo-koyeb.koyeb.app",
"deployment_group": "prod"
}
]
},
{
"id": "e38caea5-5acb-4fec-aa65-81749546b470",
"name": "www",
"organization_id": "c402bcad-d06d-4fd6-8af2-08b790c0e249",
"updated_at": "2021-05-04T08:56:40.557792Z",
"created_at": "2021-05-04T08:56:40.557792Z",
"domains": [
{
"name": "www-koyeb.koyeb.app",
"deployment_group": "prod"
}
]
}
],
"limit": 20,
"offset": 0,
"count": 2
}Authentication
The Koyeb API uses API keys to authenticate requests. You can view and manage your API keys in the Koyeb Control Panel.
Your API keys carry many privileges. Take care to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, Slack, client-side code, and so forth.
To make an authenticated request, include a bearer-type Authorization header containing your API key, prefixed with Bearer :
Authorization: BearerAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
We use conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter is missing, resource not found), and codes in the 5xx range indicate an error with our servers.
HTTP Status Code Summary
200 OK- Everything worked as expected.400 Bad Request- Often missing a required parameter.401 Unauthorized- No valid API key provided.402 Request Failed- Parameters were valid, but the request failed.403 Forbidden- Insufficient privileges to access the requested resource.404 Not Found- The requested item doesn't exist.50xServer errors - Something went wrong on the API domain's end.
Input and output data must be valid JSON with the appropriate Content-Type header set.
Attributes
- code:
invalid_argument: Occur when your request has invalid parameters.unknown_resource: Occur when the resource doesn't exist.authentication_error: Arise when there is a problem with authentication.rate_limit_error: Too many requests hit the API too quickly.authorization_required: You don't have sufficient right to access the resource.api_error: API errors use in case of a problem with api domain's servers (extremely uncommon).
- message:
- A human-readable error giving more details about the error
- status:
- The HTTP code returned by the server.
- fields (Optional):
- An array of parameters with a human-readable message giving more details about the error.
Errors responses example
Response 400 (application/json)
{
"status": 400,
"code": "invalid_argument",
"message": "Invalid argument",
"fields": [
{
"field": "definition.docker.image",
"description": "cannot be blank"
}
]
}Response 401 (application/json)
{
"status": 401,
"code": "authentication_error",
"message": "Request unauthenticated with bearer"
}Response 403 (application/json)
{
"status": 403,
"code": "authentication_required",
"message": "You don't have the requested permission to access to resource."
}Response 404 (application/json)
{
"status": 404,
"code": "unknown_resource",
"message": "App not found"
}Pagination
All top-level API resources receive a paginated…
Endpoints 188
activity
- GETGetAccountActivities
/v1/account/activities - GETList Activities
/v1/activities - GETList Notifications
/v1/notifications
Profile
- GETBegin a session with iDenfy, emit an authToken
/v1/account/idenfy - POSTClearIdenfyVerificationResult marks the current result for idenfy as
superseded
/v1/account/idenfy - GETGet the login method for an email address
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/login_method - GETGet OAuth Providers
/v1/account/oauth - POSTAuthenticate using OAuth
/v1/account/oauth - GETGet Current Organization
/v1/account/organization - GETList User Organization Invitations
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/organization_invitations - GETGet User Organization Invitation
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/organization_invitations/:id - POSTAccept Organization Invitation
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/organization_invitations/:id/accept - POSTDecline Organization Invitation
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/organization_invitations/:id/decline - GETList User Organizations
/v1/account/organizationsList all organizations that the current user is a member of. - GETGet Current User
/v1/account/profile - PUTUpdate User
/v1/account/profile - PATCHUpdate User
/v1/account/profile - POSTResend Email Verification
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/resend_validation - POSTReset Password
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/reset_password - GETGetUserSettings
/v1/account/settings - PATCHUpdateUserSettings
/v1/account/settings - POSTSignup
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/signup - POSTUpdate Password
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/update_password - POSTValidate
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/validate/:id - PUTUpdate User V2
/v2/account/profile - PATCHUpdate User V2
/v2/account/profile
invite
- POSTDEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/invite
billing
- GETExperimental: Has unpaid invoices
/v1/billing/has_unpaid_invoicesWARNING: Please don't use the following method. Koyeb doesn't guarantee backwards compatible breaking change and reserve the right to completely drop it… - GETManage
/v1/billing/manage - GETExperimental: Fetch next invoice
/v1/billing/next_invoiceWARNING: Please don't use the following method. Koyeb doesn't guarantee backwards compatible breaking change and reserve the right to completely drop it…
organization
- GETFetch Github Installation configuration
/v1/github/installation - POSTStart Github Installation
/v1/github/installation - POSTCreate Organization
/v1/organizations - GETGet Organization
/v1/organizations/:id - PUTUpdate Organization
/v1/organizations/:id - DELETEDelete an Organization
/v1/organizations/:id - PATCHUpdate Organization
/v1/organizations/:id - POSTCreateAccessToken
/v1/organizations/:id/access_tokenCreateAccessToken creates a short-lived access token in the scope of the specified organization, provided the user making the request is part of said… - POSTDeactivate an Organization
/v1/organizations/:id/deactivate - PUTUpdate Organization's default project
/v1/organizations/:id/default_project - PUTUpdate Organization Name
/v1/organizations/:id/name - POSTUpdate Organization plan
/v1/organizations/:id/plan - POSTReactivate an Organization
/v1/organizations/:id/reactivate - POSTUpsert Organization's signup qualification
/v1/organizations/:id/signup_qualification - POSTSwitch Organization context
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/organizations/:id/switch - GETGet Budget
/v1/organizations/:organization_id/budget - PUTUpdate Budget
/v1/organizations/:organization_id/budget - POSTCreate Budget
/v1/organizations/:organization_id/budget - DELETEDelete Budget
/v1/organizations/:organization_id/budget - POSTUnscope Organization Token
/v1/unscope_organization_tokenUnscopeOrganizationToken removes the organization scope from a token. This endpoint is useful when a user wants to remove an organization: by unscoping the…
sso
- POSTCannyAuth
/v1/sso/canny - POSTDiscourseAuth
/v1/sso/discourse
Coupons
- POSTRedeem Coupon
/v1/couponsThis API allows to redeem a coupon. Pass the code you received in the body. - GETCheck Coupon
/v1/coupons/:codeThis API allows to check if a given coupon is valid. It is heavily rate-limited.
Credentials
- GETList credentials
/v1/credentials - POSTCreate credential
/v1/credentials - GETGet credential
/v1/credentials/:id - PUTUpdate credential
/v1/credentials/:id - DELETEDelete credential
/v1/credentials/:id - PATCHUpdate credential
/v1/credentials/:id
Intercom
- GETGet intercom profile
/v1/intercom/profile
OrganizationConfirmations
- POSTConfirm organization action
/v1/organization_confirmations/:id
OrganizationInvitations
- GETList Organization Invitations
/v1/organization_invitations - POSTCreate Organization Invitation
/v1/organization_invitations - GETGet Organization Invitation
/v1/organization_invitations/:id - DELETEDelete Organization Invitation
/v1/organization_invitations/:id - POSTResend Organization Invitation
/v1/organization_invitations/:id/resend
OrganizationMembers
- GETList organization members
/v1/organization_members - DELETERemove an organization member
/v1/organization_members/:id
PaymentMethods
- GETList payment methods
/v1/payment_methods - POSTCreate payment authorization
/v1/payment_methods - GETGet payment method
/v1/payment_methods/:id - DELETEDelete payment method
/v1/payment_methods/:id - POSTConfirm payment authorization
/v1/payment_methods/:id/confirm
Projects
- GETList projects
/v1/projects - POSTCreate project
/v1/projects - GETGet project
/v1/projects/:id - PUTUpdate project
/v1/projects/:id - DELETEDelete project
/v1/projects/:id - PATCHUpdate project
/v1/projects/:id
OrganizationQuotas
- GETGetQuotas
/v1/organizations/:organization_id/quotas
Sessions
- POSTLogin user
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/login - DELETELogout user
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/logout - PUTRefresh token
DEPRECATED: this has been replaced by WorkOS and will be dropped soon.
/v1/account/refresh - POSTNew session
/v1/account/sessionCreates a new session without an organization for current user. NOTE: If you want a session linked to another organization, please use "Switch organization".…
Subscriptions
- GETGet Subscription
/v1/subscriptions/:id
Summary
- GETGet organization usage summary
/v1/organizations/:organization_id/summary
Users
- DELETEDelete user
/v1/users/:id - DELETEV2 Delete user
/v2/users/:id
Repositories
- GETList Branches
/v1/git/branches - GETList Repositories
/v1/git/repositories - POSTResync Organization
/v1/git/sync/organization/:organization_id
CatalogDatacenters
- GETList datacenters
/v1/catalog/datacenters
CatalogInstances
- GETList Instances
/v1/catalog/instances - GETGet Instance
/v1/catalog/instances/:id
CatalogRegions
- GETList Region
/v1/catalog/regions - GETGet Region
/v1/catalog/regions/:id
CatalogInstanceUsage
- GETListUsage
/v1/catalog/usage
Search
- GETSearch
/v1/search
Apps
- GETList App events
/v1/app_events - GETList App
/v1/apps - POSTCreate App
/v1/apps - GETGet App
/v1/apps/:id - PUTUpdate App
/v1/apps/:id - DELETEDelete App
/v1/apps/:idApp deletion is allowed for all status. - PATCHUpdate App
/v1/apps/:id - POSTPause App
/v1/apps/:id/pauseApp pause action is allowed for the following status: starting healthy degraded unhealthy resuming - POSTResume App
/v1/apps/:id/resumeApp resume action is allowed for the following status: paused
Archives
- POSTCreate Archive
/v1/archivesCreate a signed URL to upload an archive. - GETGet Archive
/v1/archives/:idGet an archive, with a signed URL to download it. - DELETEDelete Archive
/v1/archives/:idMark an archive for deletion. Its status becomes deleting, and it is deleted along with its file shortly after. Deployments already built from it keep…
Compose
- POSTCreate resources from compose.
/v1/compose
Deployments
- GETGet Deployment Scaling
/v1/deployment/:id/scaling - GETList Deployment events
/v1/deployment_events - GETList Deployments
/v1/deployments - GETGet Deployment
/v1/deployments/:id - POSTCancel Deployment
/v1/deployments/:id/cancelDeployment cancellation is allowed for the following status: pending provisioning scheduled
DockerHelper
- GETVerify Docker Image
/v1/docker-helper/verifyVerify if a docker image is reachable
Domains
- GETList Domains
/v1/domains - POSTCreate Domain
/v1/domains - GETGet Domain
/v1/domains/:id - DELETEDelete Domain
/v1/domains/:id - PATCHUpdate Domain
/v1/domains/:id - POSTRefresh Domain Status
/v1/domains/:id/refresh
InstanceSnapshots
- GETListInstanceSnapshotEvents
/v1/instance_snapshot_events - GETListInstanceSnapshots
/v1/instance_snapshots - POSTCreateInstanceSnapshot
/v1/instance_snapshots - GETGetInstanceSnapshot
/v1/instance_snapshots/:id - DELETEDeleteInstanceSnapshot
/v1/instance_snapshots/:id
Instances
- GETList Instance events
/v1/instance_events - GETList Instances
/v1/instances - GETGet Instance
/v1/instances/:id - GETExec Command
/v1/streams/instances/execThis endpoint opens a websocket. Once open, all frames going through the websocket should be formatted in JSON. Input frames should match the format specified…
PersistentVolumes
- GETList Persistent Volume events
/v1/volume_events - GETList all PersistentVolumes
/v1/volumes - POSTCreate a PersistentVolume
/v1/volumes - GETGet a PersistentVolume
/v1/volumes/:id - POSTUpdate a PersistentVolume
/v1/volumes/:id - DELETEDelete a PersistentVolume
/v1/volumes/:id
PoolClaims
- POSTClaim a sandbox from a service pool
/v1/claim - GETGet a claim
/v1/claims/:claim_id - GETList claims of a service pool
/v1/service_pools/:pool_id/claims
Provisioning
- POSTCreate an attempt for a stage
/v1/provisioning/:deployment_id/status/:stage/:attempt - PATCHDeclare stage progress
/v1/provisioning/:deployment_id/status/:stage/:attempt - PATCHDeclare step progress
/v1/provisioning/:deployment_id/status/:stage/:attempt/:step
Quotas
- POSTDEPRECATED: Review Organization Capacity
/v1/quotas/capacity - GETReturn the organization's current quota usage alongside the plan's limits.
Response is cached in Redis for 60s. Accept text/plain (or ?format=prometheus)
to receive the response rendered as Prometheus text exposition format
("koyeb_quota_<x>" for usage, "koyeb_quota_<x>_limit" for the plan limit)
suitable for scraping into an external Prometheus.
/v1/quotas/organizations/:organization_id/usage
RegionalDeployments
- GETList Regional Deployment events
/v1/regional_deployment_events - GETList Regional Deployments
/v1/regional_deploymentsExperimental: use at your own risk - GETGet Regional Deployment
/v1/regional_deployments/:idExperimental: use at your own risk
Secrets
- GETList Secrets
/v1/secrets - POSTCreate Secret
/v1/secrets - GETGet Secret
/v1/secrets/:id - PUTUpdate Secret
/v1/secrets/:id - DELETEDelete Secret
/v1/secrets/:id - PATCHUpdate Secret
/v1/secrets/:id - POSTReveal Secret
/v1/secrets/:id/reveal
ServicePools
- GETList ServicePools
/v1/service_pools - POSTCreate a ServicePool
/v1/service_pools - GETGet a ServicePool
/v1/service_pools/:id - PUTUpdateServicePool
/v1/service_pools/:id - DELETEDelete a ServicePool
/v1/service_pools/:id
Services
- GETList Service events
/v1/service_events - GETList Services
/v1/services - POSTCreate Service
/v1/services - POSTAutocomplete definition
/v1/services-autocompleteGenerate autocomplete definition for a service - GETGet Service
/v1/services/:id - PUTUpdate Service
/v1/services/:id - DELETEDelete Service
/v1/services/:idService deletion is allowed for all status. - PATCHUpdate Service
/v1/services/:id - POSTPause Service
/v1/services/:id/pauseService pause action is allowed for the following status: starting healthy degraded unhealthy resuming - POSTReDeploy Service
/v1/services/:id/redeploy - POSTResume Service
/v1/services/:id/resumeService resume action is allowed for the following status: paused - GETGet Service Scaling
/v1/services/:id/scaleReturns the current scaling configuration for a service - PUTUpdate Service Scaling
/v1/services/:id/scaleStores or updates the scaling configuration for a service to use manual scaling - DELETEDelete Service Scaling
/v1/services/:id/scaleDeletes the manual scaling configuration for a service, reverting to the scaling defined in the deployment definition.
Snapshots
- GETList all Snapshots
/v1/snapshots - POSTCreate a Snapshot
/v1/snapshots - GETGet a Snapshot
/v1/snapshots/:id - POSTUpdate a Snapshot
/v1/snapshots/:id - DELETEDelete a Snapshot
/v1/snapshots/:id
Usages
- GETGet organization usage
/v1/usages - GETGet organization usage details
/v1/usages/details
Test
- GETTest anonymous call
/v1/test/anon - POSTTest authenticated call
/v1/test/auth
Logs
- GETQuery logs
/v1/streams/logs/query - GETTails logs
/v1/streams/logs/tail
Metrics
- GETGet Metrics
/v1/streams/metrics
API details
- Base URL
https://app.koyeb.com- Authentication
- An API key in the Authorization header
- Operations
- 188 operations on 133 pathsGET 84POST 58DELETE 20PUT 14PATCH 12
- Main resources
- Profile 23organization 20Services 14Apps 9Secrets 7Credentials 6Domains 6PersistentVolumes 6Projects 6Deployments 5
- Description format
- Swagger 2.0, API version
1.0.0 - Links
- OpenAPI document
- Listed from
- Koyeb's published OpenAPI description (koyeb/koyeb-api-client-go) (Apache-2.0)
How to test the Koyeb REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Koyeb REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “GetAccountActivities” (GET /v1/account/activities), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Koyeb REST API?
Welcome to the Koyeb API documentation. The Koyeb API allows you to interact with the Koyeb platform in a simple, programmatic way using conventional HTTP… It is listed under Developer tools and has 188 endpoints.
Who publishes the Koyeb REST API?
It is listed from Koyeb's public API description (an OpenAPI document), not published by Koyeb on Swastik Codes. Anyone who controls koyeb.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Koyeb REST API?
Requests go to https://app.koyeb.com. Endpoint paths are added to this base URL.
How do I authenticate with the Koyeb REST API?
With an API key in the Authorization header.
How many endpoints does the Koyeb REST API have?
188 operations on 133 paths (84 GET, 58 POST, 20 DELETE, 14 PUT, 12 PATCH). The largest groups are Profile, organization, Services, Apps.
Is forking the Koyeb REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.