ShipStack API Documentation

One REST API for authentication, database, and file storage — powered by Supabase, Firebase, Appwrite, PocketBase, or Upstash.

Base URL:https://shipstack.codes/api

Quick Start

Get your first API call working in under 5 minutes.

1Create an account

2Get your API token

bash

curl -X POST https://shipstack.codes/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "password": "securepass123",
    "password_confirmation": "securepass123"
  }'

Response:

json

{
  "data": {
    "user": { "id": 1, "name": "Jane Doe", "email": "jane@example.com" },
    "token": "1|abc123..."
  }
}

3Connect a provider

Go to Dashboard → Connect Provider and paste your provider credentials. ShipStack will verify the connection automatically.

Or create a tenant via API:

bash

curl -X POST https://shipstack.codes/api/tenants \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "auth_provider": "supabase",
    "db_provider": "supabase",
    "storage_provider": "supabase",
    "provider_credentials": {
      "supabase": {
        "url": "https://xyzcompany.supabase.co",
        "api_key": "your-supabase-api-key"
      }
    }
  }'

4Make API calls

Every request needs two headers:

Authorization: Bearer YOUR_TOKEN
X-Tenant-Token: YOUR_TENANT_TOKEN

bash

curl https://shipstack.codes/api/db/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Authentication

Manage end-users in your connected provider. These endpoints proxy to Supabase Auth, Firebase Auth, Appwrite Auth, or PocketBase Auth depending on your tenant configuration.

Register a user

bash

curl -X POST https://shipstack.codes/api/auth/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Log in a user

bash

curl -X POST https://shipstack.codes/api/auth/login \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Returns an access token from your provider. Store this on the client for subsequent requests.

Get current user

bash

curl https://shipstack.codes/api/auth/user \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "X-User-Token: USER_ACCESS_TOKEN"

Log out

bash

curl -X POST https://shipstack.codes/api/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "X-User-Token: USER_ACCESS_TOKEN"

Password reset

bash

curl -X POST https://shipstack.codes/api/auth/reset-password \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Database CRUD

Insert, query, update, and delete rows in any table. Supports filters, pagination, and ordering.

Insert a row

bash

curl -X POST https://shipstack.codes/api/db/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "Ship it",
      "completed": false
    }
  }'

Query rows

bash

# Get all rows
curl "https://shipstack.codes/api/db/todos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

# With filters, ordering, and pagination
curl "https://shipstack.codes/api/db/todos?completed=false&order=created_at.desc&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Query Parameters

column=value — Filter by exact match
order=column.asc|desc — Sort results
limit=N — Max rows to return
offset=N — Skip N rows (pagination)
select=col1,col2 — Select specific columns

Update a row

bash

curl -X PUT https://shipstack.codes/api/db/todos/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "completed": true
    }
  }'

Delete a row

bash

curl -X DELETE https://shipstack.codes/api/db/todos/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Real-Time Subscriptions

Subscribe to table changes via Server-Sent Events (SSE). Works with all providers.

Subscribe to changes

bash

curl -N "https://shipstack.codes/api/db/todos/subscribe?interval=2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Returns an SSE stream. You'll receive a snapshot event with the initial data, then INSERT, UPDATE, and DELETE events as changes occur.

Query Parameters

interval=N — Poll frequency in seconds (1–10, default 2)
filters[column]=value — Only subscribe to matching rows

Using the JavaScript SDK

typescript

const sub = shipstack.db.subscribe("todos", { interval: 2 })
  .onSnapshot((records) => {
    console.log("Initial data:", records);
  })
  .onChange((event, data) => {
    // event: 'INSERT' | 'UPDATE' | 'DELETE'
    console.log(event, data);
  })
  .onError((err) => console.error(err));

// Cleanup when done
sub.unsubscribe();

File Storage

Upload, download, list, and delete files. Returns signed URLs for secure access.

Upload a file

bash

curl -X POST https://shipstack.codes/api/storage/avatars \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -F "file=@photo.jpg" \
  -F "path=users/123/avatar.jpg"

List files in a bucket

bash

curl "https://shipstack.codes/api/storage/avatars" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Download a file

bash

curl "https://shipstack.codes/api/storage/avatars/users/123/avatar.jpg" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN" \
  -o avatar.jpg

Get signed URL

bash

curl "https://shipstack.codes/api/storage/avatars/users/123/avatar.jpg/url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

Returns a time-limited signed URL (default 1 hour) for public access.

Delete a file

bash

curl -X DELETE "https://shipstack.codes/api/storage/avatars/users/123/avatar.jpg" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-Token: YOUR_TENANT_TOKEN"

JavaScript SDK

Use @shipstack/js for a typed TypeScript/JavaScript client.

Install

bash

npm install @shipstack/js

Initialize

typescript

import { createClient } from "@shipstack/js";

const shipstack = createClient({
  token: process.env.SHIPSTACK_TOKEN!,
  tenantToken: process.env.SHIPSTACK_TENANT_TOKEN!,
});

Usage

typescript

// Auth
await shipstack.auth.register("user@example.com", "password123");
await shipstack.auth.login("user@example.com", "password123");

// Database
await shipstack.db.insert("todos", { title: "Ship it" });
const { data } = await shipstack.db.select("todos", { limit: 10 });
await shipstack.db.update("todos", "1", { completed: true });
await shipstack.db.delete("todos", "1");

// Real-time
const sub = shipstack.db.subscribe("todos")
  .onSnapshot(console.log)
  .onChange((event, data) => console.log(event, data));

// Storage
await shipstack.storage.upload("avatars", "user/photo.jpg", file);
const url = await shipstack.storage.getSignedUrl("avatars", "user/photo.jpg");

API Reference

Complete list of all endpoints.

Account

POST/registerCreate account

POST/loginGet auth token

GET/userGet current user (needs auth)

Tenants

GET/tenantsList all tenants

POST/tenantsCreate a tenant

GET/tenants/:idGet tenant details

PUT/tenants/:idUpdate tenant

DELETE/tenants/:idDelete tenant

POST/tenants/:id/regenerate-tokenRegenerate API token

GET/tenants/:id/usageGet usage logs

Auth (Tenant)

POST/auth/registerRegister end-user

POST/auth/loginLogin end-user

POST/auth/logoutLogout end-user

GET/auth/userGet end-user profile

POST/auth/reset-passwordSend password reset

Database (Tenant)

GET/db/:tableQuery rows

POST/db/:tableInsert row

PUT/db/:table/:idUpdate row

DELETE/db/:table/:idDelete row

GET/db/:table/subscribeReal-time SSE stream

Storage (Tenant)

GET/storage/:bucketList files

POST/storage/:bucketUpload file

GET/storage/:bucket/:pathDownload file

GET/storage/:bucket/:path/urlGet signed URL

DELETE/storage/:bucket/:pathDelete file

Usage

GET/usage/quotaGet monthly usage & limits

Provider Testing

POST/providers/testValidate provider credentials

Billing

GET/stripe/configGet publishable key + tiers

GET/stripe/statusGet subscription status

POST/stripe/checkoutCreate checkout session

POST/stripe/portalOpen billing portal

Errors

All errors return JSON with a message field. Standard HTTP status codes are used.

400Bad Request — Invalid parameters or request body

401Unauthenticated — Missing or invalid Bearer token

403Forbidden — Token valid but insufficient permissions

404Not Found — Resource or endpoint does not exist

422Validation Error — Request body failed validation rules

429Rate Limited — Too many requests, slow down

500Server Error — Something went wrong on our end

json

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Ready to start building?

Create a free account and connect your first provider in under 5 minutes.

Get Started Free