REST API

Use the HTTPS query endpoint provided for your organization; https://query.example.com below is a placeholder. HTTP API access from outside Studio isn't self-service yet; email support@gnok.io to request it. Use Studio for organization administration.

The HTTP REST API provides a JSON-based interface for query execution and table browsing.

Base URL

https://query.example.com

Endpoints

POST /api/query

Execute a SQL query.

Request:

{
  "sql": "SELECT * FROM orders LIMIT 10",
  "timeout_ms": 30000
}

Response:

{
  "columns": ["order_id", "customer_id", "amount"],
  "types": ["BIGINT", "BIGINT", "DECIMAL(10,2)"],
  "rows": [
    [1, 100, "99.99"],
    [2, 101, "249.50"]
  ],
  "row_count": 2,
  "elapsed_ms": 42
}

GET /api/tables

List tables in the current catalog.

Response:

{
  "tables": [
    {"catalog": "default", "schema": "public", "name": "orders"},
    {"catalog": "default", "schema": "public", "name": "customers"}
  ]
}

GET /api/catalogs/:catalog/namespaces/:namespace/tables/:table

Get table metadata.

Response:

{
  "name": "orders",
  "schema": {
    "fields": [
      {"name": "order_id", "type": "BIGINT", "nullable": false},
      {"name": "amount", "type": "DECIMAL(10,2)", "nullable": true}
    ]
  },
  "partition_spec": ["region", "month(order_date)"],
  "snapshot_count": 42,
  "record_count": 1500000
}

Stage Endpoints (COPY INTO)

Endpoint	Description
POST /v1/stages/presign	Generate S3 presigned URLs for file upload
POST /v1/stages/presign/multipart/init	Initialize multipart upload
POST /v1/stages/presign/multipart/complete	Complete multipart upload
POST /v1/stages/presign/multipart/abort	Abort multipart upload

Authentication

All endpoints accept a JWT bearer token. Gnok support explains how to obtain tokens when your client connectivity is set up:

Authorization: Bearer <token>

Error Responses

{
  "error": "SYNTAX_ERROR",
  "message": "Expected SELECT, INSERT, UPDATE, or DELETE",
  "sql_state": "42601"
}