HTTP API

Use the HTTP API to manage Simplifyd Cloud resources from your application. For example, your backend can upload a video to a library when a customer submits a file.

For terminal use and deployment scripts, see the CLI reference. Go applications can use the Go SDK.

Base URL

https://api.cloud.simplifyd.com

Every path below is versioned under /v1.

Authentication

Requests carry a project API token as a bearer token:

Authorization: Bearer sk_proj_01j2k3...

Create one with edge token create — see Tokens. A token is scoped to a project, and optionally to a single environment.

Work that belongs to the workspace rather than to one project, such as buying domains or managing their DNS records, takes a workspace token instead:

Authorization: Bearer sk_ws_01j2k3...

A workspace owner creates one in the console, under Settings → Tokens → Workspace Tokens. It works only in the workspace it was made for, only on the routes its scopes allow, and with no more authority than the owner who created it. See Workspace tokens.

Calling the API from your services

Services you run on Simplifyd Cloud can call the API at the same address, https://api.cloud.simplifyd.com, so your own backend can drive the platform: a worker that downloads a video's original for processing, or a job that uploads videos into a library.

Give the service a token through a variable rather than writing it into your code:

1. Create a token scoped to the service's environment: edge token create "video worker" --env production.
2. Add it to the service as a variable, for example SIMPLIFYD_API_TOKEN.
3. Send it as the bearer token, exactly as above.

The token can do anything you can within its scope — deploy, change variables, delete services — so only give it to services you trust with that.

How resources are addressed

Service paths include the workspace, project, environment, and service IDs:

/v1/workspaces/{workspace}/projects/{project}/envs/{env}/svcs/{service}

Each of the four is an id, not a display name. The quickest way to find them is your browser: open the service in the console and the URL contains all four, in that order. From code, GET /v1/workspaces lists your workspaces and each level lists the one below it. At a terminal, edge status prints the ids for your current context.

Ids are stable. Renaming a workspace, project or service does not change them, so it is safe to keep them in configuration.

Responses

Successful responses are JSON, and the status says what happened: 200 for a read or an edit, 201 when something was created, 202 when the platform accepted work that is still running, 204 when there is nothing to return.

Failures are JSON too:

{
  "type": "VALIDATION_ERROR",
  "message": "\".avi\" is not a video container we can read; upload an .mp4, .mov, .mkv, .webm or .m4v file",
  "request_id": "01j2k3m4n5p6q7r8s9t0"
}

message describes the error and can be displayed or logged. Include request_id when contacting support about a failed request.

Reference