REST API Reference
The Sprites REST API allows you to manage Sprites programmatically via HTTP requests.
Base URL
Section titled “Base URL”https://api.sprites.devAuthentication
Section titled “Authentication”All API requests require authentication via Bearer token:
curl -H "Authorization: Bearer $SPRITE_TOKEN" \ https://api.sprites.dev/v1/spritesGetting a Token
Section titled “Getting a Token”Create a token at sprites.dev/account, or generate one via the CLI or SDK:
# Via CLI (stores in config)sprite org auth
# View token (after disabling keyring)sprite org keyring disablecat ~/.sprites/sprites.json | grep api_tokenOr programmatically:
const token = await SpritesClient.createToken(flyMacaroon, orgSlug);Endpoints
Section titled “Endpoints”Sprites
Section titled “Sprites”Create a new Sprite.
{ "name": "my-sprite", "url_settings": { "auth": "sprite" }}{ "id": "sprite-abc123", "name": "my-sprite", "status": "cold", "organization": "personal", "url": "https://my-sprite-abc123.sprites.app", "url_settings": { "auth": "sprite" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z"}url_settings.auth accepts sprite (default) or public.
List all Sprites for the authenticated organization.
prefix string Filter by name prefix
max_results integer
default: 50 Maximum results (max: 50)
continuation_token string Pagination token
{ "sprites": [ { "id": "sprite-abc123", "name": "my-sprite", "status": "running", "organization": "personal", "url": "https://my-sprite-abc123.sprites.app", "url_settings": { "auth": "sprite" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "has_more": false, "next_continuation_token": null}Get details for a specific Sprite.
{ "id": "sprite-abc123", "name": "my-sprite", "status": "running", "organization": "personal", "url": "https://my-sprite-abc123.sprites.app", "url_settings": { "auth": "sprite" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z"}Update Sprite settings. Only url_settings is supported.
{ "url_settings": { "auth": "public" }}{ "id": "sprite-abc123", "name": "my-sprite", "status": "running", "organization": "personal", "url": "https://my-sprite-abc123.sprites.app", "url_settings": { "auth": "public" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T11:00:00Z"}Delete a Sprite and all associated resources.
Returns 204 No Content on success.
Check if a Sprite is healthy and responding.
{ "sprite_name": "my-sprite", "sprite_id": "sprite-abc123", "status": "healthy", "reason": null, "checked_at": "2024-01-15T10:35:00Z", "elapsed": 150} healthy string Sprite is running and responsive
hibernated string Sprite is hibernated
unhealthy string Sprite is not responding
error string Error checking sprite
Upgrade a Sprite to the latest configuration.
{ "version": "0.0.1-rc27"}{ "name": "my-sprite", "status": "upgraded"}Organizations
Section titled “Organizations”Get info for the organization that owns the authenticated token.
{ "organization": { "slug": "personal", "sprites_enabled": true, "active_sprites": ["my-sprite", "dev-server"], "max_sprites": 100, "active_sprite_limit": 10 }}HTTP Proxy
Section titled “HTTP Proxy”Requests to /v1/sprites/:name/* are proxied to the Sprite’s environment.
The request is forwarded to the Sprite, and the response is returned.
If your sprite is running a web server on port 8080:
curl -H "Authorization: Bearer $SPRITE_TOKEN" \ https://api.sprites.dev/v1/sprites/my-sprite/api/usersError Responses
Section titled “Error Responses”Errors return appropriate HTTP status codes with JSON bodies:
{ "error": "sprite not found"}Validation errors return a list:
{ "errors": ["invalid wait_for_capacity parameter"]}Status Codes
Section titled “Status Codes”Pagination
Section titled “Pagination”List endpoints support pagination:
# First pagecurl -H "Authorization: Bearer $SPRITE_TOKEN" \ "https://api.sprites.dev/v1/sprites?max_results=10"
# Response includes continuation token# {# "sprites": [...],# "has_more": true,# "next_continuation_token": "abc123"# }
# Next pagecurl -H "Authorization: Bearer $SPRITE_TOKEN" \ "https://api.sprites.dev/v1/sprites?max_results=10&continuation_token=abc123"Examples
Section titled “Examples”Create and Configure a Sprite
Section titled “Create and Configure a Sprite”# Create spritecurl -X POST \ -H "Authorization: Bearer $SPRITE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "api-test" }' \ https://api.sprites.dev/v1/sprites
# Make URL publiccurl -X PUT \ -H "Authorization: Bearer $SPRITE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"url_settings": {"auth": "public"}}' \ https://api.sprites.dev/v1/sprites/api-test
# Check healthcurl -H "Authorization: Bearer $SPRITE_TOKEN" \ https://api.sprites.dev/v1/sprites/api-test/checkList All Sprites with Pagination
Section titled “List All Sprites with Pagination”#!/bin/bash
TOKEN="$SPRITE_TOKEN"BASE_URL="https://api.sprites.dev/v1/sprites"CONTINUATION=""
while true; do if [ -z "$CONTINUATION" ]; then RESPONSE=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL?max_results=50") else RESPONSE=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL?max_results=50&continuation_token=$CONTINUATION") fi
echo "$RESPONSE" | jq '.sprites[].name'
HAS_MORE=$(echo "$RESPONSE" | jq -r '.has_more') if [ "$HAS_MORE" != "true" ]; then break fi
CONTINUATION=$(echo "$RESPONSE" | jq -r '.next_continuation_token')doneRelated Documentation
Section titled “Related Documentation”- JavaScript SDK - Programmatic access
- Go SDK - Native Go client
- CLI Reference - Command-line interface