---
title: "Execute a raw SQL query"
method: POST
path: "/api/db/{project_id}/sql"
tags: ["Database"]
---

# Execute a raw SQL query

`POST /api/db/{project_id}/sql`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/db/{project_id}/sql`
- Auth: HTTP bearer

Execute a raw SQL query against the project's SQLite database. Use positional parameters (`params` or `args`) to avoid injection. Accepts `params`, `args`, or `named_args` interchangeably.
Use `?` placeholders in the query when using `params`/`args`.
The statement is executed verbatim against the underlying database, with no keyword filtering. Requires a service credential (secret key).

## Path parameters

- `project_id` string, required

## Request body

- SqlRequest
  - `query` string, required: SQL query to execute (use $1, $2, etc. for parameters)
  - `params` union[]: Query parameters in order
    - union
      - string
      - number
      - boolean

## Response `200`

Query executed successfully

- SqlResponse
  - `rows` object[]: Query result rows
  - `columns` string[]: Column names
  - `rowCount` integer: Number of rows returned/affected
  - `executionTime` number: Query execution time in milliseconds

## Other responses

- `400`: Missing or invalid SQL query
- `401`: Authentication required or invalid API key
- `403`: Service role required
- `404`: No database found for the given project_id
- `409`: Unique or primary-key constraint violation (duplicate). Branch on HTTP 409; body carries code "23505".
- `500`: Internal server error

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)