### Connection URL Examples

Source: https://docs.revisium.io/apis/cli

Examples of connection strings for Cloud, Standalone, and Docker environments.

```text
# Cloud  
revisium://cloud.revisium.io/myuser/my-project/master?token=eyJ...  
  
# Standalone (no auth)  
revisium://localhost:9222/admin/my-project/master  
  
# Docker  
revisium://localhost:8080/admin/my-project/master?token=eyJ...
```

--------------------------------

### Configure Standalone Options

Source: https://docs.revisium.io/deployment

Examples for running with custom ports, authentication, or persistent data directories.

```bash
# Custom port with auth  
npx @revisium/standalone@latest --port 3000 --auth  
  
# Persistent data  
npx @revisium/standalone@latest --data ./revisium-data  
```

--------------------------------

### Run Standalone Revisium

Source: https://docs.revisium.io/deployment

Starts the application with embedded PostgreSQL and zero configuration.

```bash
npx @revisium/standalone@latest  
```

--------------------------------

### Initialize Revisium for Development

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Commands to clone the repository, start the standalone instance, and seed the database.

```bash
git clone <repo> && cd <repo> && npm install  
  
# Start Revisium (empty DB on first run)  
npx @revisium/standalone@latest  
  
# Apply migrations + load seed data  
npm run revisium:seed  
# → npx revisium migrate apply --url revisium://admin:admin@localhost:9222/admin/faq/master --file ./revisium/migrations.json --commit  
# → npx revisium rows upload --url revisium://admin:admin@localhost:9222/admin/faq/master/draft --folder ./revisium/data --commit  
  
# Start backend  
npm run start:dev  
```

--------------------------------

### Complete Migration File Example

Source: https://docs.revisium.io/architecture/specs/migration-format

A full migration array demonstrating multiple operations in chronological order.

```json
[
  {
    "changeType": "init",
    "id": "2025-01-20T10:00:00.000Z",
    "tableId": "Category",
    "hash": "...",
    "schema": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": { "type": "string", "default": "" }
      }
    }
  },
  {
    "changeType": "init",
    "id": "2025-01-20T10:00:01.000Z",
    "tableId": "Product",
    "hash": "...",
    "schema": {
      "type": "object",
      "required": ["name", "category"],
      "properties": {
        "name": { "type": "string", "default": "" },
        "category": { "type": "string", "default": "", "foreignKey": "Category" }
      }
    }
  },
  {
    "changeType": "update",
    "id": "2025-01-21T14:00:00.000Z",
    "tableId": "Product",
    "hash": "...",
    "schemaPatch": [
      { "op": "add", "path": "/properties/price", "value": { "type": "number", "default": 0 } }
    ]
  }
]
```

--------------------------------

### Startup Command for Migrations

Source: https://docs.revisium.io/migrations/ci-cd

Configures the production start command to execute migrations before launching the application.

```json
{
  "scripts": {
    "start:prod": "npm run revisium:apply-migrations && node dist/main"
  }
}
```

--------------------------------

### Install OpenAPI Generator Dependencies

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Installs the necessary packages for generating a typed client from an OpenAPI specification.

```bash
npm install -D @hey-api/openapi-ts @hey-api/client-fetch
```

--------------------------------

### Install Revisium CLI

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Installs the Revisium CLI as a development dependency.

```bash
npm install -D @revisium/cli  
```

--------------------------------

### Configure Production Startup Script

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Update the package.json start script to apply migrations before launching the application.

```json
{
  "scripts": {  
    "start:prod": "npm run revisium:seed && node dist/src/main"  
  }
}
```

--------------------------------

### Generated OpenAPI Specification Excerpt

Source: https://docs.revisium.io/

Example of the OpenAPI path and component definitions.

```yaml
paths:  
  /tables/products/row/{rowId}:  
    get:  
      operationId: get_products  
      summary: Get products by ID  
  /tables/products/rows:  
    post:  
      operationId: query_products  
      summary: Query products rows  
components:  
  schemas:  
    Products:  
      type: object  
      properties:  
        title: { type: string }  
        price: { type: number }  
        category: { type: string }  
```

--------------------------------

### GraphQL Queries for Products

Source: https://docs.revisium.io/apis/generated-apis

Examples for fetching single product records or lists with filtering, sorting, and pagination.

```graphql
# Single row  
query {  
  product(id: "iphone-16") {  
    id  
    createdAt  
    data { title price }  
  }  
}  
  
# List with filtering, sorting, pagination  
query {  
  products(data: {  
    first: 20  
    where: { data: { path: ["price"], gte: 100 } }  
    orderBy: [{ data: { path: "price", direction: "desc", type: "float" } }]  
  }) {  
    edges {  
      node { id data { title price } }  
      cursor  
    }  
    pageInfo { hasNextPage endCursor }  
    totalCount  
  }  
}  
```

--------------------------------

### API Key Format Example

Source: https://docs.revisium.io/auth-permissions/api-keys

The standard format for all API keys, which must begin with the rev_ prefix.

```text
rev_V1StGXR8_Z5jdHi6B-myT  
```

--------------------------------

### Example Data Structure with Files

Source: https://docs.revisium.io/core-concepts/files

A JSON object demonstrating how file metadata is stored within a project schema.

```json
{
  "title": "Getting Started Guide",
  "slides": [
    {
      "image": { "status": "uploaded", "fileId": "...", "url": "https://s3.../step1.jpg", "fileName": "step1.jpg", ... },
      "caption": "Step 1: Create a project"
    },
    {
      "image": { "status": "ready", "fileId": "...", "url": "", "fileName": "", ... },
      "caption": "Step 2: Design schema"
    }
  ],
  "branding": {
    "logo": { "status": "uploaded", "fileId": "...", "url": "https://s3.../logo.svg", "fileName": "logo.svg", ... },
    "color": "#171717"
  }
}
```

--------------------------------

### JSON Patch Syntax Examples

Source: https://docs.revisium.io/querying-data/crud

Demonstrates various path configurations for updating top-level, nested, and array-based fields.

```json
// Update a top-level field  
{ "op": "replace", "path": "title", "value": "iPhone 16 Pro Max" }  
  
// Update a nested field  
{ "op": "replace", "path": "specs.weight", "value": 227 }  
  
// Update a field inside an array item  
{ "op": "replace", "path": "items[0].quantity", "value": 20 }  
  
// Update multiple fields at once  
[  
  { "op": "replace", "path": "price", "value": 1099 },  
  { "op": "replace", "path": "inStock", "value": true }  
]  
```

--------------------------------

### Start Revisium in Standalone Mode

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Use this command to launch the API, Admin UI, and embedded PostgreSQL database locally.

```bash
npx @revisium/standalone@latest
```

--------------------------------

### Authentication Methods

Source: https://docs.revisium.io/auth-permissions/api-keys

Examples of how to provide API keys via headers or query parameters for REST and GraphQL endpoints.

```APIDOC
## API Key Authentication

### Description
Revisium supports three authentication methods for API keys: X-Api-Key header (recommended), Authorization: Bearer header, and query parameters for webhooks.

### Authentication Methods
- **X-Api-Key Header**: Pass the key in the `X-Api-Key` header.
- **Authorization: Bearer Header**: Pass the key in the `Authorization` header with the `Bearer` prefix.
- **Query Parameter**: Pass the key as the `api_key` query parameter (primarily for webhooks).

### Examples

#### X-Api-Key Header (REST)
```bash
curl http://localhost:8080/api/organization/myorg/project/myproject/branch/master \
  -H "X-Api-Key: rev_xxxxxxxxxxxxxxxxxxxx"
```

#### X-Api-Key Header (GraphQL)
```bash
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: rev_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"query": "{ me { id username } }"}'
```

#### Authorization: Bearer Header
```bash
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rev_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"query": "{ me { id username } }"}'
```

#### Query Parameter
```text
https://your-instance/api/...?api_key=rev_xxxxxxxxxxxxxxxxxxxx
```
```

--------------------------------

### Authentication Methods

Source: https://docs.revisium.io/apis/cli

Examples of using JWT tokens or API keys within the connection URL.

```text
# JWT token  
revisium://localhost:9222/admin/my-project/master?token=eyJ...  
  
# API key (via apikey parameter or auto-detected by rev_ prefix in token)  
revisium://localhost:9222/admin/my-project/master?apikey=rev_xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Define a Products Table

Source: https://docs.revisium.io/core-concepts/data-modeling

Example of a data object and its corresponding JSON Schema for a products table.

```json
{
  "title": "iPhone 16 Pro",
  "price": 999,
  "inStock": true,
  "description": "Latest flagship smartphone"
}
```

```json
{
  "type": "object",
  "properties": {
    "title": { "type": "string", "default": "" },
    "price": { "type": "number", "default": 0 },
    "inStock": { "type": "boolean", "default": false },
    "description": { "type": "string", "default": "" }
  },
  "required": ["title", "price", "inStock", "description"],
  "additionalProperties": false
}
```

--------------------------------

### Start Docker Compose Services

Source: https://docs.revisium.io/deployment

Command to launch the defined Docker services in detached mode.

```bash
docker-compose up -d  
```

--------------------------------

### File Field States

Source: https://docs.revisium.io/core-concepts/files

Examples of the File schema object structure during different lifecycle stages.

```json
{
  "status": "ready",
  "fileId": "Ua4ZaUehur50VOp2odFvy",
  "url": "",
  "fileName": "",
  "hash": "",
  "extension": "",
  "mimeType": "",
  "size": 0,
  "width": 0,
  "height": 0
}
```

```json
{
  "status": "uploaded",
  "fileId": "Ua4ZaUehur50VOp2odFvy",
  "url": "https://s3.../cover.jpg",
  "fileName": "cover.jpg",
  "hash": "a1b2c3d4e5...",
  "extension": "jpg",
  "mimeType": "image/jpeg",
  "size": 340000,
  "width": 1200,
  "height": 800
}
```

```json
{
  "status": "uploaded",
  "fileId": "Ua4ZaUehur50VOp2odFvy",
  "url": "https://s3.../cover-v2.png",
  "fileName": "cover-v2.png",
  "hash": "f6g7h8i9j0...",
  "extension": "png",
  "mimeType": "image/png",
  "size": 520000,
  "width": 1600,
  "height": 900
}
```

--------------------------------

### Dockerfile for Migration Deployment

Source: https://docs.revisium.io/migrations/ci-cd

Multi-stage Dockerfile setup to include migration files in the final production image.

```dockerfile
FROM node:22-alpine AS builder  
WORKDIR /app  
COPY package*.json ./  
RUN npm ci  
COPY . .  
RUN npm run build  
  
FROM node:22-alpine  
WORKDIR /app  
COPY --from=builder /app/dist ./dist/  
COPY --from=builder /app/revisium/ ./revisium/  
COPY --from=builder /app/package*.json ./  
RUN npm ci --omit=dev  
  
CMD ["npm", "run", "start:prod"]
```

--------------------------------

### Start Standalone Revisium

Source: https://docs.revisium.io/quick-start

Run the standalone version of Revisium using npx. Use the --auth flag to enable authentication.

```bash
npx @revisium/standalone@latest
```

```bash
npx @revisium/standalone@latest --auth
```

--------------------------------

### Query Generated GraphQL API

Source: https://docs.revisium.io/

Example of querying products with filtering, sorting, and pagination.

```graphql
query {  
  products(data: {  
    where: { data: { path: ["category"], equals: "electronics" } }  
    orderBy: [{ data: { path: "price", direction: "desc", type: "float" } }]  
    first: 10  
  }) {  
    edges {  
      node { data { title, price, category { name } } }  
    }  
  }  
}  
```

```json
{  
  "data": {  
    "products": {  
      "edges": [  
        {  
          "node": {  
            "data": {  
              "title": "iPhone 16 Pro",  
              "price": 999,  
              "category": { "name": "Electronics" }  
            }  
          }  
        }  
      ]  
    }  
  }  
}  
```

--------------------------------

### Initialize and Configure Revisium

Source: https://docs.revisium.io/use-cases/ai-agent-memory

Commands to start the standalone Revisium server and register it as an MCP tool within Claude Code.

```bash
# Start Revisium  
npx @revisium/standalone@latest --auth  
  
# Add to Claude Code  
claude mcp add --transport http revisium http://localhost:9222/mcp  
```

--------------------------------

### Full GitHub Actions Pipeline with Seeding

Source: https://docs.revisium.io/migrations/ci-cd

A complete workflow example that runs schema migrations and conditionally uploads seed data.

```yaml
name: Full Deploy  
on:  
  push:  
    branches: [main]  
  
jobs:  
  deploy:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
      - uses: actions/setup-node@v4  
        with:  
          node-version: '20'  
      - name: Apply Schema Migrations  
        run: npx revisium migrate apply --file ./revisium/migrations.json --commit  
        env:  
          REVISIUM_URL: revisium://cloud.revisium.io/${{ vars.ORG }}/${{ vars.PROJECT }}/master  
          REVISIUM_TOKEN: ${{ secrets.REVISIUM_TOKEN }}  
      - name: Upload Seed Data  
        if: github.ref == 'refs/heads/main'  
        run: npx revisium rows upload --folder ./revisium/data --commit  
        env:  
          REVISIUM_URL: revisium://cloud.revisium.io/${{ vars.ORG }}/${{ vars.PROJECT }}/master  
          REVISIUM_TOKEN: ${{ secrets.REVISIUM_TOKEN }}  
      - name: Deploy Application  
        run: # your deployment step  
```

--------------------------------

### Cascade rename table example

Source: https://docs.revisium.io/core-concepts/foreign-keys

Shows how the foreignKey declaration in a schema is updated when the referenced table name changes.

```text
products schema:  "foreignKey": "categories"  →  "foreignKey": "product-categories"  
```

--------------------------------

### GitHub Actions Migration Authentication

Source: https://docs.revisium.io/migrations/ci-cd

Examples of applying migrations in GitHub Actions using different authentication strategies.

```yaml
name: Deploy  
on:  
  push:  
    branches: [main]  
  
jobs:  
  deploy:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
      - uses: actions/setup-node@v4  
        with:  
          node-version: '20'  
      - name: Apply Migrations  
        run: npx revisium migrate apply --file ./revisium/migrations.json --commit  
        env:  
          REVISIUM_URL: revisium://cloud.revisium.io/${{ vars.ORG }}/${{ vars.PROJECT }}/master  
          REVISIUM_TOKEN: ${{ secrets.REVISIUM_TOKEN }}  
```

```yaml
      - name: Apply Migrations  
        run: npx revisium migrate apply --file ./revisium/migrations.json --commit  
        env:  
          REVISIUM_URL: revisium://cloud.revisium.io/${{ vars.ORG }}/${{ vars.PROJECT }}/master  
          REVISIUM_USERNAME: ${{ secrets.REVISIUM_USERNAME }}  
          REVISIUM_PASSWORD: ${{ secrets.REVISIUM_PASSWORD }}  
```

```yaml
      - name: Apply Migrations  
        run: |  
          docker run --rm \
            -e REVISIUM_URL=revisium://cloud.revisium.io/${{ vars.ORG }}/${{ vars.PROJECT }}/master \
            -e REVISIUM_TOKEN=${{ secrets.REVISIUM_TOKEN }} \
            -v ${{ github.workspace }}/revisium/migrations.json:/app/migrations.json \
            revisium/revisium-cli \
            revisium migrate apply --file /app/migrations.json --commit  
```

--------------------------------

### Kubernetes Init Container for Migrations

Source: https://docs.revisium.io/migrations/ci-cd

Configures an init container in a Kubernetes Deployment to execute migrations before the main application starts.

```yaml
apiVersion: apps/v1  
kind: Deployment  
metadata:  
  name: my-app  
spec:  
  selector:  
    matchLabels:  
      app: my-app  
  template:  
    metadata:  
      labels:  
        app: my-app  
    spec:  
      initContainers:  
      - name: revisium-migrate  
        image: my-registry/my-app-migrations:latest  
        command: ["revisium"]  
        args:  
          - migrate  
          - apply  
          - --file=/app/migrations.json  
          - --commit  
        env:  
          - name: REVISIUM_URL  
            value: "revisium://revisium.example.com/myorg/myproject/master"  
          - name: REVISIUM_USERNAME  
            valueFrom:  
              secretKeyRef:  
                name: revisium-credentials  
                key: username  
          - name: REVISIUM_PASSWORD  
            valueFrom:  
              secretKeyRef:  
                name: revisium-credentials  
                key: password  
      containers:  
      - name: app  
        image: my-registry/my-app:latest  
```

--------------------------------

### Query Feature Flag API

Source: https://docs.revisium.io/use-cases/configuration-store

Example of fetching a specific feature flag configuration and applying logic based on the returned data.

```javascript
const response = await fetch('https://revisium.example.com/endpoint/feature-flags/dark-mode');
const { data } = await response.json();

if (data.enabled && Math.random() * 100 < data.rollout) {
  enableDarkMode();
}
```

--------------------------------

### Define Data Models with JSON Schema

Source: https://docs.revisium.io/

Example of a product data object and its corresponding JSON Schema definition for validation.

```json
{
  "title": "iPhone 16 Pro",
  "price": 999,
  "inStock": true,
  "specs": {
    "weight": 199,
    "tags": ["5G", "USB-C", "ProMotion"]
  },
  "variants": [
    { "color": "Desert Titanium", "storage": 256 },
    { "color": "Black Titanium", "storage": 512 }
  ]
}
```

```json
{
  "type": "object",
  "properties": {
    "title": { "type": "string", "default": "" },
    "price": { "type": "number", "default": 0 },
    "inStock": { "type": "boolean", "default": false },
    "specs": {
      "type": "object",
      "properties": {
        "weight": { "type": "number", "default": 0 },
        "tags": { "type": "array", "items": { "type": "string", "default": "" } }
      },
      "required": ["weight", "tags"]
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "color": { "type": "string", "default": "" },
          "storage": { "type": "number", "default": 0 }
        },
        "required": ["color", "storage"]
      }
    }
  },
  "required": ["title", "price", "inStock", "specs", "variants"]
}
```

--------------------------------

### GraphQL API Request with API Key

Source: https://docs.revisium.io/apis/generated-apis

Example of performing a POST request to a GraphQL endpoint including the API key in the headers.

```bash
curl -X POST http://localhost:8080/endpoint/graphql/myorg/myproject/master/head \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: rev_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"query": "{ products { edges { node { id data { title price } } } } }"}'  
```

--------------------------------

### REST API Request with API Key

Source: https://docs.revisium.io/apis/generated-apis

Example of performing a read operation on a REST endpoint using an API key for authentication.

```bash
curl http://localhost:8080/endpoint/rest/myorg/myproject/master/head/tables/products/rows \
  -H "X-Api-Key: rev_xxxxxxxxxxxxxxxxxxxx"  
```

--------------------------------

### Seed Data Directory Structure

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Example directory structure for stored seed data where folders represent tables and files represent rows.

```text
revisium/data/  
├── FaqCategory/  
│   ├── payment.json       # rowId = "payment"  
│   └── delivery.json  
└── FaqItem/  
    ├── faq-1.json          # rowId = "faq-1"  
    └── faq-2.json  
```

--------------------------------

### Cascade rename row example

Source: https://docs.revisium.io/core-concepts/foreign-keys

Shows how foreign key references in the products table are automatically updated when a row in the categories table is renamed.

```text
products/iphone-16:  category: "electronics"  →  category: "electronics-devices"  
products/macbook-m4: category: "electronics"  →  category: "electronics-devices"  
```

--------------------------------

### Agent Memory Interaction Workflow

Source: https://docs.revisium.io/use-cases/ai-agent-memory

Example sequence of MCP tool calls used by an agent to define schemas and persist research data.

```text
Agent: "I need to store research findings"  
→ login  
→ createTable("findings", schema with title, source, content, tags)  
→ createRow("findings", "finding-1", { title: "...", content: "...", ... })  
→ commitRevision (with user permission)  
```

--------------------------------

### Define Foreign Key Array Data

Source: https://docs.revisium.io/core-concepts/foreign-keys

Example data for tags and products tables demonstrating a one-to-many relationship using an array of foreign keys.

```json
{ "name": "5G" }  
```

```json
{  
  "title": "iPhone 16 Pro",  
  "tags": ["5g", "usb-c", "promotion"]  
}  
```

--------------------------------

### Get Single Row via REST

Source: https://docs.revisium.io/querying-data/crud

Fetches a single row using a GET request to the specified endpoint.

```http
GET /endpoint/rest/<org>/<project>/<branch>/head/tables/products/row/iphone-16  
```

--------------------------------

### GET /tables/products/row/:rowId

Source: https://docs.revisium.io/apis/generated-apis

Retrieves a single product row by its ID.

```APIDOC
## GET /tables/products/row/:rowId

### Description
Retrieves a single product row by its unique identifier.

### Method
GET

### Endpoint
/tables/products/row/:rowId

### Parameters
#### Path Parameters
- **rowId** (string) - Required - The unique identifier of the product row.
```

--------------------------------

### Typical migration workflow

Source: https://docs.revisium.io/apis/cli

Standard sequence for exporting migrations from a development instance and applying them to staging and production environments.

```bash
# 1. Export migrations from dev  
npx revisium migrate save --file ./migrations.json \  
  --url revisium://localhost:9222/admin/my-project/master  
  
# 2. Apply to staging  
npx revisium migrate apply --file ./migrations.json --commit \  
  --url revisium://staging.example.com/admin/my-project/master?token=...  
  
# 3. Apply to production  
npx revisium migrate apply --file ./migrations.json --commit \  
  --url revisium://prod.example.com/admin/my-project/master?token=...  

```

--------------------------------

### Deploy with Docker

Source: https://docs.revisium.io/deployment

Run a single container instance with an external PostgreSQL database.

```bash
docker run -d \
  -p 8080:8080 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/revisium?schema=public \
  -e ADMIN_PASSWORD=change-me \
  revisium/revisium:latest
```

--------------------------------

### Move Field Data Structure

Source: https://docs.revisium.io/core-concepts/schema-evolution

Example of moving a field from the root level into a nested object.

```json
{
  "title": "iPhone 16 Pro",
  "weight": 199,
  "specs": {
    "color": "Desert Titanium"
  }
}
```

```json
{
  "title": "iPhone 16 Pro",
  "specs": {
    "color": "Desert Titanium",
    "weight": 199
  }
}
```

--------------------------------

### Get Single Row

Source: https://docs.revisium.io/querying-data/crud

Retrieves a single product row by its ID using GraphQL or REST.

```APIDOC
## GraphQL query { product(id: "iphone-16") } 

### Description
Fetches a single product record by ID.

### Request Example
query { product(id: "iphone-16") { id createdAt data { title price } } }

## GET /endpoint/rest/<org>/<project>/<branch>/head/tables/products/row/<id>

### Description
Retrieves a single product record via REST.

### Method
GET

### Endpoint
/endpoint/rest/<org>/<project>/<branch>/head/tables/products/row/<id>
```

--------------------------------

### GET /mcp

Source: https://docs.revisium.io/apis/mcp

Establishes an SSE (Server-Sent Events) stream for receiving notifications from the MCP server.

```APIDOC
## GET /mcp

### Description
Establishes an SSE stream for receiving notifications from the MCP server.

### Method
GET

### Endpoint
/mcp
```

--------------------------------

### Export and Apply Migrations via File

Source: https://docs.revisium.io/migrations

Use these commands to save schema changes from a source instance to a file and then apply them to a target instance.

```bash
# 1. Export migrations from source instance  
npx revisium migrate save --file ./migrations.json \
  --url revisium://localhost:9222/admin/my-project/master  
  
# 2. Apply to target instance  
npx revisium migrate apply --file ./migrations.json --commit \
  --url revisium://staging.example.com/admin/my-project/master?token=...
```

--------------------------------

### Migration Flow Diagram

Source: https://docs.revisium.io/migrations/ci-cd

Visual representation of the recommended schema migration path from development to production.

```text
Dev (source of truth)  
  │  
  │  migrate save / sync schema  
  ↓  
Staging (test)  
  │  
  │  migrate apply / sync schema  
  ↓  
Production  
```

--------------------------------

### Initial migration generation

Source: https://docs.revisium.io/apis/cli

Workflow for generating a migration file from scratch by first exporting schemas and then converting them into migrations.

```bash
# 1. Export schemas  
npx revisium schema save --folder ./schemas \  
  --url revisium://localhost:9222/admin/my-project/master  
  
# 2. Generate migrations from schemas  
npx revisium schema create-migrations \  
  --schemas-folder ./schemas --file ./migrations.json  

```

--------------------------------

### Initialize and Use RevisiumClient

Source: https://docs.revisium.io/apis/system-api

Instantiate the client with authentication credentials and retrieve project or table information.

```typescript
import { RevisiumClient } from '@revisium/client';  
  
const client = new RevisiumClient({  
  url: 'http://localhost:8080',  
  username: 'admin',  
  password: 'admin',  
});  
  
const project = await client.getProject('my-org', 'my-project');  
const tables = await client.getTables(revisionId);
```

--------------------------------

### REST API Queries

Source: https://docs.revisium.io/apis/generated-apis

REST endpoints for retrieving product rows using GET and POST methods.

```http
# Single row  
GET /tables/products/row/iphone-16  
  
# List with filtering, sorting, pagination  
POST /tables/products/rows  
Content-Type: application/json  
  
{  
  "first": 20,  
  "where": { "data": { "path": ["price"], "gte": 100 } },  
  "orderBy": [{ "data": { "path": "price", "direction": "desc", "type": "float" } }]  
}  
```

--------------------------------

### All-in-One Deployment Structure

Source: https://docs.revisium.io/architecture

Visual representation of the single-process deployment mode where all services run together.

```text
revisium (single process)  
├── @revisium/core  
├── @revisium/admin (static files)  
└── @revisium/endpoint  
```

--------------------------------

### Manage Migrations via CLI

Source: https://docs.revisium.io/

Commands to export and apply database migrations across different environments.

```bash
# Export migrations from source instance
npx revisium migrate save --file ./migrations.json

# Apply to target instance
npx revisium migrate apply --file ./migrations.json
```

--------------------------------

### Configure Admin Interface Environment Variables

Source: https://docs.revisium.io/apis/configuration

Enables full type variants and project prefixes for clear disambiguation.

```text
ENDPOINT_GRAPHQL_SHOW_NODE_TYPE=true  
ENDPOINT_GRAPHQL_SHOW_FLAT_TYPE=true  
ENDPOINT_GRAPHQL_ADD_PROJECT_PREFIX=true  
```

--------------------------------

### Define Single Foreign Key Data

Source: https://docs.revisium.io/core-concepts/foreign-keys

Example data for categories and products tables demonstrating a many-to-one relationship.

```json
{ "name": "Electronics" }  
```

```json
{  
  "title": "iPhone 16 Pro",  
  "price": 999,  
  "category": "electronics"  
}  
```

--------------------------------

### Project Structure for Migrations

Source: https://docs.revisium.io/migrations/ci-cd

Recommended directory layout for storing migration files and seed data alongside source code.

```text
my-project/  
├── revisium/  
│   ├── migrations.json    # schema migrations  
│   └── data/              # seed data (optional)  
│       ├── products/  
│       │   ├── iphone-16.json  
│       │   └── macbook-m4.json  
│       └── categories/  
│           └── electronics.json  
├── src/  
└── package.json  
```

--------------------------------

### REST API Row Creation Response

Source: https://docs.revisium.io/core-concepts/files

Example response structure containing the fileId required for the upload step.

```json
{
  "data": {
    "title": "iPhone 16 Pro",
    "cover": {
      "status": "ready",
      "fileId": "abc123-def456-...",
      "url": "",
      "fileName": "",
      ...
    }
  }
}
```

--------------------------------

### Export and Import Data Portability

Source: https://docs.revisium.io/

Commands for backing up schemas and data, or seeding a new instance.

```bash
# Download all schemas
npx revisium schema save --folder ./schemas

# Download all data
npx revisium data save --folder ./data

# Upload to another instance
npx revisium data apply --folder ./data
```

--------------------------------

### Authenticate with API Keys

Source: https://docs.revisium.io/auth-permissions/authentication

Use either the X-Api-Key header or the Authorization Bearer header for programmatic access.

```bash
# Using X-Api-Key header  
curl -H "X-Api-Key: rev_xxxxxxxxxxxxxxxxxxxx" \  
  http://localhost:8080/api/...  
  
# Using Bearer header  
curl -H "Authorization: Bearer rev_xxxxxxxxxxxxxxxxxxxx" \  
  http://localhost:8080/api/...  

```

--------------------------------

### Fetch Data in Next.js

Source: https://docs.revisium.io/use-cases/headless-cms

Example of fetching content from the Revisium GraphQL endpoint within a Next.js App Router function.

```javascript
async function getArticles() {
  const res = await fetch('https://revisium.example.com/endpoint/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `{
        articles(data: { first: 20, where: { data: { path: ["published"], equals: true } } }) {
          edges { node { data { title slug content author { name } } } }
        }
      }`
    }),
    next: { revalidate: 60 },
  });
  return res.json();
}
```

--------------------------------

### Generate migration files

Source: https://docs.revisium.io/apis/cli

Creates a migration file from existing local schema files, automatically handling table dependency ordering and integrity hashing.

```bash
npx revisium schema create-migrations \  
  --schemas-folder ./schemas \  
  --file ./migrations.json  

```

--------------------------------

### GraphQL Filtering Operations

Source: https://docs.revisium.io/querying-data/filtering

Examples of filtering records using various operators and logical combinations within GraphQL queries.

```APIDOC
## GraphQL Filtering

### Description
Filter records by any field in your data using JSON path-based expressions. Combine multiple conditions with AND, OR, and NOT logic.

### Operators
- **String**: equals, not, in, notIn, string_contains, string_starts_with, string_ends_with, mode: insensitive
- **Numeric**: equals, not, gt, gte, lt, lte, in
- **Array**: array_contains, array_starts_with
- **Logical**: AND, OR, NOT

### System Fields
- **id** (String)
- **createdAt** (DateTime)
- **updatedAt** (DateTime)
- **readonly** (Boolean)

### Example Query
```graphql
query GetTargetedUsers {  
  users(data: {  
    where: {  
      AND: [  
        { data: { path: ["status"], equals: "active" } },  
        {  
          OR: [  
            { data: { path: ["role"], equals: "admin" } },  
            {  
              AND: [  
                { data: { path: ["role"], equals: "developer" } },  
                { data: { path: ["level"], equals: "senior" } }  
              ]  
            }  
          ]  
        },  
        {  
          NOT: {  
            data: { path: ["department"], in: ["temp", "contractor"] }  
          }  
        }  
      ]  
    }  
  }) {  
    edges { node { data { name role level department } } }  
  }  
} 
```
```

--------------------------------

### Define Foreign Keys in Nested Objects

Source: https://docs.revisium.io/core-concepts/foreign-keys

Example of referencing a users table from fields within a nested metadata object.

```json
{
  "title": "Getting Started",
  "metadata": {
    "author": "john-doe",
    "reviewer": "jane-smith"
  }
}
```

```json
{
  "type": "object",
  "properties": {
    "title": { "type": "string", "default": "" },
    "metadata": {
      "type": "object",
      "properties": {
        "author": {
          "type": "string",
          "default": "",
          "foreignKey": "users"
        },
        "reviewer": {
          "type": "string",
          "default": "",
          "foreignKey": "users"
        }
      },
      "required": ["author", "reviewer"]
    }
  },
  "required": ["title", "metadata"],
  "additionalProperties": false
}
```

--------------------------------

### Define Foreign Keys in Array of Objects

Source: https://docs.revisium.io/core-concepts/foreign-keys

Example of referencing a products table from within an items array in an orders document.

```json
{
  "customer": "Acme Corp",
  "items": [
    { "product": "iphone-16", "quantity": 10 },
    { "product": "macbook-m4", "quantity": 5 }
  ]
}
```

```json
{
  "type": "object",
  "properties": {
    "customer": { "type": "string", "default": "" },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "default": "",
            "foreignKey": "products"
          },
          "quantity": { "type": "number", "default": 0 }
        },
        "required": ["product", "quantity"]
      }
    }
  },
  "required": ["customer", "items"],
  "additionalProperties": false
}
```

--------------------------------

### GitHub Actions CI Build Strategy

Source: https://docs.revisium.io/migrations/ci-cd

Automates building both the application and migration images using a matrix strategy in GitHub Actions.

```yaml
# GitHub Actions — build app + migrations images  
jobs:  
  build:  
    strategy:  
      matrix:  
        include:  
          - name: app  
            dockerfile: Dockerfile  
            context: "."  
          - name: migrations  
            dockerfile: revisium/Dockerfile  
            context: "."  
    steps:  
      - uses: actions/checkout@v4  
      - name: Build and push  
        uses: docker/build-push-action@v5  
        with:  
          context: ${{ matrix.context }}  
          file: ${{ matrix.dockerfile }}  
          push: true  
          tags: my-registry/my-app-${{ matrix.name }}:latest  
```

--------------------------------

### Define a complete table schema with nested objects and arrays

Source: https://docs.revisium.io/core-concepts/data-modeling

Example of a JSON data object and its corresponding schema definition.

```json
{
  "title": "iPhone 16 Pro",
  "price": 999,
  "inStock": true,
  "specs": {
    "weight": 199,
    "tags": ["5G", "USB-C", "ProMotion"]
  },
  "variants": [
    { "color": "Desert Titanium", "storage": 256 },
    { "color": "Black Titanium", "storage": 512 }
  ]
}
```

```json
{
  "type": "object",
  "properties": {
    "title": { "type": "string", "default": "" },
    "price": { "type": "number", "default": 0 },
    "inStock": { "type": "boolean", "default": false },
    "specs": {
      "type": "object",
      "properties": {
        "weight": { "type": "number", "default": 0 },
        "tags": {
          "type": "array",
          "items": { "type": "string", "default": "" }
        }
      },
      "required": ["weight", "tags"]
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "color": { "type": "string", "default": "" },
          "storage": { "type": "number", "default": 0 }
        },
        "required": ["color", "storage"]
      }
    }
  },
  "required": ["title", "price", "inStock", "specs", "variants"],
  "additionalProperties": false
}
```

--------------------------------

### Configure Claude Desktop

Source: https://docs.revisium.io/apis/mcp

Configuration file structure for adding the Revisium MCP server to Claude Desktop.

```json
{
  "mcpServers": {
    "revisium-local": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

--------------------------------

### Get Single Row via GraphQL

Source: https://docs.revisium.io/querying-data/crud

Retrieves a specific row by ID using standard or flat GraphQL queries.

```graphql
query {  
  product(id: "iphone-16") {  
    id  
    createdAt  
    data { title price }  
  }  
}  
```

```graphql
query {  
  productFlat(id: "iphone-16") {  
    title  
    price  
  }  
}  
```

--------------------------------

### Microservice Deployment Architecture

Source: https://docs.revisium.io/architecture

Visual representation of the distributed deployment mode for horizontal scaling.

```text
@revisium/admin → @revisium/core ← @revisium/endpoint  
                        ↓  
                   PostgreSQL  
```

--------------------------------

### Configure Public API Environment Variables

Source: https://docs.revisium.io/apis/configuration

Sets up simplified types by disabling Node types and project prefixes.

```text
ENDPOINT_GRAPHQL_SHOW_NODE_TYPE=false  
ENDPOINT_GRAPHQL_SHOW_FLAT_TYPE=true  
ENDPOINT_GRAPHQL_ADD_PROJECT_PREFIX=false  
```

--------------------------------

### Deploy with Kubernetes

Source: https://docs.revisium.io/deployment

Standard deployment manifest for running the application in a Kubernetes cluster.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: revisium
spec:
  replicas: 1
  selector:
    matchLabels:
      app: revisium
  template:
    metadata:
      labels:
        app: revisium
    spec:
      containers:
      - name: revisium
        image: revisium/revisium:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: database-url
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: jwt-secret
        - name: ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: admin-password
```

--------------------------------

### Define an Init Migration

Source: https://docs.revisium.io/architecture/specs/migration-format

Used to create a new table with a full schema definition.

```json
{
  "changeType": "init",
  "id": "2025-01-20T10:00:00.000Z",
  "tableId": "Product",
  "hash": "a1b2c3...",
  "schema": {
    "type": "object",
    "required": ["name", "price"],
    "properties": {
      "name": { "type": "string", "default": "" },
      "price": { "type": "number", "default": 0 }
    }
  }
}
```

--------------------------------

### Define S3 File Attachment Data

Source: https://docs.revisium.io/

Example JSON structure for a record containing a single file attachment and a gallery of files.

```json
{
  "title": "iPhone 16 Pro",
  "cover": {
    "status": "uploaded",
    "fileId": "abc123",
    "url": "https://s3.../cover.jpg",
    "fileName": "cover.jpg",
    "hash": "sha256...",
    "extension": "jpg",
    "mimeType": "image/jpeg",
    "size": 340000,
    "width": 1200,
    "height": 800
  },
  "gallery": [
    {
      "status": "uploaded",
      "fileId": "def456",
      "url": "https://s3.../front.jpg",
      "fileName": "front.jpg",
      "hash": "sha256...",
      "extension": "jpg",
      "mimeType": "image/jpeg",
      "size": 280000,
      "width": 1200,
      "height": 800
    },
    {
      "status": "uploaded",
      "fileId": "ghi789",
      "url": "https://s3.../back.jpg",
      "fileName": "back.jpg",
      "hash": "sha256...",
      "extension": "jpg",
      "mimeType": "image/jpeg",
      "size": 310000,
      "width": 1200,
      "height": 800
    }
  ]
}
```

--------------------------------

### Execute Migrations and Data Upload via Docker

Source: https://docs.revisium.io/migrations/ci-cd

Manual commands to run migrations or upload seed data using the Revisium CLI container.

```bash
# Apply migrations  
docker run --rm \
  -e REVISIUM_URL=revisium://cloud.revisium.io/myorg/myproject/master \
  -e REVISIUM_TOKEN=$TOKEN \
  -v ./revisium/migrations.json:/app/migrations.json \
  revisium/revisium-cli \
  revisium migrate apply --file /app/migrations.json --commit  
  
# Upload seed data  
docker run --rm \
  -e REVISIUM_URL=revisium://cloud.revisium.io/myorg/myproject/master \
  -e REVISIUM_TOKEN=$TOKEN \
  -v ./revisium/data:/app/data \
  revisium/revisium-cli \
  revisium rows upload --folder /app/data --commit  
```

--------------------------------

### Execute API Generation

Source: https://docs.revisium.io/guides/dictionary-service-nestjs

Runs the configured npm script to generate the typed API client.

```bash
npm run generate:faq-api
```

--------------------------------

### Configure Microservice Federation Environment Variables

Source: https://docs.revisium.io/apis/configuration

Enables Apollo Federation support for schema composition in a gateway.

```text
ENDPOINT_GRAPHQL_FEDERATION=true  
ENDPOINT_GRAPHQL_ADD_PROJECT_PREFIX=true  
```

--------------------------------

### Visualize branch creation

Source: https://docs.revisium.io/core-concepts/versioning

Conceptual representation of creating a new branch from an existing revision.

```text
master:  rev-1 → rev-2 → rev-3 (HEAD)  
                            ↓  
staging:                  rev-3 (HEAD) → Draft  
```

--------------------------------

### Initialize Manual MCP Session

Source: https://docs.revisium.io/auth-permissions/authentication

Initialize an MCP session for debugging purposes using a JSON-RPC request.

```bash
curl -X POST http://localhost:8080/mcp \  
  -H "Content-Type: application/json" \  
  -H "Accept: application/json, text/event-stream" \  
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'  

```

--------------------------------

### Patch Row Operations

Source: https://docs.revisium.io/apis/mcp

Examples of JSON Patch operations for updating row fields, including nested properties and array indices.

```json
{"op": "replace", "path": "title", "value": "New Title"}  
{"op": "replace", "path": "metadata.description", "value": "..."}  
{"op": "replace", "path": "items[0].name", "value": "Updated"}
```

--------------------------------

### Pagination with Filtering and Sorting

Source: https://docs.revisium.io/querying-data/pagination

Demonstrates how to combine pagination parameters with specific filtering and ordering criteria.

```graphql
query GetAvailableProducts($after: String) {  
  products(data: {  
    first: 20,  
    after: $after,  
    where: {  
      data: { path: ["inStock"], equals: true }  
    },  
    orderBy: [{ field: createdAt, direction: desc }]  
  }) {  
    edges {  
      node { data { name price } }  
      cursor  
    }  
    pageInfo { hasNextPage endCursor }  
    totalCount  
  }  
}  

```