データベースの REST API

外部システムからデータベースの行を読み書きできます。認証は他の API と同じく X-API-Key ヘッダーです（→ API の概要）。

テーブルごとの API リファレンス

行の API は、テーブルのフィールド定義に合わせてリクエスト・レスポンスの形が変わります。そのため テーブルごとのリファレンス を画面から確認できます。

テーブルの詳細画面 →「REST API ドキュメント」タブ

OpenAPI 仕様そのものを取得することもできます（こちらはテーブルID のみ指定できます）。

GET /api/tables/{tableId}/openapi

テーブルの指定方法

行の API の URL の {tableIdOrCode} には、テーブルID（UUID）と テーブルコード のどちらでも指定できます。テーブルコードは「基本情報」タブで設定します。→ テーブルとフィールドを設計する

curl https://api.synqlet.com/api/tables/customers/rows \
  -H "X-API-Key: sk_synqlet_..."

エンドポイント

テーブルの詳細画面 →「REST API ドキュメント」タブで確認してください

テーブル自体の管理（/api/tables の一覧・作成・更新・削除）は APIリファレンス を参照してください。

ノート

一括操作（rows-bulk）は1回のリクエストで 最大1000件 です。テーブルをまたいでまとめて操作したい場合は POST /api/rows-batch を使います。

行の形

{
  "id": "019e8310-1f6c-7f1e-9f18-2a17b0d1a111",
  "createdAt": "2026-07-30T02:11:43.123Z",
  "updatedAt": "2026-07-30T02:11:43.123Z",
  "createdBy": "0197bfe7-85da-7de7-b884-45c269f182b1",
  "updatedBy": "0197bfe7-85da-7de7-b884-45c269f182b1",
  "values": {
    "name": "株式会社サンプル",
    "score": 80,
    "closedAt": null
  }
}

日時は ISO 8601 形式の文字列、日付は 2026-07-30、時刻は 12:34:56、年月は 2026-07 の形式です。

一覧取得（フィルター・並び替え・ページング）

GET /api/tables/{tableIdOrCode}/rows のクエリパラメータです。

パラメータ	説明
pageSize	1ページの件数（1〜200、既定 50）
filter	絞り込み条件（JSON 文字列）
sort	並び替え（JSON 文字列）
cursor	次ページの位置。レスポンスの nextUrl に含まれます

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

{
  "data": [{ "id": "...", "values": { "name": "株式会社サンプル" } }],
  "nextUrl": "https://api.synqlet.com/api/tables/customers/rows?pageSize=50&cursor=..."
}

ヒント

nextUrl をそのまま呼び出せば次のページを取得できます。件数の増減で行が重複・欠落しないカーソル方式のページングです。

filter

filter には JSON を URL エンコードして渡します。

{
  "values": {
    "name": { "_contains": "サンプル" },
    "score": { "_gte": 50 }
  },
  "createdAt": { "_gte": "2026-07-01T00:00:00Z" }
}

指定できる演算子（_eq / _gt / _gte / _lt / _lte / _contains / _startsWith / _endsWith / _isNull）と、_and / _or / _not の組み合わせはスクリプトから使う場合と同じです。→ フィルター

curl -G https://api.synqlet.com/api/tables/customers/rows \
  -H "X-API-Key: sk_synqlet_..." \
  --data-urlencode 'filter={"values":{"status":{"_eq":"active"}}}' \
  --data-urlencode 'sort=[{"createdAt":{"direction":"desc","nulls":"nullsLast"}}]'

sort

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

CSV / TSV / JSONL でダウンロードする

GET /api/tables/{tableIdOrCode}/rows-export は、条件に一致する行を CSV / TSV / JSONL で全件 返します（ページングはありません）。レスポンスは順次書き出されるため、行数が多くてもサーバー側にファイルを溜め込みません。

format / encoding / newline は 必須 です（出力されるファイルの中身が変わる指定なので、既定値に頼らず必ず指定してください）。省略すると 400 になります。

パラメータ	必須	説明
format	○	csv / tsv / jsonl
encoding	○	utf8 / utf8Bom / shiftJis。utf8Bom は BOM 付き（Excel 向け）。Shift_JIS にできない文字は ? になります
newline	○	crlf / lf
header		true（既定） / false。1行目にフィールドコードを出力するか（jsonl では無視されます）
limit		出力する行数の上限（1〜1000）。未指定なら全件。先頭数件だけ確認したいときに使います
filter		一覧取得と同じ絞り込み条件（JSON 文字列）
sort		一覧取得と同じ並び替え（JSON 文字列）

curl -G https://api.synqlet.com/api/tables/customers/rows-export \
  -H "X-API-Key: sk_synqlet_..." \
  --data-urlencode 'format=csv' \
  --data-urlencode 'encoding=shiftJis' \
  --data-urlencode 'newline=crlf' \
  --data-urlencode 'filter={"values":{"status":{"_eq":"active"}}}' \
  -o customers.csv

csv / tsv の列は id / createdAt / updatedAt / createdBy / updatedBy の後にテーブルのフィールドが続きます。レコード型・リスト型の値は JSON 文字列、ファイル型の値はファイルの名前・MIMEタイプ・サイズの JSON 文字列になります（ファイルの中身とダウンロードURLは含まれません）。

jsonl は1行に1件の JSON を出力します（JSON Lines）。1件取得（GET /rows/{rowId}）と同じ形なので、レコード型・リスト型も構造のまま扱えます（ファイル型のダウンロードURLだけは含まれません）。

curl -G https://api.synqlet.com/api/tables/customers/rows-export \
  -H "X-API-Key: sk_synqlet_..." \
  --data-urlencode 'format=jsonl' \
  --data-urlencode 'encoding=utf8' \
  --data-urlencode 'newline=lf' \
  -o customers.jsonl

ノート

出力はリクエストを受け付けた時点のスナップショットです。出力の途中で行が追加・更新・削除されても、同じ行が2回出てきたり抜け落ちたりすることはありません（サーバー側でカーソルを使って読み出しているためです）。

そのため、ダウンロードを長時間（2分以上）中断したまま放置すると、エクスポートは打ち切られます。再度リクエストしてください。

ノート

画面の「ダウンロード」ボタンも同じエンドポイントを使います。ブラウザはリクエストヘッダーを付けられないため、画面からのダウンロードでは POST /api/tables/{tableIdOrCode}/rows-export-token で発行した短命なトークンを token クエリパラメータに載せます。API から呼び出す場合は他のエンドポイントと同じく X-API-Key ヘッダーで認証してください。

作成・更新

作成（POST /rows）では values を指定します。id を省略すると自動で割り振られます。options.upsert を true にすると、同じIDの行が既にある場合は更新します（既定はエラー）。

curl -X POST https://api.synqlet.com/api/tables/customers/rows \
  -H "X-API-Key: sk_synqlet_..." \
  -H "Content-Type: application/json" \
  -d '{"id":"customer-001","values":{"name":"株式会社サンプル","status":"active"},"options":{"upsert":true}}'

更新（PATCH /rows/{rowId}）は部分更新です。指定しなかったフィールドは変更されません。値を空にするには null を指定します（必須フィールドは null にできません）。

curl -X PATCH https://api.synqlet.com/api/tables/customers/rows/customer-001 \
  -H "X-API-Key: sk_synqlet_..." \
  -H "Content-Type: application/json" \
  -d '{"values":{"status":"archived"}}'

一括作成・更新は rows-bulk に data の配列を渡します。

{ "data": [{ "id": "customer-001", "values": { "status": "archived" } }] }

一括削除は DELETE /rows-bulk に ids を渡します。

{ "ids": ["customer-001", "customer-002"] }

複数テーブルをまとめて操作する rows-batch

rows-bulk は1つのテーブルだけを対象にします。テーブルをまたいで 作成・更新・削除をまとめたい場合は POST /api/rows-batch を使います。

curl -X POST https://api.synqlet.com/api/rows-batch \
  -H "X-API-Key: sk_synqlet_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "type": "create", "tableId": "customers", "values": { "name": "株式会社サンプル" } },
      { "type": "update", "tableId": "orders", "id": "order-001", "values": { "status": "done" } },
      { "type": "delete", "tableId": "carts", "id": "cart-001" }
    ]
  }'

• operations は 配列の先頭から順に、1つのトランザクション で処理されます。1件でも失敗すると全体が失敗し、途中までの変更は残りません。
• そのため「作成した行を後続の操作で更新する」といった依存のある並びも書けます。
• 1回につき 最大1000件 です。
• type ごとに指定するものが変わります。

type	指定するもの
create	values（id は省略可。options.upsert も指定できる）
update	id と values（部分更新）
delete	id

レスポンスは、リクエストの操作と 同じ順番・同じ件数 の結果です（operations[i] の結果が data[i]）。type は操作の種類で、作成・更新は row に行が入り、削除は row が null になります。

{
  "data": [
    {
      "type": "create",
      "row": { "id": "019e...", "values": { "name": "株式会社サンプル" } }
    },
    {
      "type": "update",
      "row": { "id": "order-001", "values": { "status": "done" } }
    },
    { "type": "delete", "row": null }
  ]
}

row は1件取得のレスポンスと同じ形（id / createdAt / updatedAt / createdBy / updatedBy / values）です。

ノート

スクリプトからは synqlet:database の batchRequest() / batchRequestKeyed() で同じことができます。→ スクリプトからデータベースを操作する

ファイルを添付する

ファイル型フィールドには、次の手順でファイルを添付します。

1. アップロードURLを発行する

   curl -X POST https://api.synqlet.com/api/tables/customers/rows/customer-001/file-upload-url \
     -H "X-API-Key: sk_synqlet_..." \
     -H "Content-Type: application/json" \
     -d '{"count":1}'

   data に { "id": "...", "url": "..." } が count 件返ります（1回で最大50件）。

2. 返ってきた url にファイル本体を PUT する

   curl -X PUT "<発行されたURL>" \
     -H "Content-Type: text/csv" \
     --data-binary @report.csv

3. 行の作成 / 更新でファイル情報を指定する

   {
     "values": {
       "attachment": { "id": "<発行されたID>", "name": "report.csv" }
     }
   }

行に紐づけられなかったファイルは、あとで自動的に削除されます。

取得時のファイル型フィールドの値には、ファイル名・MIMEタイプ・サイズと、1時間だけ有効なダウンロード用URL が入ります。

ノート

既にあるファイル（別テーブルの行のファイルやフロージョブの添付ファイル）は、values に { "copyFrom": ..., "name": ... } を指定してコピーもできます。スクリプトから扱う場合はコピー元の指定が自動で行われます。→ ファイル型フィールドを扱う

関連ページ

• API の概要 / APIキーの発行
• データベースとは
• スクリプトからデータベースを操作する