Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ocient.com/llms.txt

Use this file to discover all available pages before exploring further.

The provides an HTTP Query API that enables the execution of SQL statements. This page uses command-line examples using curl. The HTTP Query API returns data in JSON format by default. The default header value is Accept: application/json.

​
API Documentation

The API follows OpenAPI Specification () guidelines, which you can access in these formats from any SQL Node address {sql_node_address}:
  • YAML format: /openapi.yaml endpoint
  • JSON format: /openapi.json endpoint
YAML Download Example
CURL
curl https://{sql_node_address}/openapi.yaml
JSON Download Example
CURL
curl https://{sql_node_address}/openapi.json
You can use these specifications with various OpenAPI tools for code generation, testing, and documentation.

​
Connection Setup

Before using the API, you must establish an open port for a SQL Node. The connectivity pool defines connection settings for SQL Nodes, including their open port and address. For details, see CONNECTIVITY POOL.
All the examples assume that the openapi_port is the standard SSL port 443. If your connectivity pool openapi_port has a different port setting, you must specify it in the request URL. For example, this URL specifies using port 8443: https://sql_node_address:8443/v1/execute/.
Enable the OpenAPI Port To open a port, execute this ALTER CONNECTIVITY POOL SQL statement on a connectivity pool in your system. Change the connectivity pool and node values in the example according to your system.
SQL
ALTER CONNECTIVITY_POOL benchmark_sql_connectivity_pool
    ALTER PARTICIPANT "benchmark-sql0" SET openapi_port 443;

​
Check Port Configuration

Verify your port configuration by executing this query.
SQL
SELECT c.name, n.name, openapi_port
    FROM sys.connectivity_pool_participants AS cp
    LEFT JOIN sys.connectivity_pools AS c ON cp.id = c.id
    LEFT JOIN sys.nodes AS n ON cp.node_id = n.id;
The output displays all configured connectivity pools with their associated nodes and OpenAPI ports.

​
SSL Certificate Setup

The HTTP Query API supports two options for handling SSL certificates. Secure Connection Using TLS You can use your own certificates for TLS-secured connections by configuring certificate files in your Ocient install. For details, see Secure Connections Using TLS. Unsecured Connection For quick testing or in non-production environments, you can bypass certificate validation by adding the -k or --insecure flag to your curl command. Example
SQL
curl -k -u 'admin@system:admin' https://<sql-node-address>/v1/execute/system \
    -d '{"statement":"SELECT * FROM sys.dummy2;","format":"collection"}'

​
Authentication Methods

The Ocient HTTP Query API accepts user credentials in various formats designed for different use cases. Simple API Requests For simple queries, you can include user credentials in the request. In this example, the request includes credentials after the -u flag.
CURL
curl -u 'admin@system:admin' https://sql_node/v1/execute/system \
    -d '{"statement":"SELECT * FROM sys.dummy2;", "format": "collection"}'
Bearer Token Authentication For continuous access, you can obtain an authentication token by making a request to the login endpoint. Replace the text in this example with the address of your SQL Node, your username, your password, and the name of your database.
CURL
curl -X POST https://sql_node/v1/login \
    -H "Content-Type: application/json" \
    -d '{
        "username": "admin@system",
        "password": "admin",
        "database": "system"
    }'
This request returns an authentication token that you can add to subsequent requests.
CURL
curl -X POST https://sql_node/v1/execute \
    -H "Authorization: Bearer TEST_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "statement": "SELECT * FROM sys.dummy2;",
        "database": "system",
        "format": "collection"
    }'
OpenID Connect (SSO) For SSO authentication, you can use OpenID Connect by targeting the sso_authentication endpoint with a callback path. Replace the text in this example with the name of your instance, the name of your database, and your callback path.
CURL
curl -X POST https://ocient-instance/v1/sso_authentication \
    -H "Content-Type: application/json" \
    -d '{
        "database": "system",
        "sso_callback_path": "/app_callback"
    }'
After the redirection and authentication are complete, you can include your token in subsequent requests.
CURL
curl -X POST https://ocient-instance/v1/sso_token \
    -H "Content-Type: application/json" \
    -d '{
        "id_token": "TEST_ID_TOKEN",
        "database": "system"
    }'

​
API Endpoint Documentation

The Ocient HTTP Query API supports these endpoints. For API requests, JSON data must use double quotes (") for all keys and string values. Single quotes should enclose the JSON payload, as shown in this example (see the payload section following the -d flag).
CURL
curl -X POST \
    https://my_sql_node.com/v1/execute \
    -H "Content-Type: application/json" \
    -d '{ "query": "SELECT * FROM my_table WHERE status = \"active\"", "database": "my_database" }'
Single or double quotes are acceptable for parameters not nested in JSON objects.

​
Endpoints

POST execute

GET execute

GET info

POST login

POST logout

POST sso_authentication

GET callback

POST sso_token

POST sso_device_grant

POST sso_device_grant_verify

POST token_refresh

Swagger General SQL Syntax
Last modified on May 27, 2026