API v1

The NatureQuery REST API.

Programmatic access to NatureQuery. Execute SQL queries, generate SQL from natural language, and manage your saved queries and connections.

Get an API key

Authentication

All API requests require a Bearer token in the Authorization header. Generate an API key from the Settings → API Keys tab.

Authorization Header

Authorization: Bearer nq_your_api_key_here

Security: API keys are hashed with SHA-256 before storage. The plaintext key is only shown once at creation. Treat it like a password.

Rate Limits

API requests are limited to 60 requests per minute per API key. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

429 Response

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Response Format

All responses use a consistent JSON envelope:

Success

{
  "success": true,
  "data": { ... }
}

Paginated

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 142,
    "totalPages": 3
  }
}

Error

{
  "success": false,
  "error": "Description of what went wrong"
}

List Connections

Returns all database connections for your account. Passwords are never included.

GET/api/v1/connections

Example request

curl https://www.naturequery.app/api/v1/connections \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "name": "Production DB",
      "host": "db.example.com",
      "port": 5432,
      "database": "myapp",
      "user": "readonly",
      "dbType": "postgresql",
      "ssl": true,
      "isActive": true,
      "createdAt": "2026-02-10T12:00:00.000Z"
    }
  ]
}

List Saved Queries

Paginated list of saved queries. Includes team-shared queries.

GET/api/v1/queries

Query parameters

page

number

Page number (default: 1)

pageSize

number

Items per page, max 100 (default: 50)

search

string

Filter by name or question text

connectionId

string

Filter by connection ID

Example request

curl "https://www.naturequery.app/api/v1/queries?page=1&pageSize=10" \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "name": "Monthly Revenue",
      "question": "total revenue by month",
      "sql": "SELECT ... FROM orders ...",
      "connectionId": "cm...",
      "connectionName": "Production DB",
      "isPublic": false,
      "isFavorite": true,
      "tags": ["finance", "monthly"],
      "shareToken": null,
      "createdAt": "2026-02-10T12:00:00.000Z",
      "updatedAt": "2026-02-12T08:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 24,
    "totalPages": 3
  }
}

Save a Query

Create a new saved query.

POST/api/v1/queries

Request body

namerequired

string

Display name for the query

questionrequired

string

The natural language question

sqlrequired

string

The SQL query

description

string

Optional description

connectionId

string

ID of the associated connection

connectionName

string

Display name of the connection

tags

string[]

Array of tag strings

isPublic

boolean

Whether the query is publicly visible (default: false)

Example request

curl -X POST https://www.naturequery.app/api/v1/queries \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT DATE_TRUNC('"'"'month'"'"', created_at) AS month, SUM(amount) FROM orders GROUP BY 1",
    "tags": ["finance"]
  }'

Example response

{
  "success": true,
  "data": {
    "id": "cm...",
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT ...",
    "connectionId": null,
    "connectionName": null,
    "isPublic": false,
    "isFavorite": false,
    "tags": ["finance"],
    "shareToken": null,
    "createdAt": "2026-02-13T10:00:00.000Z",
    "updatedAt": "2026-02-13T10:00:00.000Z"
  }
}

Get Query by ID

Fetch a single saved query. Must be owned by you or shared via a team.

GET/api/v1/queries/:id

Parameters

idrequired

string

The query ID (path parameter)

Example request

curl https://www.naturequery.app/api/v1/queries/cm_query_id \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": {
    "id": "cm_query_id",
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT ...",
    "connectionId": "cm...",
    "connectionName": "Production DB",
    "isPublic": false,
    "isFavorite": true,
    "tags": ["finance"],
    "shareToken": null,
    "createdAt": "2026-02-10T12:00:00.000Z",
    "updatedAt": "2026-02-12T08:30:00.000Z"
  }
}

Execute SQL

Run a SQL query against one of your saved connections. Subject to plan limits.

POST/api/v1/query/execute

Request body

connectionIdrequired

string

ID of the connection to query

sqlrequired

string

SQL statement to execute

Example request

curl -X POST https://www.naturequery.app/api/v1/query/execute \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "cm_connection_id",
    "sql": "SELECT id, name, email FROM users LIMIT 5"
  }'

Example response

{
  "success": true,
  "data": {
    "rows": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ],
    "fields": [
      { "name": "id", "dataType": "int4" },
      { "name": "name", "dataType": "varchar" },
      { "name": "email", "dataType": "varchar" }
    ],
    "rowCount": 2,
    "executionTime": 45
  }
}

Generate SQL

Convert a natural language question into SQL using AI, based on your connection's schema.

POST/api/v1/query/generate

Request body

questionrequired

string

Natural language question

connectionIdrequired

string

ID of the connection (for schema context)

Example request

curl -X POST https://www.naturequery.app/api/v1/query/generate \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "top 10 customers by total revenue",
    "connectionId": "cm_connection_id"
  }'

Example response

{
  "success": true,
  "data": {
    "question": "top 10 customers by total revenue",
    "sql": "SELECT c.name, SUM(o.amount) AS total_revenue FROM customers c JOIN orders o ON o.customer_id = c.id GROUP BY c.name ORDER BY total_revenue DESC LIMIT 10",
    "connectionId": "cm_connection_id"
  }
}

Query History

Paginated list of previously executed queries with status and timing info.

GET/api/v1/history

Query parameters

page

number

Page number (default: 1)

pageSize

number

Items per page, max 100 (default: 50)

connectionId

string

Filter by connection ID

status

string

Filter by status: success, error

search

string

Search in question or SQL text

Example request

curl "https://www.naturequery.app/api/v1/history?page=1&pageSize=10&status=success" \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "question": "total revenue by month",
      "sql": "SELECT ...",
      "connectionId": "cm...",
      "connectionName": "Production DB",
      "status": "success",
      "rowCount": 12,
      "executionTimeMs": 45,
      "errorMessage": null,
      "executedAt": "2026-02-13T09:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 87,
    "totalPages": 9
  }
}

Error codes

Status	Meaning
`400`	Bad request: invalid JSON or failed validation
`401`	Unauthorized: missing, invalid, or expired API key
`403`	Forbidden: plan limit reached (upgrade to continue)
`404`	Not found: resource doesn't exist or you don't have access
`429`	Too many requests: rate limit exceeded, check Retry-After header
`500`	Internal server error

Questions about the API?

Manage API keys Contact us

API v1

The NatureQuery REST API.

Programmatic access to NatureQuery. Execute SQL queries, generate SQL from natural language, and manage your saved queries and connections.

Get an API key

Authentication

All API requests require a Bearer token in the Authorization header. Generate an API key from the Settings → API Keys tab.

Authorization Header

Authorization: Bearer nq_your_api_key_here

Security: API keys are hashed with SHA-256 before storage. The plaintext key is only shown once at creation. Treat it like a password.

Rate Limits

API requests are limited to 60 requests per minute per API key. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

429 Response

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Response Format

All responses use a consistent JSON envelope:

Success

{
  "success": true,
  "data": { ... }
}

Paginated

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 142,
    "totalPages": 3
  }
}

Error

{
  "success": false,
  "error": "Description of what went wrong"
}

List Connections

Returns all database connections for your account. Passwords are never included.

GET/api/v1/connections

Example request

curl https://www.naturequery.app/api/v1/connections \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "name": "Production DB",
      "host": "db.example.com",
      "port": 5432,
      "database": "myapp",
      "user": "readonly",
      "dbType": "postgresql",
      "ssl": true,
      "isActive": true,
      "createdAt": "2026-02-10T12:00:00.000Z"
    }
  ]
}

List Saved Queries

Paginated list of saved queries. Includes team-shared queries.

GET/api/v1/queries

Query parameters

page

number

Page number (default: 1)

pageSize

number

Items per page, max 100 (default: 50)

search

string

Filter by name or question text

connectionId

string

Filter by connection ID

Example request

curl "https://www.naturequery.app/api/v1/queries?page=1&pageSize=10" \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "name": "Monthly Revenue",
      "question": "total revenue by month",
      "sql": "SELECT ... FROM orders ...",
      "connectionId": "cm...",
      "connectionName": "Production DB",
      "isPublic": false,
      "isFavorite": true,
      "tags": ["finance", "monthly"],
      "shareToken": null,
      "createdAt": "2026-02-10T12:00:00.000Z",
      "updatedAt": "2026-02-12T08:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 24,
    "totalPages": 3
  }
}

Save a Query

Create a new saved query.

POST/api/v1/queries

Request body

namerequired

string

Display name for the query

questionrequired

string

The natural language question

sqlrequired

string

The SQL query

description

string

Optional description

connectionId

string

ID of the associated connection

connectionName

string

Display name of the connection

tags

string[]

Array of tag strings

isPublic

boolean

Whether the query is publicly visible (default: false)

Example request

curl -X POST https://www.naturequery.app/api/v1/queries \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT DATE_TRUNC('"'"'month'"'"', created_at) AS month, SUM(amount) FROM orders GROUP BY 1",
    "tags": ["finance"]
  }'

Example response

{
  "success": true,
  "data": {
    "id": "cm...",
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT ...",
    "connectionId": null,
    "connectionName": null,
    "isPublic": false,
    "isFavorite": false,
    "tags": ["finance"],
    "shareToken": null,
    "createdAt": "2026-02-13T10:00:00.000Z",
    "updatedAt": "2026-02-13T10:00:00.000Z"
  }
}

Get Query by ID

Fetch a single saved query. Must be owned by you or shared via a team.

GET/api/v1/queries/:id

Parameters

idrequired

string

The query ID (path parameter)

Example request

curl https://www.naturequery.app/api/v1/queries/cm_query_id \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": {
    "id": "cm_query_id",
    "name": "Monthly Revenue",
    "question": "total revenue by month",
    "sql": "SELECT ...",
    "connectionId": "cm...",
    "connectionName": "Production DB",
    "isPublic": false,
    "isFavorite": true,
    "tags": ["finance"],
    "shareToken": null,
    "createdAt": "2026-02-10T12:00:00.000Z",
    "updatedAt": "2026-02-12T08:30:00.000Z"
  }
}

Execute SQL

Run a SQL query against one of your saved connections. Subject to plan limits.

POST/api/v1/query/execute

Request body

connectionIdrequired

string

ID of the connection to query

sqlrequired

string

SQL statement to execute

Example request

curl -X POST https://www.naturequery.app/api/v1/query/execute \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "cm_connection_id",
    "sql": "SELECT id, name, email FROM users LIMIT 5"
  }'

Example response

{
  "success": true,
  "data": {
    "rows": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ],
    "fields": [
      { "name": "id", "dataType": "int4" },
      { "name": "name", "dataType": "varchar" },
      { "name": "email", "dataType": "varchar" }
    ],
    "rowCount": 2,
    "executionTime": 45
  }
}

Generate SQL

Convert a natural language question into SQL using AI, based on your connection's schema.

POST/api/v1/query/generate

Request body

questionrequired

string

Natural language question

connectionIdrequired

string

ID of the connection (for schema context)

Example request

curl -X POST https://www.naturequery.app/api/v1/query/generate \
  -H "Authorization: Bearer nq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "top 10 customers by total revenue",
    "connectionId": "cm_connection_id"
  }'

Example response

{
  "success": true,
  "data": {
    "question": "top 10 customers by total revenue",
    "sql": "SELECT c.name, SUM(o.amount) AS total_revenue FROM customers c JOIN orders o ON o.customer_id = c.id GROUP BY c.name ORDER BY total_revenue DESC LIMIT 10",
    "connectionId": "cm_connection_id"
  }
}

Query History

Paginated list of previously executed queries with status and timing info.

GET/api/v1/history

Query parameters

page

number

Page number (default: 1)

pageSize

number

Items per page, max 100 (default: 50)

connectionId

string

Filter by connection ID

status

string

Filter by status: success, error

search

string

Search in question or SQL text

Example request

curl "https://www.naturequery.app/api/v1/history?page=1&pageSize=10&status=success" \
  -H "Authorization: Bearer nq_your_key"

Example response

{
  "success": true,
  "data": [
    {
      "id": "cm...",
      "question": "total revenue by month",
      "sql": "SELECT ...",
      "connectionId": "cm...",
      "connectionName": "Production DB",
      "status": "success",
      "rowCount": 12,
      "executionTimeMs": 45,
      "errorMessage": null,
      "executedAt": "2026-02-13T09:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 87,
    "totalPages": 9
  }
}

Error codes

Status	Meaning
`400`	Bad request: invalid JSON or failed validation
`401`	Unauthorized: missing, invalid, or expired API key
`403`	Forbidden: plan limit reached (upgrade to continue)
`404`	Not found: resource doesn't exist or you don't have access
`429`	Too many requests: rate limit exceeded, check Retry-After header
`500`	Internal server error

Questions about the API?

Manage API keys Contact us