Docs/ API Reference/ Quick Start

API Quick Start

Make your first API call to sh0 in under five minutes. This guide covers authentication, listing resources, creating an app, and understanding response formats.

Note

The sh0 API runs on port 9000 by default. All examples assume your server is accessible at https://your-server:9000. Replace this with your actual server address.

Step 1: Get Your Token

First, authenticate to get a JWT token. Use the default credentials or your own:

Terminal

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "sh0-change-me!"
  }'

Save the token from the response for subsequent requests:

Terminal

export SH0_TOKEN="eyJhbGciOiJIUzI1NiIs..."

Warning

The default password sh0-change-me! should be changed immediately after your first login. Navigate to Settings → Profile to update it.

Step 2: List Your Apps

Make a GET request to list all deployed applications:

Terminal

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Response (200 OK)

{
  "data": [
    {
      "id": "app_abc123",
      "name": "my-web-app",
      "status": "running",
      "domain": "my-web-app.sh0.app",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "pages": 1
}

API response in terminal showing list of apps

Step 3: Create an App

Create a new application by sending a POST request with the app configuration:

Terminal

curl -X POST https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "git_url": "https://github.com/user/hello-world.git",
    "branch": "main"
  }'

Response (201 Created)

{
  "data": {
    "id": "app_def456",
    "name": "hello-world",
    "status": "building",
    "domain": "hello-world.sh0.app",
    "git_url": "https://github.com/user/hello-world.git",
    "branch": "main",
    "created_at": "2026-03-21T14:00:00Z"
  }
}

sh0 will automatically detect the stack (Node.js, Python, Go, etc.), build a Docker image, and deploy the container.

App creation response showing the new app in building status

Tip

You can track the build progress by polling the app status endpoint or connecting to the WebSocket for real-time updates:

Terminal

# Poll app status
curl https://your-server:9000/api/apps/app_def456 \
  -H "Authorization: Bearer $SH0_TOKEN"

# Stream build logs
curl https://your-server:9000/api/apps/app_def456/logs?type=build \
  -H "Authorization: Bearer $SH0_TOKEN"

Response Format

All sh0 API responses follow a consistent format:

Successful responses:

Success Format

{
  "data": { ... }
}

List responses with pagination:

List Format

{
  "data": [ ... ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Error responses:

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "App with id 'app_xyz' not found"
  }
}

Pagination

List endpoints support pagination with two query parameters:

Parameter	Default	Description
`page`	1	Page number (1-indexed)
`per_page`	20	Items per page (max 100)

Terminal

# Get page 2, 50 items per page
curl "https://your-server:9000/api/deployments?page=2&per_page=50" \
  -H "Authorization: Bearer $SH0_TOKEN"

Error Handling

The API uses standard HTTP status codes. Here are the most common ones:

Status	Meaning
200	Success
201	Resource created
400	Bad request (invalid parameters)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Resource not found
409	Conflict (duplicate name, etc.)
422	Validation error
429	Rate limited
500	Internal server error

Tip

Always check the error.code field for programmatic error handling rather than parsing the message string, which may change between versions.

Next Steps

Now that you can authenticate and make basic API calls, explore the full capabilities of the sh0 API:

Full API Reference -- Interactive explorer with all 180+ endpoints
Git Deploy -- Set up push-to-deploy workflows
Scaling -- Scale apps via the API
Monitoring -- Retrieve metrics and health data

sh0 API explorer showing available endpoint categories

API Authentication

Full Reference