Getting Started with the API
Read and write your workspace tables from outside Gridie. Dashboards, automation scripts and your own web services can treat Gridie as a database.
Requests follow the PostgREST convention. The @supabase/supabase-js client connects without any changes to your code.
Two things to set up
Issue a key, then choose which tables to open. You need both. A key on its own shows you nothing.
Issue an API key
Go to User menu → Settings → External access → API keys and click Create key.
- Name something that tells you where the key is used.
- Permission read only, or read and write. You choose this here and it cannot be changed later.
- Expiry set a period, or leave it without one.
Copy the key from the screen right away. Once you close the dialog it cannot be shown again. Gridie stores only a hash, so neither your administrators nor we can recover the original. If you lose it, revoke the key and issue a new one.
A key inherits the permissions of the person who issued it. Tables you cannot see stay invisible through your key. Conversely, tables you can edit are editable by whoever holds a read and write key. Handing over a key is close to lending out your account.
Open a table
Turn API access on from the menu at the top right of a table, or from the table list under Settings → Database.
The settings screen lets you switch many tables at once. Tables you only have read access to show a read-only marker instead of a switch.
A table that is not opened does not exist as far as the API is concerned. Requesting it by its exact name still returns 404.
Your first request
Say you opened a table called orders.
supabase-js
import { createClient } from "@supabase/supabase-js";
// Pass the origin only. Adding a path makes the client build the wrong URL.
const gridie = createClient("https://gridie.ai", process.env.GRIDIE_API_KEY);
const { data, error } = await gridie
.from("orders")
.select("id, customer, total")
.eq("status", "paid")
.order("created_at", { ascending: false })
.limit(20);The response is a bare array of rows, with no wrapper key.
[
{ "id": 1, "customer": "Ada Lovelace", "total": 42000 },
{ "id": 2, "customer": "Grace Hopper", "total": 18000 }
]Base URL
There is one canonical address.
https://gridie.ai/api/v1With a Supabase client, pass the origin only. Supabase Compatibility explains why, along with the URL rules.
Authentication
Send the key as a header. Both forms are accepted.
-H "apikey: gsk_..."
-H "Authorization: Bearer gsk_..."You can call the API straight from a browser. We answer CORS preflights and expose the Content-Range header so clients can read counts. Keep in mind that a key placed in browser code belongs to every visitor who loads the page. For public pages, put a server in front.
Inspecting a key
When a program juggles several keys, it can ask what the current one is.
curl "https://gridie.ai/api/v1/me" -H "apikey: $GRIDIE_API_KEY"{
"workspace": { "id": "0b1e…", "name": "Acme" },
"permission": "read",
"expiresAt": null,
"tableCount": 3
}permission is either read or write, and tableCount is how many tables this key can see. Zero means no table has been opened yet.
Next
REST API covers reading, inserting, updating, deleting and the filter syntax. If you plan to use a Supabase client, start with Supabase Compatibility.