API の使い方（CRUD・検索）

ここでは、REST API でのデータ操作（CRUD）と、一覧取得時の絞り込み・並び替え・ページングの指定方法を説明します。認証や基本はAPI の概要を参照してください。

各エンドポイントの正確なパス・パラメータ・スキーマはAPIリファレンスで確認できます。

HTTP メソッドと CRUD

リソース（/api/<リソース名>）に対して、HTTP メソッドで操作します。

操作	メソッド・パス	説明
一覧取得	`GET /api/<リソース>`	一覧を取得（`data` と `pagination` を返す）
個別取得	`GET /api/<リソース>/<id>`	1件取得
作成	`POST /api/<リソース>`	作成（ボディに JSON）
更新	`PUT /api/<リソース>/<id>`	更新（ボディに JSON）
削除	`DELETE /api/<リソース>/<id>`	削除
一括作成	`POST /api/<リソース>/create-many`	ボディに JSON の配列
一括更新	`PUT /api/<リソース>/update-many`	ボディに JSON の配列
一括削除	`DELETE /api/<リソース>/delete-many`	ボディに JSON の配列

# 作成の例
curl -X POST https://api.synqlet.com/api/environment-variables \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "API_BASE_URL", "value": "https://example.com" }'

プログラムから全件を取得するときは、一覧取得（GET /api/<リソース>）を paging で辿ってください（pagination.nextOffset が null になるまで繰り返します。後述のページングのレスポンスを参照）。CSV / TSV / JSONL のファイルが欲しい場合は、画面の一覧右上のメニューから「ダウンロード」を選ぶと、形式・文字コード・改行コードを選んで保存できます。

テーブルの行データのファイルダウンロードは今までどおり使えます（→ データベースの REST API）。

絞り込み・並び替え・ページング

一覧取得（GET）では、次のクエリパラメータを URLエンコードした JSON で指定します。

パラメータ	内容	例（エンコード前の JSON）
`paging`	ページング	`{"limit":50,"offset":0}`
`filter`	絞り込み条件	`{"name":{"eq":"本番バッチ連携"}}`
`sorting`	並び替え	`{"createdAt":"desc"}`
`relations`	関連を含める	`["createdByMember"]`

# filter と paging を指定する例（JSON を URL エンコードして渡す）
curl -G https://api.synqlet.com/api/flows \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'paging={"limit":20,"offset":0}' \
  --data-urlencode 'filter={"name":{"eq":"サンプル通知フロー"}}'

指定できるフィールドや演算子（eq など）はリソースごとに異なります。詳細はAPIリファレンスを参照してください。

ページングのレスポンス

一覧のレスポンスには pagination が含まれます。

{
  "data": [/* ... */],
  "pagination": { "limit": 20, "count": 1, "offset": 0, "nextOffset": null }
}

nextOffset が null でなければ、その値を paging.offset に指定して続きを取得できます。

エラー応答

エラー時は HTTP ステータスコードと、次の形式の JSON が返ります。

{ "message": "Invalid api key", "error": "Unauthorized", "statusCode": 401 }

ステータス	主な原因
`401 Unauthorized`	`X-API-Key` が未設定・不正
`400 Bad Request`	リクエスト内容（ボディ・パラメータ）が不正
`404 Not Found`	指定した ID のリソースが存在しない