API 시작하기

그리디 워크스페이스의 테이블을 바깥 프로그램에서 읽고 쓸 수 있습니다. 대시보드, 자동화 스크립트, 직접 만든 웹 서비스가 그리디를 데이터베이스처럼 씁니다.

요청 규격은 PostgREST를 따릅니다. @supabase/supabase-js 클라이언트가 코드 수정 없이 그대로 붙습니다.

준비물은 두 가지입니다

키를 발급하고, 바깥에 열어 줄 테이블을 고릅니다. 둘 다 해야 합니다. 키만 발급하면 아무 테이블도 보이지 않습니다.

API 키 발급

유저 메뉴 → 설정 → 외부 연결 → API 키에서 키 발급을 누릅니다.

이름 어디에 쓰는 키인지 알아볼 이름을 적습니다.
권한 읽기만 할지, 읽고 쓰기까지 할지 여기서 정합니다. 발급한 뒤에는 바꿀 수 없습니다.
만료 기간을 정하거나 만료 없이 둡니다.

발급 직후 화면에서 키를 복사하세요. 창을 닫으면 다시 볼 수 없습니다. 그리디는 키의 해시만 저장하기 때문에 관리자도, 저희도 원래 값을 알지 못합니다. 잃어버렸다면 폐기하고 새로 발급하면 됩니다.

키는 발급한 사람의 권한을 그대로 물려받습니다. 내가 볼 수 없는 테이블은 내 키로도 보이지 않습니다. 반대로 내가 편집할 수 있는 테이블은 읽기·쓰기 키를 쥔 쪽에서 편집할 수 있습니다. 키를 넘길 때는 계정을 빌려주는 것과 같다고 생각하세요.

테이블 열기

테이블 화면 우측 상단 메뉴에서, 또는 설정 → 데이터베이스의 테이블 목록에서 API 연결을 켭니다.

설정 화면에서는 여러 테이블을 한 번에 켜고 끌 수 있습니다. 내가 읽기 권한만 가진 테이블은 스위치 대신 읽기 전용 표시가 붙습니다.

켜지 않은 테이블은 API에서 존재 자체가 보이지 않습니다. 이름을 정확히 알고 불러도 404가 돌아옵니다.

첫 요청

orders라는 테이블을 열어 두었다고 하겠습니다.

supabase-js


import { createClient } from "@supabase/supabase-js";
 
// 주소에는 오리진만 넣습니다. 경로를 붙이면 클라이언트가 잘못 조합합니다.
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);

curl


curl "https://gridie.ai/api/v1/tables/orders?status=eq.paid&order=created_at.desc&limit=20" \
  -H "apikey: $GRIDIE_API_KEY"

Python


import os, requests
 
response = requests.get(
    "https://gridie.ai/api/v1/tables/orders",
    params={"status": "eq.paid", "order": "created_at.desc", "limit": 20},
    headers={"apikey": os.environ["GRIDIE_API_KEY"]},
)
rows = response.json()

응답은 감싸는 키 없이 행 배열입니다.


[
  { "id": 1, "customer": "김지훈", "total": 42000 },
  { "id": 2, "customer": "이서연", "total": 18000 }
]

주소

정식 주소는 하나입니다.


https://gridie.ai/api/v1

Supabase 클라이언트를 쓴다면 오리진만 넘기세요. 이유와 주소 규칙은 Supabase 호환에 적어 두었습니다.

인증

키는 헤더로 보냅니다. 두 가지 형식을 모두 받습니다.


-H "apikey: gsk_..."
-H "Authorization: Bearer gsk_..."

브라우저에서 직접 부를 수도 있습니다. CORS 프리플라이트에 응답하고, 개수를 읽을 수 있도록 Content-Range 헤더를 노출합니다. 다만 키가 브라우저 코드에 들어가면 방문자 모두가 그 키를 갖게 됩니다. 공개 페이지에서는 서버를 한 단계 두는 편이 안전합니다.

키 확인하기

프로그램이 여러 키를 다룰 때, 지금 쥔 키가 무엇인지 물어볼 수 있습니다.


curl "https://gridie.ai/api/v1/me" -H "apikey: $GRIDIE_API_KEY"


{
  "workspace": { "id": "0b1e…", "name": "우리 회사" },
  "permission": "read",
  "expiresAt": null,
  "tableCount": 3
}

permission은 read 또는 write이고, tableCount는 이 키로 볼 수 있는 테이블 수입니다. 0이라면 아직 테이블을 열지 않은 것입니다.

REST API에서 조회, 추가, 수정, 삭제와 필터 문법을 다룹니다. Supabase 클라이언트로 붙일 계획이라면 Supabase 호환을 먼저 보세요.