Koyeb

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…

Developer tools#openapi

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: Bearer

All 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.
  • 50x Server 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

How to test the Koyeb REST API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Koyeb REST API collection, without the publisher's secrets.
  3. 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.
  4. 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.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.