API Introduction

The Vers API provides programmatic access to VM management, commits, repositories, domains, environment variables, and tagging. While most users interact with Vers through the CLI or SDKs, the API enables direct integration.

Base URL

https://api.vers.sh/api/v1

Authentication

All API endpoints require a Bearer token:

curl -H "Authorization: Bearer $VERS_API_KEY" \
  https://api.vers.sh/api/v1/vms

Get your API key from vers.sh/billing.

Endpoints

63 operations across VMs, commits, repositories, domains, environment variables, and tags:

Method	Endpoint	Description
`GET`	`/api/v1/commit_tags`
`POST`	`/api/v1/commit_tags`
`GET`	`/api/v1/commit_tags/{tag_name}`
`DELETE`	`/api/v1/commit_tags/{tag_name}`
`PATCH`	`/api/v1/commit_tags/{tag_name}`
`GET`	`/api/v1/commits`
`GET`	`/api/v1/commits/public`
`DELETE`	`/api/v1/commits/{commit_id}`
`PATCH`	`/api/v1/commits/{commit_id}`
`POST`	`/api/v1/deploy`	Deploy a GitHub repository to a new Vers project.
`GET`	`/api/v1/domains`
`POST`	`/api/v1/domains`
`GET`	`/api/v1/domains/{domain_id}`
`DELETE`	`/api/v1/domains/{domain_id}`
`GET`	`/api/v1/env_vars`
`PUT`	`/api/v1/env_vars`
`DELETE`	`/api/v1/env_vars/{key}`
`GET`	`/api/v1/images`
`POST`	`/api/v1/images/create`
`DELETE`	`/api/v1/images/images/{base_image_id}`
`POST`	`/api/v1/images/upload`
`GET`	`/api/v1/images/{image_name}/status`
`POST`	`/api/v1/keys/validate`
`GET`	`/api/v1/public/repositories`
`GET`	`/api/v1/public/repositories/{org_name}/{repo_name}`
`GET`	`/api/v1/public/repositories/{org_name}/{repo_name}/tags`
`GET`	`/api/v1/public/repositories/{org_name}/{repo_name}/tags/{tag_name}`
`GET`	`/api/v1/repositories`
`POST`	`/api/v1/repositories`
`POST`	`/api/v1/repositories/fork`
`GET`	`/api/v1/repositories/{repo_name}`
`DELETE`	`/api/v1/repositories/{repo_name}`
`GET`	`/api/v1/repositories/{repo_name}/tags`
`POST`	`/api/v1/repositories/{repo_name}/tags`
`GET`	`/api/v1/repositories/{repo_name}/tags/{tag_name}`
`DELETE`	`/api/v1/repositories/{repo_name}/tags/{tag_name}`
`PATCH`	`/api/v1/repositories/{repo_name}/tags/{tag_name}`
`PATCH`	`/api/v1/repositories/{repo_name}/visibility`
`GET`	`/api/v1/system/version`
`GET`	`/api/v1/vm`
`POST`	`/api/v1/vm/branch/by_commit/{commit_id}`
`POST`	`/api/v1/vm/branch/by_ref/{repo_name}/{tag_name}`
`POST`	`/api/v1/vm/branch/by_tag/{tag_name}`
`POST`	`/api/v1/vm/branch/by_vm/{vm_id}`
`GET`	`/api/v1/vm/commits/{commit_id}/parents`
`POST`	`/api/v1/vm/from_commit`
`POST`	`/api/v1/vm/new_root`
`DELETE`	`/api/v1/vm/{vm_id}`
`POST`	`/api/v1/vm/{vm_id}/commit`
`PATCH`	`/api/v1/vm/{vm_id}/disk`
`POST`	`/api/v1/vm/{vm_id}/exec`
`POST`	`/api/v1/vm/{vm_id}/exec/stream`
`POST`	`/api/v1/vm/{vm_id}/exec/stream/attach`
`GET`	`/api/v1/vm/{vm_id}/files`
`PUT`	`/api/v1/vm/{vm_id}/files`
`PATCH`	`/api/v1/vm/{vm_id}/label`
`GET`	`/api/v1/vm/{vm_id}/logs`
`GET`	`/api/v1/vm/{vm_id}/metadata`
`GET`	`/api/v1/vm/{vm_id}/ssh_key`
`PATCH`	`/api/v1/vm/{vm_id}/state`
`GET`	`/api/v1/vm/{vm_id}/status`
`POST`	`/api/v1/vm/{vm_or_commit_id}/branch`
`GET`	`/api/v1/vms`

Models

66 types defined in the schema: BaseImageInfo, BaseImageStatusResponse, CommitInfo, CreateBaseImageRequest, CreateBaseImageResponse, CreateDomainRequest, CreateRepoTagRequest, CreateRepoTagResponse, CreateRepositoryRequest, CreateRepositoryResponse, CreateTagRequest, CreateTagResponse, DeleteBaseImageResponse, DeleteDomainResponse, DeployRequest, DeployResponse, DeploySettings, DomainResponse, EnvVarsResponse, ErrorResponse, ForkRepositoryRequest, ForkRepositoryResponse, FromCommitVmRequest, ImageSourceRequest, LabelVmRequest, ListBaseImagesResponse, ListCommitsResponse, ListPublicRepositoriesResponse, ListRepoTagsResponse, ListRepositoriesResponse, ListTagsResponse, NewRootRequest, NewVmResponse, NewVmsResponse, OrchestratorVersion, PublicRepositoryInfo, RepoTagInfo, RepositoryInfo, SetEnvVarsRequest, SetRepositoryVisibilityRequest, TagInfo, UpdateCommitRequest, UpdateRepoTagRequest, UpdateTagRequest, UploadBaseImageResponse, VM, ValidateKeyResponse, VmCommitEntity, VmCommitRequest, VmCommitResponse, VmCreateVmConfig, VmDeleteResponse, VmExecLogEntry, VmExecLogResponse, VmExecLogStream, VmExecRequest, VmExecResponse, VmExecStreamAttachRequest, VmMetadataResponse, VmReadFileResponse, VmResizeDiskRequest, VmSshKeyResponse, VmState, VmUpdateStateEnum, VmUpdateStateRequest, VmWriteFileRequest See the interactive API playground below for full request/response schemas.

Quick Examples

Create a VM

curl -X POST https://api.vers.sh/api/v1/vm/new_root?wait_boot=true \
  -H "Authorization: Bearer $VERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vm_config": {"mem_size_mib": 512, "vcpu_count": 1, "fs_size_mib": 512}}'

List VMs

curl https://api.vers.sh/api/v1/vms \
  -H "Authorization: Bearer $VERS_API_KEY"

Get SSH Credentials

curl https://api.vers.sh/api/v1/vm/{vm_id}/ssh_key \
  -H "Authorization: Bearer $VERS_API_KEY"

Branch a VM

curl -X POST https://api.vers.sh/api/v1/vm/{vm_id}/branch \
  -H "Authorization: Bearer $VERS_API_KEY"

SDKs

Official SDKs are available for 9 languages — see the SDKs page for install instructions and quickstart code.

Overview

Endpoints

Shell Auth

API Introduction

API Introduction

Base URL

Authentication

Endpoints

Models

Quick Examples

Create a VM

List VMs

Get SSH Credentials

Branch a VM

SDKs

See Also

​API Introduction

​Base URL

​Authentication

​Endpoints

​Models

​Quick Examples

​Create a VM

​List VMs

​Get SSH Credentials

​Branch a VM

​SDKs

​See Also

API Introduction

Base URL

Authentication

Endpoints

Models

Quick Examples

Create a VM

List VMs

Get SSH Credentials

Branch a VM

SDKs

See Also