> ## 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.

# Ocient HTTP Query API

export const Swagger = "Swagger®";

export const OcientDataIntelligencePlatform = "OcientAIQ™ Unified Data Platform";

export const Ocient = "Ocient®";

The {OcientDataIntelligencePlatform} 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 ({Swagger}) 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 theme={null}
curl https://{sql_node_address}/openapi.yaml
```

**JSON Download Example**

```curl CURL theme={null}
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](/cluster-and-node-management#connectivity-pool).

<Info>
  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/`.
</Info>

**Enable the OpenAPI Port**

To open a port, execute this [ALTER CONNECTIVITY POOL](/cluster-and-node-management#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 SQL theme={null}
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 SQL theme={null}
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 {Ocient} 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](/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 SQL theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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

<Columns cols={2}>
  <Card title="POST execute" href="/api-playgrounds/ocient-http-query-api/post-execute" />

  <Card title="GET execute" href="/api-playgrounds/ocient-http-query-api/get-execute" />

  <Card title="GET info" href="/api-playgrounds/ocient-http-query-api/get-info" />

  <Card title="POST login" href="/api-playgrounds/ocient-http-query-api/post-login" />

  <Card title="POST logout" href="/api-playgrounds/ocient-http-query-api/post-logout" />

  <Card title="POST sso_authentication" href="/api-playgrounds/ocient-http-query-api/post-sso-authentication" />

  <Card title="GET callback" href="/api-playgrounds/ocient-http-query-api/get-callback" />

  <Card title="POST sso_token" href="/api-playgrounds/ocient-http-query-api/post-sso-token" />

  <Card title="POST sso_device_grant" href="/api-playgrounds/ocient-http-query-api/post-sso-device-grant" />

  <Card title="POST sso_device_grant_verify" href="/api-playgrounds/ocient-http-query-api/post-sso-device-grant-verify" />

  <Card title="POST token_refresh" href="/api-playgrounds/ocient-http-query-api/post-token-refresh" />
</Columns>

### Related Links

[Swagger](https://swagger.io/specification/)

[Data Query Language (DQL) Statement Reference](/data-query-language-dql-statement-reference)