API Reference
All OQL execution goes through a single HTTPS endpoint. Authenticate with your Ocalt credentials (the username and password you use at accounts.ocalt.com). No API key setup — your Ocalt account is the key.
POST /v1/query — execute a query
{
"auth": {
"username": "your_ocalt_username_or_email_or_phone",
"password": "your_ocalt_password"
},
"query": "EMIT \"Hello\"", /* required */
"mode": "sync", /* "sync" (default) | "async" */
"request": { /* optional — injected as !REQUEST() in site mode */
"path": "/api/data",
"method": "GET",
"header:x-custom": "value"
},
"options": {
"webhook": "https://..." /* async only — called on completion */
}
}
Auth note: The username field accepts your Ocalt username, email address, or phone number — whichever you prefer. Use your accounts.ocalt.com password. There is no separate API key. The token field only applies to the browser-based Live Editor.
Sync response (200)
{
"status": "ok",
"job_id": "uuid",
"result": "Hello",
"trace": [
{ "step": "EMIT", "status": "Ok", "duration_ms": 0, "exec_class": "Cpu" }
]
}
Async response (202)
{
"status": "accepted",
"job_id": "uuid",
"poll_url": "https://oql.ocalt.com/v1/job/uuid"
}
GET /v1/job/{id} — poll async job
{
"status": "complete",
"job_id": "uuid",
"result": "...",
"trace": [...]
}
POST /v1/confirm/{id} — resume GATHER or CONFIRM
{
"approved": true, /* CONFIRM flow — true or false */
"fields": { /* GATHER flow — submitted form values */
"name": "Alice",
"email": "alice@example.com"
}
}
GET /files/{token} — public file download
Files shared with SHARE "/root/path" SET ?url are accessible at https://ocalt.com/files/{token}. Tokens are single-use by default.
API domain whitelist
If your OQL account has a domain whitelist configured at accounts.ocalt.com, any request from an unlisted Origin header receives a 403. Requests with no Origin header (server-to-server) bypass the check.
JavaScript — browser (no credentials)
In the browser, never include your password. Instead configure a domain whitelist at accounts.ocalt.com — requests from whitelisted origins are authenticated by domain, not by credential.
async function oql(query, request = {}) {
const resp = await fetch('https://oql.ocalt.com/v1/query', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, request })
});
return resp.json();
}
const r = await oql('EMIT "Hello"');
console.log(r.result); // "Hello"
JavaScript — server-side (Node.js, with credentials)
Server-to-server calls authenticate with your Ocalt username/email/phone and password. Credentials never touch the browser.
async function oql(query, request = {}) {
const resp = await fetch('https://oql.ocalt.com/v1/query', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
auth: { username: 'username_or_email_or_phone', password: 'your_ocalt_password' },
query,
request,
})
});
return resp.json();
}
const r = await oql('EMIT "Hello"');
console.log(r.result); // "Hello"
Python example
import requests
def oql(query, request={}):
resp = requests.post('https://oql.ocalt.com/v1/query', json={
'auth': {'username': 'username_or_email_or_phone', 'password': 'your_ocalt_password'},
'query': query,
'request': request,
})
return resp.json()
r = oql('EMIT "Hello"')
print(r['result']) # Hello
cURL example
curl -X POST https://oql.ocalt.com/v1/query \
-H "Content-Type: application/json" \
-d '{
"auth": {"username":"username_or_email_or_phone","password":"your_ocalt_password"},
"query": "EMIT \"Hello\""
}'
Development / test account
To try the API without an Ocalt account, use the hardcoded development bypass:
{
"auth": { "username": "test", "password": "test" },
"query": "EMIT \"Hello\""
}
The test account has a free tier namespace (user_test) and is shared. Do not store sensitive data in it.
