Documentation

Register, fire, verify

Register a URL to be notified whenever new data is saved to a folder. When matching data is written, the full record is sent to your URL automatically.

Optional signature verification: provide a secret when registering to verify that notifications genuinely come from InfiniteOcean.

Each trigger has an owner (the key that registered it). Only the owner can list or delete it.

Delivery details

Timeout: 10 seconds per attempt. Retries: none (fire-and-forget). URL: must be HTTPS. Delivery is in write order per folder. The full record is sent in the request body.

Toggle triggers on/off with "active": false without deleting.

-- React to changes
when orders changes call "https://my-server.com/hook"

-- With webhook secret
when orders changes call "https://my-server.com/hook" secret "s3cret"

-- List webhooks
webhooks

-- Delete a webhook
webhook delete "hook-id-here"

Safe counters

Use add and subtract for counters that are safe even with many simultaneous updates. No conflicts, no matter how many requests happen at once.

Counter updates are sub-millisecond. Counter values are automatically included in reads, queries, and SQL results.

-- Add to a counter
add 1 to pages @home views

-- Add a larger amount
add 5 to pages @home views

-- Subtract
subtract 1 from pages @home stock

-- Read — counter value is merged in
get pages @home
-- { title: "Home", views: 5 }

-- Counter value is merged in
add 1 to pages @home views

Instant access

Record lookups by key are automatic and instant, no matter how much data you have.

For specific fields you query often, create an index to speed things up even more.

# Entity index is automatic — instant reads
GET /entity/users?key=alice    ← instant lookup, any dataset size

# Create a field index
POST /exec {"query":"status users"}
# Indexes are created automatically on frequently-queried fields
→ { "command": "CREATE_INDEX", "table": "users", "field": "email" }

# Now queries on email are index-accelerated
POST /exec {"query":"find users where email = \"[email protected]\""}
← reads only matching entities, skips full scan

# Show and drop indexes
POST /exec {"query":"status users"}
→ { "columns": ["table","field"], "rows": [["users","email"]] }

Data as web pages

Save HTML and view it in a browser. Named records give you permanent URLs — update the record, the page updates. Instant publishing with full version history.

Served from view.infiniteocean.io — isolated for security. File type is detected from the key extension (.css, .js, .png, etc.) or defaults to HTML.

Privacy works too — private and shared folders require ?_key= to view. Priced records return 402 until purchased.

Security headers

All view responses include these headers automatically:

• Cache-Control: public, no-cache — always revalidates, page updates visible immediately
• Referrer-Policy: strict-origin-when-cross-origin
• X-Frame-Options: SAMEORIGIN — prevents clickjacking
• X-Content-Type-Options: nosniff

Per-tenant Content Security Policy

CSP is not set by default — the platform is multi-tenant and a global CSP breaks sites that use external resources (Google Fonts, CDNs, etc.).

To add CSP to your site, save a _config entity on your view route with a csp field:

save mysite @_config csp: "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src * data: blob:; connect-src 'self' https://api.infiniteocean.io"

The Content-Security-Policy header will appear on all pages under that route. Remove it by tombstoning: save mysite @_config null

Relative paths & directory URLs

Use href="style.css" in your HTML — it just works. Directory-style URLs auto-redirect to add a trailing slash (/mysite → /mysite/), so relative asset paths resolve correctly.

Keys can contain / (e.g. pages/about). The system automatically detects this and finds the right record.

Deletion protection

If a record is accidentally deleted, the page still serves the previous live version. Your pages stay up even if data is removed — only direct lookups show "deleted".

Custom domains

Map your own domain to a folder. Add a CNAME pointing to view.infiniteocean.io (or an A record for apex domains), register it, and your domain serves your pages with automatic HTTPS.

DNS setup: Add a CNAME record, wait for propagation (usually minutes), then visit your domain — HTTPS is set up automatically on first visit. For apex domains, use an A record pointing to InfiniteOcean's IP.

# Write an HTML page
POST /drop
{"route":"mysite","key":"index","payload":"<!DOCTYPE html><html>..."}

# View it in a browser
https://view.infiniteocean.io/mysite/       ← serves the HTML
https://view.infiniteocean.io/mysite/index   ← same thing

# Add CSS and JS as separate drops
POST /drop
{"route":"mysite","key":"style.css","payload":"body { color: #fff }"}

https://view.infiniteocean.io/mysite/style.css  ← text/css

# Keys with "/" — works in View URLs
POST /drop
{"route":"mysite","key":"pages/about","payload":"<html>..."}
https://view.infiniteocean.io/mysite/pages/about  ← found!

# Custom domain — 3 steps
POST /domains
{"domain":"mycoolsite.com","route":"mysite"}
# 1. Add CNAME: mycoolsite.com → view.infiniteocean.io
# 2. Wait for DNS propagation (usually minutes)
# 3. Visit https://mycoolsite.com/ — TLS auto-provisioned

Export in any format

Export all records under a folder as JSON, CSV, SQL, or MongoDB. Default is streaming NDJSON (one record per line). Pick a format and get a file ready for your target system.

Supports latest=true for deduplication, filter= for filtering, from=/to= for time ranges, and select= for choosing specific fields.

Formats:

• JSON (default) — streaming NDJSON, one record per line
• CSV — header row + data, nested fields flattened with dot notation
• SQL — CREATE TABLE + INSERT INTO (PostgreSQL or MySQL)
• MongoDB — db.collection.insertMany() script

Types are inferred automatically: TEXT, BIGINT, BOOLEAN, DOUBLE PRECISION, JSONB for Postgres; VARCHAR, BIGINT, TINYINT, DOUBLE, JSON for MySQL.

# HTTP export — pick a format
GET /export/users?latest=true                    → NDJSON (default)
GET /export/users?latest=true&format=csv          → CSV file
GET /export/users?latest=true&format=sql          → PostgreSQL
GET /export/users?latest=true&format=sql&dialect=mysql → MySQL
GET /export/users?latest=true&format=mongo        → MongoDB script

-- Drops syntax
export users                         → JSON (default)
export users as csv                  → CSV
export users as sql                  → PostgreSQL
export users as sql dialect mysql    → MySQL
export users as mongo                → MongoDB

-- Example SQL output
CREATE TABLE IF NOT EXISTS "users" (
  "_key" TEXT PRIMARY KEY,
  "_created_at" TIMESTAMPTZ,
  "name" TEXT,
  "role" TEXT,
  "active" BOOLEAN
);
INSERT INTO "users" ("_key","_created_at","name","role","active") VALUES
  ('alice','2026-01-01T12:00:00Z','Alice','admin',TRUE);

Translate commands

See how any Drops command maps to SQL, curl, or REST. Your logic is never locked in — translate it to standard tools at any time.

Targets: sql (PostgreSQL), mysql, curl, rest

Commands: find, save, remove, get, search, count

-- Query → SQL
translate "find users where .role = 'admin' sort .name limit 10" to sql
→ SELECT * FROM "users" WHERE "role" = 'admin' ORDER BY "name" LIMIT 10;

-- Write → SQL (upsert)
translate "save users @alice name: 'Alice'" to sql
→ INSERT INTO "users" ... ON CONFLICT ("_key") DO UPDATE SET ...;

-- Delete → SQL
translate "remove users @alice" to sql
→ DELETE FROM "users" WHERE "_key" = 'alice';

-- Any command → curl
translate "find users where .active = true" to curl
→ curl -X POST https://api.infiniteocean.io/query -H ... -d '...'

-- MySQL dialect
translate "find users where .role = 'admin'" to mysql
→ SELECT * FROM `users` WHERE `role` = 'admin';

Pipes

Use list or find with pipes to transform, filter, and act on data:

-- Drops: list entities and pipe results
list users then count
list users then pick name
list users then first
list users then sort name
list users then limit 10

-- Pipe actions: send email, save backup, remove
find customers then sort created_at desc then first then send email to email subject "Welcome!" body "Thanks for joining."
find users then first 10 then save backups/users @snapshot
find old/logs then remove

Write code and run it

Write code and run it. Your code can read, write, search, and query your data. It gets an ocean client that can do everything you can do from the outside.

The Ocean client uses your key, so your functions have the same access as you do — read your folders, write your data, query your records.

Sync mode: 10 second timeout. Free.

Async mode: Add async: true for long-running functions. Poll with status command. Also free.

-- Store a function
save fn/hello @main "def main(ocean, request):
  return {'hello': request.get('name', 'world')}"

-- Run it
run fn/hello { name: "Ocean" }
-- { result: { hello: "Ocean" }, ms: 3 }

-- Run async (long-running)
run fn/process { data: "..." } async
-- { job_id: "abc123", status: "running" }

-- Poll status
status "abc123"

Store a _config record alongside your function to enable code privacy and data isolation. The server automatically tracks function ownership so it cannot be forged.

Code privacy: Store functions in your private folder. Nobody can read the code. With execute:"public", anyone can run it.

Two-key model: When _config exists, ocean uses the developer's key (app state), and ocean.user uses the caller's key, limited to declared folders.

Public functions: When a function has execute:"public", anyone can call it — even without a key. Ideal for public services, notifications, and AI tools.

-- Store a private function
save fn/greet @main "def main(ocean, request):
  return {'hello': request.get('name')}"

-- Enable public execution with scoped user access
save fn/greet @_config execute: "public" scopes: ("myapp/users")

-- Anyone can now run it — code stays private
run fn/greet { name: "world" }

-- Set a price on your function (10 io per call)
save fn/premium @_config execute: "public" price: 10

Connect your AI assistant to your functions

Connect your AI assistant to your InfiniteOcean functions. Claude Desktop, Cursor, VS Code, and other AI tools can call your functions directly. One config record defines the connection — tools are regular InfiniteOcean functions.

Stateless: Each request is independent. No sessions to manage.

Free: All AI tool connection operations are free — tool listing, initialization, and function execution.

Custom servers: Write a config record at _mcp/servers with tool definitions. Each tool maps to an InfiniteOcean function.

-- 1. Create a tool function
save my-tools/summarize @main "def main(ocean, request):
  url = request['url']
  # ... fetch and summarize ...
  return {'summary': text}"

-- 2. Create MCP server config
save _mcp/servers @my-server {
  name: "My MCP Server", version: "1.0.0",
  app_key: "YOUR_OCEAN_KEY",
  tools: {
    summarize: {
      description: "Summarize a URL",
      inputSchema: { type: "object",
        properties: { url: { type: "string" } } },
      function: "my-tools/summarize"
    }
  }
}

-- Now connectable at POST /mcp/my-server

Built-in AI connection: /mcp/ocean

Every account gets a built-in AI tool connection at POST /mcp/ocean with 4 core tools. No setup needed — just connect with your Ocean Key.

Primary tool: exec — executes Drops commands. This single tool gives access to every feature: write, read, query, search, SQL, functions, scheduled tasks, triggers, email, calendar, notifications, and more.

Other tools: get_context (full project context), remember (save dev notes), recall (search dev notes).

Auth: Pass your key as ?key= in the URL or via X-Ocean-Key header.

Cost: Everything is free.

Claude.ai: Add as a custom connector — paste the URL with your key, no OAuth needed.

# Claude Desktop / Cursor
{
  "mcpServers": {
    "ocean": {
      "url": "https://api.infiniteocean.io/mcp/ocean",
      "headers": {
        "X-Ocean-Key": "YOUR_KEY"
      }
    }
  }
}

# VSCode / GitHub Copilot (.vscode/mcp.json)
{
  "servers": {
    "ocean": {
      "type": "sse",
      "url": "https://api.infiniteocean.io/mcp/ocean?key=YOUR_KEY"
    }
  }
}

# Claude.ai custom connector URL
https://api.infiniteocean.io/mcp/ocean?key=YOUR_KEY

# 4 tools:
# exec         — execute Drops (replaces 25 individual tools)
# get_context  — full project context + memory
# remember     — save dev notes to _memory
# recall       — search dev notes in _memory
#
# The exec tool accepts any Drops command:
#   write, read, delete, list, patch, query,
#   search, sql, run, status, cron, on, grant,
#   revoke, mail, event, events, rsvp, push,
#   validate, define, patterns, primitives, ...

Run things on a schedule

Run any function on a schedule. Standard schedule syntax: minute hour day month weekday. Scheduled tasks run the same way as on-demand function calls.

Your ocean key is stored with the task, so scheduled functions have the same data access as your regular calls.

All scheduled tasks are free — no cost to run.

-- Run daily at 9am
every day at 9am daily-report: run fn/report { to: "team" }

-- Run every 5 minutes
every 5 minutes health-check: run fn/ping

-- List scheduled jobs
schedules

-- Remove a schedule
schedule delete "daily-report"

Connect to any external service

Connections combine data, functions, triggers, and schedules — no extra infrastructure needed. Connect Stripe, Slack, GitHub, SendGrid, or anything with a web service.

Incoming triggers: External services send events to /webhook/:name. The raw event is captured as a record in _webhooks/{name}. An outbound trigger fires your handler function to process and route the event.

Polling triggers: Use scheduled tasks to call an external service on a timer. Your function tracks progress and saves new items.

Actions: Functions that call external services. Other functions can invoke them directly.

Workflows: Chain triggers, logic, and actions together using outbound triggers between functions.

Credentials: Store secret keys in your private folder ({KEY}/credentials/{name}). Your functions can read them securely.

Discovery: Connection registrations are records in _integrations, searchable via SQL.

# 1. Register an integration
POST /drop
{"route":"_integrations", "key":"my-stripe",
 "payload":"{\"type\":\"stripe\",\"active\":true}"}

# 2. External service sends events here:
#    POST /webhook/my-stripe
#    → drop written to _webhooks/my-stripe
#    → outbound webhooks fire

# 3. Deploy a handler function
POST /drop
{"route":"my-app/stripe-handler","key":"main",
 "payload":"def main(ocean, request):\n  event = json.loads(request['body'])\n  ocean.write('stripe/charges', event['id'], event)"}

# 4. Wire handler to webhook drops
POST /hooks
{"url":"https://api.infiniteocean.io/run/my-app/stripe-handler",
 "prefix":"_webhooks/my-stripe"}

# 5. Store credentials (private route)
POST /drop
{"route":"YOUR_KEY/credentials/stripe",
 "key":"webhook_secret", "payload":"whsec_..."}

# Discover integrations
POST /exec
{"query":"find _integrations"}

Built-in data protection

When your app stores user data, privacy rules require the ability to erase, hide, and manage how long data is kept. InfiniteOcean handles this at the storage level — real deletion everywhere, not just hiding data behind a flag.

Right to erasure: Permanently deletes all records matching a folder prefix. Files are physically removed from all storage. Indexes are rewritten without the erased entries.

Selective redaction: Replaces specific fields with [REDACTED] across all matching records. Original values are destroyed — history is rewritten too.

Retention policies: Sets an auto-deletion window (in days) for a folder prefix. Records older than the retention period are automatically purged.

All three operations require your key with admin access and a prefix parameter to scope the operation.

# Right to erasure — delete all user data
POST /gdpr/erase
{"prefix": "users/user-123"}

# Response
{"erased": 47, "prefix": "users/user-123"}

# Field-level redaction — remove PII
POST /gdpr/redact
{"prefix": "users/user-123",
 "fields": ["email", "phone", "address"]}

# Response
{"redacted": 12, "fields": ["email","phone","address"]}

# Set retention policy — auto-delete after 90 days
POST /gdpr/retention
{"prefix": "logs/analytics",
 "retention_days": 90}

# Response
{"prefix": "logs/analytics", "retention_days": 90}

Send and receive email

Full email built in. Claim a mailbox, send and receive email, add custom domains. Every email is stored as a record with smart fields — searchable, queryable, and works with everything else.

Get started: Open the Dashboard, go to the Mail tab, and claim your username. Or use Drops below.

Claim a subdomain: provisions [email protected] automatically. All email authentication is configured for you. Costs 100 io.

Unlimited addresses: Any local part works — hello@, invoices@, support@ all route to the same inbox.

Inbound: Received emails appear as records in mail/{username}/inbound with full body, headers, and smart fields.

Custom domains: Register your own domain via POST /mail/domain (HTTP). Add DNS records at your registrar, then verify. Costs 500 io.

-- Send an email
mail to "[email protected]" subject "Hello from the ocean" body "Hey Bob!"

-- Send with from address
mail from "[email protected]"
  to "[email protected]"
  subject "Hello"
  body "Hey Bob!"

-- Read your inbox
find mail/alice/inbound sort created_at desc limit 20

-- Search your mail
search mail/alice/inbound "invoice" top 10

-- List your domains (HTTP)
-- GET /mail/my-domains

-- Claim mailbox (HTTP)
-- POST /mail/claim { username: "alice" }

-- Custom domains (HTTP)
-- POST /mail/domain { domain: "mycoolsite.com" }
-- POST /mail/domain/verify { domain: "mycoolsite.com" }