API reference

githubDB’s API is GitHub’s own REST API: queries go in through repository_dispatch, results come out through the raw file CDN. There is no githubDB server.

Send a query

POST https://api.github.com/repos/<OWNER>/githubdb/dispatches
Authorization: Bearer <token>
Accept: application/vnd.github+json

Body:

{
  "event_type": "query",
  "client_payload": {
    "id": "8c1f57e2-4f9a-4b6e-9f3d-2a7c1e5b0d44",
    "db": "example",
    "sql": "SELECT * FROM clients WHERE id > :min",
    "params": { "min": 5 }
  }
}

Field	Required	Description
event_type	yes	Always "query"
client_payload.id	yes	Unique query id, generated by the client (UUID recommended). The result is published at results/<id>.json. Without an id the workflow has nowhere to write the result and exits silently.
client_payload.db	yes	Database name — the file data/<db>.json
client_payload.sql	yes	A single SQL statement
client_payload.params	no	Named parameters referenced as :name in the SQL. Vector parameters may be a base64 float32 string or a JSON number array.

GitHub responds 204 No Content immediately — that only means the event was accepted, not that the query succeeded.

Read the result

GET https://raw.githubusercontent.com/<OWNER>/githubdb/<BRANCH>/results/<id>.json

Returns 404 until the workflow finishes (typically 10–30 s). Poll every ~3 s with a timeout of ~120 s.

Success:

{
  "ok": true,
  "id": "8c1f...",
  "rowCount": 2,
  "columns": ["id", "name"],
  "rows": [[1, "Ana"], [2, "Luis"]],
  "elapsedMs": 840
}

Statements that modify data (INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE) return rowCount = affected rows and empty rows.

Failure:

{ "ok": false, "id": "8c1f...", "error": "Table 'clients' not found in database 'example'" }

Error situation	Result
Invalid SQL	ok: false with the parser message
Unknown database	ok: false, Database '<x>' not found
Vector dimension mismatch	ok: false with expected/received dimensions
Row too large (file would exceed 100 MB even after sharding)	ok: false, no data committed
Concurrent push race	retried ×3 automatically, then ok: false

Result files are deleted automatically after one hour.

Fast reads without the Action

For read-only access you can skip the query API entirely and fetch the data files directly:

GET https://raw.githubusercontent.com/<OWNER>/githubdb/<BRANCH>/data/<db>.json

This is a CDN read — sub-second, no Actions minutes, no write token needed (public repos need no token at all). Combine it with client-side filtering or vector similarity for fast RAG retrieval; see Vector search.

Rate limits

All traffic goes through GitHub’s API: roughly 5,000 authenticated requests/hour per token. The raw CDN polling does not count against the API limit.