Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vers.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
MethodEndpointDescription
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/deployDeploy 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.

​
See Also

  • SDKs — Install and quickstart for TypeScript, Python, Go, Rust, Ruby, C#, Java, Kotlin, PHP
  • VM Access Guide — SSH connections and SDK usage
  • CLI Reference — Command-line interface