Query API

Run an original Obelisk query script over HTTP. The successful response is the script's JSON result, without additional business fields.

Endpoint

POST https://cloud.obelisk.antinomie.org/query

Authentication

Send a personal API key, a Bearer access token from an authorized beta native client, or an OAuth application token issued for the exact https://cloud.obelisk.antinomie.org/query resource with history:query scope. Browser login cookies cannot authenticate this endpoint. Send only one authentication method.

For OAuth integration, discover Query resource metadata and authorization server metadata. Register your client, complete browser consent with PKCE S256, and exchange the authorization code. Tokens issued for /mcp cannot be used here.

Create a personal API key in your Console and use it as the Bearer token below. Keys work with both Query API and MCP, expire after 90 days and can be revoked in Console.

Request example

export OBELISK_ACCESS_TOKEN='<your access token>'
curl 'https://cloud.obelisk.antinomie.org/query' \
  -H "Authorization: Bearer $OBELISK_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"script":"return sessions({limit: 10});","context":{"cwd":"/work/example-project","invokingSessionId":null}}'

script uses the same synchronous helpers as local Obelisk, including sessions(), sql() and raw(). context.cwd is required: use the original project path. It supplies query context, not a server directory to scan. invokingSessionId is optional; null means unknown. Neither field selects the account or workspace.

Response

The body is exactly the script's JSON result. X-Obelisk-Generation identifies the published history version used. Responses are not cached.

Common errors

• 400: Invalid request or query. Read the returned error string.
• 401: Missing, expired or invalid credentials. Complete authorization or refresh the token.
• 405: Wrong HTTP method. Use POST; a browser address-bar request uses GET.
• 409: No published history yet. Complete synchronization first.
• 503: The service is not configured or is temporarily unavailable.

Beta limits

Sync your history before querying. Accounts without a published index receive HTTP 409. Session history and original records are supported; the separate memory stream is not synchronized. Empty memory results do not mean you have no local memories.

Requests are limited to 64 KiB and responses to 1 MiB, with a five-second execution timeout. Full query parity, Windows paths, cancellation and individual Agent client compatibility remain under verification.

Existing CLI queries continue to run locally. This HTTP API does not change CLI defaults.