Convert a structured saved query to editable PostgreSQL

POST

/api/v1/bi/saved-queries/{id}/convert-to-sql

curl --request POST \
  --url https://api.justcrawl.io/api/v1/bi/saved-queries/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/convert-to-sql \
  --header 'Authorization: Bearer <token>'

• Production

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

Server-rendered literal SQL retaining the saved scope

Media typeapplication/json

object

sql

required

string

sqlDialect

required

string

Allowed values: postgres

scopeKind

required

string

Allowed values: org agent

scopeAgentId

required

string format: uuid

nullable

Example

{
  "sqlDialect": "postgres",
  "scopeKind": "org"
}

401

Missing or invalid authentication token

Media typeapplication/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

Access to the BI surface itself is refused. no_org and feature_disabled fire on every BI route from the mount guard, before any handler runs — feature_disabled is the first response most new integrations see, because the SQL console is entitled per organization. Permission and verified-email gates use insufficient_permissions and email_not_verified; rls_denied and kill_switched come from the engine. This response never describes resource-level authorization: an id you do not own returns 404, not 403.

Media typeapplication/json

object

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.

string

docs_url

required

Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

error

required

object

code

string

Allowed values: no_org feature_disabled insufficient_permissions email_not_verified authentication_required user_not_found rls_denied kill_switched

Example

{
  "error": {
    "code": "feature_disabled",
    "message": "SQL console is not enabled for this organization",
    "docs_url": "https://docs.justcrawl.io/guides/errors/bi",
    "request_id": "req_9f3a1c7e2b40"
  }
}

404

Not found, or not owned by your organization. The two are deliberately indistinguishable so cross-tenant existence cannot be probed

Media typeapplication/json

Error envelope returned by every /api/v1/bi/* handler error. Unlike the rest of the API — where the structured shape is opt-in via the application/vnd.justcrawl.v1+json media type — a BI handler always emits it, and all four fields are always present. The one exception: 401s from missing or invalid auth are rejected by shared middleware before any BI handler runs, so they carry the flat { "error": "<message>" } shape (Error schema) instead — see the Unauthorized response on each operation.

object

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.

string

docs_url

required

Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Query not found",
    "docs_url": "https://docs.justcrawl.io/guides/errors/not_found",
    "request_id": "req_9f3a1c7e2b40"
  }
}

409

The saved query is already SQL, or its definition no longer resolves (not_structured, conversion_unavailable)

Media typeapplication/json

object

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.

string

docs_url

required

Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

error

required

object

code

string

Allowed values: not_structured conversion_unavailable

Example

{
  "error": {
    "code": "not_structured"
  }
}

500

Unexpected server error. Full detail goes to the logs and PostHog $exception capture, never the response

Media typeapplication/json

Error envelope returned by every /api/v1/bi/* handler error. Unlike the rest of the API — where the structured shape is opt-in via the application/vnd.justcrawl.v1+json media type — a BI handler always emits it, and all four fields are always present. The one exception: 401s from missing or invalid auth are rejected by shared middleware before any BI handler runs, so they carry the flat { "error": "<message>" } shape (Error schema) instead — see the Unauthorized response on each operation.

object

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.

string

docs_url

required

Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

Example

{
  "error": {
    "code": "internal_error",
    "message": "Failed to list queries",
    "docs_url": "https://docs.justcrawl.io/guides/errors/internal_error",
    "request_id": "req_9f3a1c7e2b40"
  }
}