API の使い方（CRUD・検索）

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

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

HTTP メソッドと CRUD

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

操作	メソッド・パス	説明
一覧取得	`GET /api/<リソース>`	一覧を取得（`data` と `nextUrl` を返す）
件数取得	`GET /api/<リソース>/count`	`filter` に一致する件数を取得（`{ "count": 数値 }` を返す）
個別取得	`GET /api/<リソース>/<id>`	1件取得
作成	`POST /api/<リソース>`	作成（ボディに JSON）。`201 Created` で作成したデータを返す
更新	`PATCH /api/<リソース>/<id>`	部分更新（ボディに JSON）。省略した項目は変更されない。対象は URL の `<id>` で決まるので、ボディの `id` は省略可（書くなら URL と同じ値に。異なると `400`）
削除	`DELETE /api/<リソース>/<id>`	削除。`204 No Content`（本文なし）を返す
一括作成	`POST /api/<リソース>-bulk`	ボディに `{ "data": [...] }`。`201 Created` で作成したデータの配列を返す
一括更新	`PATCH /api/<リソース>-bulk`	ボディに `{ "data": [{ "id": "...", ... }] }`。更新したデータの配列を返す
一括削除	`DELETE /api/<リソース>-bulk?ids=A&ids=B`	削除する ID をクエリの `ids` に並べる（ボディは不可）。`204 No Content`

# 作成の例
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" }'

# 更新の例（value だけを変更する）
curl -X PATCH https://api.synqlet.com/api/environment-variables/<id> \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": "https://example.org" }'

データベースの行以外のリソースの REST API は、データベースの REST API（行API）と同じ方式に揃えるため、次のとおり互換性の無い変更を行いました。以前の形式のリクエストは使えません。

更新は PUT から PATCH（部分更新）に変わりました
削除は 204 No Content（本文なし）を返すようになりました
一括操作は /create-many /update-many /delete-many から <リソース>-bulk に変わりました
一覧のページングは paging（limit / offset）から pageSize / cursor に、レスポンスは pagination から nextUrl に変わりました。件数は GET /api/<リソース>/count で取得します
並び替えのパラメータは sorting から sort に変わりました
絞り込みの演算子は eq から _eq のように _ 付きになりました

データベースの REST API（/api/tables/<tableId>/rows など）は変わらず、これまでどおり使えます。

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

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

一括操作

一括作成・一括更新はボディの data に配列を指定します。一括更新では各要素に id が必要です。

# 一括作成
curl -X POST https://api.synqlet.com/api/environment-variables-bulk \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "data": [
        { "name": "API_BASE_URL", "value": "https://example.com" },
        { "name": "TIMEOUT_SECONDS", "value": "30" }
      ] }'

# 一括削除（ID をクエリに並べる）
curl -X DELETE "https://api.synqlet.com/api/environment-variables-bulk?ids=<id1>&ids=<id2>" \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

1回に指定できるのは 1,000件までです（超えると 400 Bad Request）。
一括削除で ids が無い・空のときは 400 Bad Request です。存在しない ID が1つでも含まれていると、何も削除せずに 404 Not Found を返します（全件削除されるか、1件も削除されないかのどちらかです）。
一括削除の ID は URL に入るため、URL 全体を 6,000 バイト以内に収めてください。超える場合は複数回のリクエストに分けてください（経由するネットワーク機器によっては長い URL が拒否されるため）。

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

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

パラメータ	内容	例（エンコード前）
`pageSize`	1ページの件数（1〜1000、既定 50）	`20`
`cursor`	次ページの位置。レスポンスの `nextUrl` に含まれる値を使います
`filter`	絞り込み条件	`{"name":{"_eq":"本番バッチ連携"}}`
`sort`	並び替え	`[{"createdAt":{"direction":"desc","nulls":"nullsLast"}}]`
`relations`	関連を含める	`["createdByMember"]`

# filter と sort を指定する例（JSON を URL エンコードして渡す）
curl -G https://api.synqlet.com/api/flows \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'filter={"name":{"_contains":"通知"}}' \
  --data-urlencode 'sort=[{"createdAt":{"direction":"desc","nulls":"nullsLast"}}]'

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

filter

filter は「フィールド名: 条件」の JSON です。複数のフィールドを並べると AND 条件になります。

演算子	使えるフィールド	意味
`_eq`	文字列・数値・日時・真偽値・ID・列挙値	等しい
`_contains`	文字列・文字列の配列	部分一致（大文字小文字を区別しない）
`_gte` / `_lte`	文字列・数値・日時	以上 / 以下
`_between`	文字列・数値・日時	範囲（`{ "lower": ..., "upper": ... }`）
`_arrayContains`	配列	指定した値を要素に含む（完全一致）
`_notEmpty`	文字列の配列	`true` で要素が1つ以上あるもの
`_jsonContains`	JSON の項目	指定した JSON を含む（構造の部分一致）
`_field`	JSON の項目	JSON の中の1項目で絞り込む（`{ "fieldName": "...", "filter": { "stringFilter": { "_eq": "..." } } }`。`stringFilter` / `numberFilter` / `booleanFilter` から選ぶ）

ID の項目に UUID として読めない値を指定すると 400 になります。 numberFilter では、数値として読めない値（文字列・真偽値など）が入っているデータは条件に一致しません。

条件を組み合わせるときは _and / _or に条件の配列を指定します。

{
  "_or": [
    { "name": { "_contains": "通知" } },
    { "createdAt": { "_gte": "2026-07-01T00:00:00Z" } }
  ]
}

sort

sort は条件の配列です。1要素につき1項目を指定し、direction（asc / desc）と nulls（nullsFirst / nullsLast）を両方とも必ず指定します。配列の先頭が優先されます。

[
  { "archived": { "direction": "asc", "nulls": "nullsLast" } },
  { "createdAt": { "direction": "desc", "nulls": "nullsLast" } }
]

カスタムフィールドの値（values）のような JSON の項目は、中の項目名（field）と比較の方法（type: string / number）も指定します。日付は string で並べます。

[{ "values": { "field": "priority", "type": "number", "direction": "desc", "nulls": "nullsLast" } }]

number で並べるとき、数値として読めない値（文字列・真偽値など）は値が無いものとして扱い、nulls で指定した位置に並びます。

並び替えの最後には必ず id の昇順が足されます（同じ値のデータの順序を一定にするため）。sort を指定しないときは id の昇順です。

ページング

一覧のレスポンスは data（結果の配列）と nextUrl（次ページのURL。無ければ null）です。Link: <...>; rel="next" ヘッダーにも同じURLが入ります。

{
  "data": [/* ... */],
  "nextUrl": "https://api.synqlet.com/api/flows?pageSize=20&cursor=..."
}

nextUrl をそのまま呼び出せば次のページを取得できます。nextUrl は今のリクエストの filter / sort などを保ったまま cursor だけを差し替えたURLです。途中でデータが増減しても重複・欠落しないカーソル方式のページングです。

件数の取得

一覧のレスポンスには件数が含まれません。件数が必要なときは GET /api/<リソース>/count を呼び出します。一覧と同じ filter を指定できます。

curl -G https://api.synqlet.com/api/flows/count \
  -H "X-API-Key: sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'filter={"archived":{"_eq":false}}'

{ "count": 12 }

エラー応答

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

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

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