# Alpaca Cloud

> Open-source Postgres backend platform. Database, Auth, Storage, Edge Functions, Realtime, Sandboxes, and App Hosting — one platform, one API key.

Base URL: https://api.alpaca-cloud.com
Dashboard: https://app.alpaca-cloud.com
Docs: https://docs.alpaca-cloud.com

---

## Authentication

All API requests require a Bearer token (your Personal Access Token or project service role key).

```
Authorization: Bearer <your_token>
```

Get your token: Dashboard → Account → API Tokens

---

## Projects

Every resource lives inside a **project**. Get your project ID from the dashboard URL or via:

```
GET /projects
```

Response: `[{ id, name, status, backend_type, server_url, db_host, ... }]`

---

## REST API — Project Resources

### Database / SQL

```
POST /projects/:id/query
Body: { "sql": "SELECT * FROM users LIMIT 10" }
Response: { "rows": [...], "rowCount": N }
```

### Tables

```
GET    /projects/:id/tables                     — list all tables
POST   /projects/:id/tables                     — create table
DELETE /projects/:id/tables/:table              — drop table
GET    /projects/:id/tables/:table/columns      — list columns
POST   /projects/:id/tables/:table/columns      — add column
DELETE /projects/:id/tables/:table/columns/:col — drop column
GET    /projects/:id/tables/:table/rows         — query rows (with filter/sort/limit)
POST   /projects/:id/tables/:table/rows         — insert row
PATCH  /projects/:id/tables/:table/rows/:id     — update row
DELETE /projects/:id/tables/:table/rows/:id     — delete row
```

### Auth Users

```
GET    /projects/:id/auth/users          — list all users
POST   /projects/:id/auth/users          — create user { email, password }
DELETE /projects/:id/auth/users/:uid     — delete user
GET    /projects/:id/auth/providers      — get OAuth providers config
PATCH  /projects/:id/auth/providers      — update OAuth providers
```

### Storage

```
GET    /projects/:id/storage/buckets                      — list buckets
POST   /projects/:id/storage/buckets                      — create bucket { name, public }
DELETE /projects/:id/storage/buckets/:bucket              — delete bucket
GET    /projects/:id/storage/buckets/:bucket/objects      — list files
POST   /projects/:id/storage/buckets/:bucket/upload       — upload file (multipart)
DELETE /projects/:id/storage/buckets/:bucket/objects/:path — delete file
```

### Edge Functions

```
GET    /projects/:id/functions           — list functions
POST   /projects/:id/functions           — create function { name, code }
PATCH  /projects/:id/functions/:fid      — update function
POST   /projects/:id/functions/:fid/deploy — deploy function
POST   /projects/:id/functions/:fid/invoke — invoke function
DELETE /projects/:id/functions/:fid      — delete function
```

### Sandboxes (Code Execution)

Spin up isolated Docker containers (Node.js, Python, Shell) and execute code programmatically.

```
POST   /sandboxes                        — create sandbox { runtime: "node"|"python"|"shell" }
GET    /sandboxes                        — list your sandboxes
GET    /sandboxes/:id                    — get sandbox status
POST   /sandboxes/:id/exec              — run code/command
GET    /sandboxes/:id/files/*path       — read a file from sandbox
PUT    /sandboxes/:id/files/*path       — write a file to sandbox
DELETE /sandboxes/:id                    — destroy sandbox
```

**Create a sandbox:**
```json
POST /sandboxes
{ "runtime": "python", "label": "My Python Sandbox" }

Response:
{
  "id": "sbx_abc123xyz",
  "runtime": "python",
  "status": "creating",
  "note": "Poll GET /sandboxes/:id until status=running before exec"
}
```

**Execute code:**
```json
POST /sandboxes/sbx_abc123xyz/exec
{ "code": "print('hello world')", "language": "python" }

Response:
{ "stdout": "hello world
", "stderr": "", "exit_code": 0, "duration_ms": 42 }
```

**Execute a shell command:**
```json
POST /sandboxes/sbx_abc123xyz/exec
{ "command": "pip install requests && python3 -c "import requests; print(requests.__version__)"" }
```

**Write a file then run it:**
```json
PUT /sandboxes/sbx_abc123xyz/files/app/script.py
{ "content": "import json
data = {'result': 42}
print(json.dumps(data))" }

POST /sandboxes/sbx_abc123xyz/exec
{ "command": "python3 /app/script.py" }
```

Sandbox limits: 512MB RAM · 0.5 vCPU · outbound network enabled (pip/npm install works) · 30-min TTL · max 5 concurrent per user

### App Hosting (Deployments)

```
POST   /projects/:id/compute/deploy              — trigger deploy { repo_url, branch }
GET    /projects/:id/compute                     — status + last 10 deployments
GET    /projects/:id/compute/deployments/:depId  — get specific deployment status
GET    /projects/:id/compute/logs               — build/runtime logs
POST   /projects/:id/compute/stop               — stop container
```

**Poll deploy until done:**
```
POST /projects/:id/compute/deploy → { deploy_id: "abc" }
GET  /projects/:id/compute/deployments/abc
  → { status: "building" | "running" | "failed", in_progress: true|false, build_log: "..." }
```

### Project Management

```
GET   /projects/:id          — get project (returns flat object)
PATCH /projects/:id          — update project settings
                               Returns flat object + webhook_registered, webhook_url
  Updatable: repo_url, build_command, output_dir, install_command,
             production_branch, env_vars, email_notifications,
             slack_webhook, forms_enabled, webhook_secret,
             github_token, google_client_id, google_client_secret
```

**install_command vs build_command:**
- `install_command` runs FIRST (e.g. `npm install`) to install dependencies
- `build_command` runs AFTER (e.g. `npm run build`) to produce output
- Both are optional — omit if your Dockerfile handles everything

### API Keys

```
POST /projects/:id/api-keys/rotate    — rotate anon + service_role keys
```

### Webhooks (GitHub)

When you set `repo_url` + `github_token` via PATCH, a GitHub push webhook is auto-registered.
The response includes `webhook_secret` — use it to verify `X-Hub-Signature-256` headers.
View/copy your webhook secret in the dashboard under Settings → Continuous Deployment.

### Logs

```
GET /projects/:id/logs?source=api&minutes=60&search=error
```

---

## PostgREST Auto-REST API (per project)

Your project URL exposes a full REST API auto-generated from your database schema.
No code needed — every table becomes an endpoint.

Base: `https://your-project.alpaca-cloud.com/rest/v1/`

```
GET    /rest/v1/users                   — select all
GET    /rest/v1/users?id=eq.42          — filter by id
GET    /rest/v1/users?select=id,email   — select columns
GET    /rest/v1/posts?order=created_at.desc&limit=10
POST   /rest/v1/users                   — insert
PATCH  /rest/v1/users?id=eq.42          — update
DELETE /rest/v1/users?id=eq.42          — delete
POST   /rest/v1/rpc/my_function         — call a Postgres function
```

Headers required:
```
apikey: <your-anon-key>
Authorization: Bearer <jwt-token>
Content-Type: application/json
```

---

## Auth API (per project)

Base: `https://your-project.alpaca-cloud.com/auth/v1/`

```
POST /auth/v1/signup              — { email, password }
POST /auth/v1/token?grant_type=password — sign in
POST /auth/v1/logout              — sign out
GET  /auth/v1/user                — get current user (requires JWT)
POST /auth/v1/recover             — password reset email
POST /auth/v1/admin/users         — create user (service role only)
GET  /auth/v1/admin/users         — list users (service role only)
DELETE /auth/v1/admin/users/:uid  — delete user (service role only)
```

---

## Storage API (per project)

Base: `https://your-project.alpaca-cloud.com/storage/v1/`

```
GET    /storage/v1/bucket                      — list buckets
POST   /storage/v1/bucket                      — create bucket { name, public }
POST   /storage/v1/object/list/:bucket         — list objects { prefix, limit, offset }
POST   /storage/v1/object/:bucket/path/to/file — upload file
GET    /storage/v1/object/public/:bucket/:path — download public file
POST   /storage/v1/object/sign/:bucket/:path   — create signed URL
DELETE /storage/v1/object/:bucket/:path        — delete file
```

---

## MCP Server (for AI agents)

Connect Claude Desktop, Cursor, Windsurf, or any MCP-compatible tool directly to your project:

```json
{
  "mcpServers": {
    "alpaca-cloud": {
      "command": "npx",
      "args": [
        "@alpacacloud/mcp",
        "--url=https://your-project.alpaca-cloud.com",
        "--key=your-service-role-key"
      ]
    }
  }
}
```

MCP tools: `run_sql`, `list_tables`, `get_table`, `query_table`, `insert_row`, `update_rows`,
           `delete_rows`, `list_auth_users`, `get_project_info`, `list_storage_buckets`, `list_storage_objects`

---

## JavaScript SDK

```bash
npm install @alpacacloud/js
```

```js
import { createClient } from '@alpacacloud/js'

const alp = createClient('https://your-project.alpaca-cloud.com', 'your-anon-key')

// Database
const { data } = await alp.from('posts').select('*').eq('published', true).limit(10)

// Auth
const { user } = await alp.auth.signUp({ email: 'user@example.com', password: 'secret' })
const { session } = await alp.auth.signIn({ email: 'user@example.com', password: 'secret' })

// Storage
await alp.storage.from('avatars').upload('user123.jpg', fileBlob)
const { publicUrl } = alp.storage.from('avatars').getPublicUrl('user123.jpg')
```

---

## Error Format

All errors return:
```json
{ "error": "Human-readable message", "detail": "optional extra info" }
```

Common status codes:
- `400` — bad request / missing fields
- `401` — missing or invalid token
- `403` — forbidden (wrong project / insufficient role)
- `404` — resource not found
- `409` — conflict (e.g. sandbox not running)
- `429` — rate limit / quota exceeded
- `500` — internal error

---

## Rate Limits

- SQL queries: 1000/min per project
- Sandbox exec: 60/min per sandbox
- File uploads: 100/min per project
- API requests: 5000/min per token

---

## Links

- Website: https://alpaca-cloud.com
- Dashboard: https://app.alpaca-cloud.com
- GitHub: https://github.com/Melgencer/alpacabase
- Status: https://status.alpaca-cloud.com
- Support: support@alpaca-cloud.com