Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer ak_your_prefix_your_secret_here

Important: Keep your API keys secure and never expose them in client-side code.

Base URL

All API endpoints are relative to:

https://your-domain.com/api/v1

Documents API

The Documents API allows you to store, retrieve, update, and delete JSON documents in collections.

POST /{collection}

Create a new document with an auto-generated ID.

curl -X POST https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin"
    }
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "collection": "users",
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin"
    },
    "version": "1",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "ttl_at": null
  }
}

GET /{collection}/{id}

Retrieve a specific document by ID.

curl -H "Authorization: Bearer ak_your_key" \
  https://your-domain.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000

PUT /{collection}/{id}

Update or create a document (upsert). Requires ETag for optimistic locking.

curl -X PUT https://your-domain.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"1\"" \
  -d '{
    "data": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "role": "admin"
    }
  }'

PATCH /{collection}/{id}/patch

Partially update a document by merging new data with existing data.

curl -X PATCH https://your-domain.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000/patch \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"1\"" \
  -d '{
    "data": {
      "role": "super_admin"
    }
  }'

DELETE /{collection}/{id}

Delete a document permanently.

curl -X DELETE https://your-domain.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ak_your_key"

GET /{collection}

List documents in a collection with optional filtering and pagination.

curl -H "Authorization: Bearer ak_your_key" \
  "https://your-domain.com/api/v1/users&limit=10&page=1"

Querying Documents

Filter and search your documents using powerful query DSL and JSON filters.

Query DSL Syntax

Use the query DSL with the q parameter for powerful filtering:

GET /api/v1/users?q=eq(role,"admin")

Supported operators: eq, ne, gt, gte, lt, lte, in, nin, contains, exists

Multiple Conditions

Combine multiple filters using multiple q parameters:

GET /api/v1/users?q=eq(role,"admin")&q=eq(status,"active")

Array Queries

Query documents with array fields:

GET /api/v1/products?q=in(tags,["electronics","gadgets"])

Numeric Comparisons

Filter by numeric values:

GET /api/v1/products?q=gt(price,100)&q=lt(price,500)

JSON Filter

Use JSON filter for complex queries:

GET /api/v1/users?filter={"eq":{"role":"admin"},"gt":{"age":18}}

Ordering

Sort results by field (prefix with - for descending):

GET /api/v1/users?order=name&order=-created_at

Pagination

Navigate through large result sets using page-based pagination.

Basic Pagination

GET /api/v1/documents&limit=25

Returns up to 25 documents (default limit is 25, maximum is 100).

Page-based Navigation

GET /api/v1/documents&limit=25&page=2

Use the page parameter to navigate through pages. Page numbers start at 1.

Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pages": 5,
    "count": 100,
    "limit": 25,
    "from": 1,
    "to": 25
  }
}

pagination object contains:

page - Current page number
pages - Total number of pages
count - Total number of documents
limit - Number of documents per page
from - First document number on current page
to - Last document number on current page

Error Handling

The API returns standard HTTP status codes and structured error responses.

Error Response Format

{
  "error": {
    "code": "validation_failed",
    "message": "Name can't be blank"
  }
}

Common Status Codes

400 Bad Request - Invalid request parameters

401 Unauthorized - Invalid or missing API key

404 Not Found - Document or resource not found

409 Conflict - ETag mismatch (optimistic locking)

422 Unprocessable Entity - Validation errors

429 Too Many Requests - Rate limit exceeded

Complete Examples

Real-world examples showing how to use the s5 API.

User Management System

1. Create a user

curl -X POST https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "role": "user",
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    }
  }'

2. Update user role

curl -X PATCH https://your-domain.com/api/v1/users/{user_id}/patch \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/\"1\"" \
  -d '{
    "data": {
      "role": "admin"
    }
  }'

3. Find all admin users

curl -H "Authorization: Bearer ak_your_key" \
  "https://your-domain.com/api/v1/users?q=eq(role,\"admin\")"

Product Catalog

1. Add a product

curl -X POST https://your-domain.com/api/v1/products \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Wireless Headphones",
      "price": 99.99,
      "category": "electronics",
      "in_stock": true,
      "tags": ["wireless", "audio", "bluetooth"],
      "specifications": {
        "battery_life": "20 hours",
        "connectivity": "Bluetooth 5.0"
      }
    }
  }'

2. Search products by category

curl -H "Authorization: Bearer ak_your_key" \
  "https://your-domain.com/api/v1/products?q=eq(category,\"electronics\")&q=eq(in_stock,true)"

JavaScript SDK

Use the official s5-orm.js package for easy integration with your JavaScript applications.

Installation

npm install s5-orm.js
# or
yarn add s5-orm.js

Basic Usage

import S5 from 's5-orm.js';

const s5 = new S5({
  apiKey: 'ak_your_prefix_your_secret'
});

// Get a collection
const User = s5.collection('users');

// Create a user
const user = await User.create({
  name: 'John Doe',
  email: 'john@example.com',
  role: 'admin'
});

// Find a user
const foundUser = await User.find(user.id);

// Update a user
foundUser.data.role = 'super_admin';
await foundUser.save();

// Query users
const adminUsers = await User.where({
  q: ['eq(role,"admin")']
});

// Multiple conditions
const activeAdmins = await User.where({
  q: ['eq(role,"admin")', 'eq(status,"active")']
});

// Array queries
const taggedProducts = await Product.where({
  q: ['in(tags,["electronics","gadgets"])']
});

s5 API Documentation