REST API

Claude などの AI アシスタントから raxel を操作したい場合は、この REST API を直接呼ぶ代わりにAI エージェント連携 (MCP) が使えます (設定 1 つで接続でき、エンドポイントの知識が不要になります)。

REST APIを使用して、外部システムからレコードの取得・作成・更新・削除を行えます。 すべてのAPIリクエストにはAPIトークンによる認証が必要です。

認証

リクエストヘッダーに X-API-Token を含めてAPIトークンを送信します。 APIトークンはアプリの設定画面から発行できます。

curl -H "X-API-Token: YOUR_API_TOKEN" \
  https://example.com/api/apps/{appId}/records

トークン権限

APIトークンには以下の権限を個別に付与できます。必要最小限の権限を設定してください。

レート制限

• APIトークンごとに 600リクエスト/分 の制限があります。
• 制限を超えた場合、ステータスコード 429 Too Many Requests が返されます。
• レート制限に達した 429 レスポンスにはX-RateLimit-Limit /X-RateLimit-Remaining /X-RateLimit-Reset ヘッダーが付与されます （Reset は Unix 秒）。
• テナントごとの同時接続数上限とアプリごとの日次リクエスト上限も別途適用され、超過時はいずれも429 が返されます。

エンドポイント一覧

{
  "data": {
    "title": "サンプルタイトル",
    "priority": "high",
    "dueDate": "2026-04-01"
  }
}

{
  "data": {
    "priority": "medium"
  },
  "expectedHistoryVersion": 5
}

{
  "recordIds": ["rec_001", "rec_002"],
  "data": {
    "status": "completed"
  }
}

{
  "recordIds": ["rec_001", "rec_002"]
}

{
  "creates": [
    { "data": { "title": "新規1" } }
  ],
  "updates": [
    { "recordId": "rec_001", "data": { "title": "更新1" } },
    { "recordId": "rec_002", "data": { "title": "更新2" } }
  ],
  "deletes": ["rec_900"]
}

{
  "transitionId": "<transitionId>",
  "comment": "承認しました",
  "assignee": "<userId>"
}

{
  "operations": [
    { "op": "record.create", "appId": "<appId>", "data": { "title": "新規" } },
    { "op": "record.update", "appId": "<appId>", "id": "rec_001", "data": { "title": "更新" } },
    { "op": "record.status", "appId": "<appId>", "id": "rec_002", "transitionId": "<transitionId>" },
    { "op": "comment.create", "appId": "<appId>", "recordId": "rec_003", "body": "コメント" }
  ]
}

{
  "recordIds": ["rec_001", "rec_002"]
}

{
  "recordIds": ["rec_001", "rec_002"],
  "transitionIdsByFromStatus": {
    "<fromStatusId>": "<transitionId>"
  },
  "comment": "一括承認しました"
}

{
  "body": "コメント本文",
  "mentions": [
    { "type": "user", "targetId": "<userId>" }
  ]
}

{
  "assigneeUserId": "<userId>"
}

{
  "records": [
    { "data": { "title": "タスクA", "priority": "high" } },
    { "data": { "title": "タスクB", "priority": "medium" } }
  ]
}

{
  "records": [
    {
      "id": "<recordId>",
      "data": { "priority": "high" },
      "expectedHistoryVersion": 3
    },
    {
      "updateKey": { "field": "externalCode", "value": "ABC-001" },
      "data": { "status": "completed" }
    }
  ]
}

{
  "records": [
    { "id": "<recordId>" },
    { "id": "<recordId>" }
  ]
}

複数操作の原子実行 (bulkRequest)

POST /api/bulk-request を使うと、 複数の操作を1リクエストにまとめて単一トランザクションで原子実行できます。 1つでも操作が失敗した場合は全操作がロールバックされ、何も確定しません。 レコードの CRUD・ワークフロー遷移・コメント操作を、複数のアプリをまたいで混在させることができます。

リクエストボディは { "operations": [ ... ] } 形式で、 最大 20 操作まで指定できます。各操作は op（操作種別）とappId を必ず含みます。

サポートする操作 (op)

レスポンス

成功時は { "results": [ ... ] } を返します。results は入力の operations と同じ順序で、各 op の結果が入ります。 レコード操作の結果には op・id・recordNumber・historyVersion が含まれます。 コメント操作の結果には op・commentId が含まれます。

いずれかの操作が失敗した場合は、失敗した操作の情報を含む以下のエラーレスポンスが返され、全操作がロールバックされます。

{
  "error": "エラーメッセージ",
  "index": 1,
  "op": "record.update",
  "appId": "<appId>",
  "code": "PERMISSION_DENIED",   // 省略されることがあります
  "details": { ... }             // 省略されることがあります
}

APIトークン認証の制約

セッション認証（ログインユーザー）では複数アプリの操作を1リクエストに混在させることができます。APIトークン認証では、トークンを発行したアプリの操作のみ実行できます（他のアプリを指定した操作は 403 になります）。 また、各 op には対応するトークンスコープが必要です（record.delete には delete 権限、それ以外は write 権限）。

副作用

通知・ルックアップ集計などの副作用（post-commit side effects）は、トランザクションのコミット後にまとめて実行されます。 副作用の失敗はリクエスト全体の結果には影響しません。

curl 例

# APIトークンで record.create と comment.create を1リクエストで原子実行する例
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "record.create",
        "appId": "app_001",
        "data": { "title": "新規タスク", "priority": "high" }
      },
      {
        "op": "comment.create",
        "appId": "app_001",
        "recordId": "rec_existing_001",
        "body": "関連タスクを作成しました。"
      }
    ]
  }' \
  "https://example.com/api/bulk-request"

# 成功時のレスポンス例
{
  "results": [
    {
      "op": "record.create",
      "id": "rec_new_001",
      "recordNumber": 42,
      "historyVersion": 1
    },
    {
      "op": "comment.create",
      "commentId": "cmt_001"
    }
  ]
}

# 失敗時のレスポンス例（全操作ロールバック）
{
  "error": "アプリ app_001 に対する操作権限がありません",
  "index": 1,
  "op": "comment.create",
  "appId": "app_001",
  "code": "PERMISSION_DENIED"
}

ファイル（添付）API

レコードのフィールドにファイルを添付するには、まずファイルをアップロードしてid を取得し、 その id をレコードの data に指定します。

アップロード

POST /api/upload にmultipart/form-data でファイルを送信します。write 権限の API トークンが必要です。

# fieldId は添付フィールドの id (フィールドコードではない)。
# GET /api/apps/{appId}/fields が返す各フィールドの "id" で調べる
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -F "appId=<appId>" \
  -F "fieldId=<attachmentFieldId>" \
  -F "file=@/path/to/document.pdf" \
  "https://example.com/api/upload"

# レスポンス例
{
  "id": "clxxxxxxxxxxxxxxxx",
  "fileName": "document.pdf",
  "fileSize": 204800,
  "mimeType": "application/pdf",
  "url": "/api/upload/clxxxxxxxxxxxxxxxx"
}

フォームフィールドの指定:

既存レコードの添付フィールドにファイルを追加するときは、recordId にそのレコードの ID を指定してください。 レコードに依存するフィールドのアクセス権（作成者・ワークフローの担当者などを対象にした設定）と、 ステータスごとのフィールドの編集制限が、そのレコードに対して評価されます。 指定したレコードが存在しない・閲覧できない場合は 404、閲覧はできるが編集できない場合は 403 を返します。recordId を指定しても、ファイルはまだレコードに紐づきません。 下の「レコードへの添付」のとおり、レコードの更新で data に指定してください。

recordId を指定しない場合は、特定のレコードを前提にせずに権限を確認します。 新しく作るレコードか既存のレコードのどちらかでそのフィールドに書き込めれば受け付けます。 新しく作るレコードとしての確認では、作成者をトークンの発行者とみなします（新規登録の画面と同じ扱い）。 それ以外のレコードに依存する設定（ワークフローの担当者・ユーザー選択フィールドの値など）と、 ステータスごとのフィールドの編集制限は評価されません。

レコードへの添付

アップロードで取得した id を、 レコード作成・更新時の data に指定します。 添付フィールドの値は [{ "id": "<id>" }] の配列形式です。

# レコード作成時にファイルを添付
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "提出書類",
      "attachment": [{ "id": "clxxxxxxxxxxxxxxxx" }]
    }
  }' \
  "https://example.com/api/apps/1/records"

# 一括登録（batch）でも同様に指定できます
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "data": { "title": "書類A", "attachment": [{ "id": "clxxxxxxxxxxxxxxxx" }] } },
      { "data": { "title": "書類B", "attachment": [{ "id": "clyyyyyyyyyyyyyy" }] } }
    ]
  }' \
  "https://example.com/api/apps/1/records/batch"

ダウンロード

GET /api/upload/{id} でファイルをダウンロードできます。read 権限の API トークンが必要です。

curl -H "X-API-Token: YOUR_API_TOKEN" \
  "https://example.com/api/upload/clxxxxxxxxxxxxxxxx" \
  -o document.pdf

テーブル（サブテーブル）フィールドの値

data の直下はフィールドコードがキーですが、テーブル（サブテーブル）フィールドの明細行のキーだけはサブフィールドの id です（コードではありません）。 ここだけキーの種類が変わるので、コードで送ると明細が保存されません。

サブフィールドの id はGET /api/apps/{appId}/fields のsettings.subFields[].id で取得できます。 レコード取得（GET）が返す明細行も同じ id キーなので、更新時はその形のまま送り返せます。

# 1. サブフィールドの id を調べる
curl -H "X-API-Token: YOUR_API_TOKEN" \
  "https://example.com/api/apps/1/fields"
# => { "code": "details", "type": "subtable",
#      "settings": { "subFields": [ { "id": "sf_a1b2", "code": "item_name", ... },
#                                   { "id": "sf_c3d4", "code": "amount", ... } ] } }

# 2. 明細行のキーには id を使う (code ではない)
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"title":"8月分の経費","details":[{"sf_a1b2":"交通費","sf_c3d4":1200}]}}' \
  "https://example.com/api/apps/1/records"

行に未知のキー（サブフィールドのコードや綴り違い、削除済みサブフィールドの旧 id）が 含まれる場合は 400 になり、コードで送っていたときはコード → id の対応表がエラーメッセージに入ります。 一部のキーだけをコードで送った場合も、その列だけが黙って消えることはなく 400 になります。 すべてのキーが未知の場合は「この行は空行として保存されます」と明示されるので、 メッセージの対応表どおりにキーを置き換えて再送してください。

なお、明細の値そのものを条件にした絞り込み・集計はできません。filters のfield にdetails.amount のような 指定をしてもエラーにはならず、常に 0 件になります（明細は配列なので この形では値に届きません）。明細の値で絞り込む・集計するには、レコード側に計算フィールドまたは 関連レコード集計フィールドを用意して、そのフィールドコードを使ってください。

cursor（シーク）ページング

大量のレコードを順次取得する際は、offset ページング（page）ではなくcursor ページングを使用することを推奨します。 cursor ページングはシーク方式のため、レコードの追加・削除が発生しても重複や取りこぼしが起きません。

レスポンスに nextCursor が含まれる場合、次のリクエストのcursor パラメータにその値を渡すことで次ページを取得できます。nextCursor が含まれない場合は最終ページです。

対応するソートと制約

全件を確実かつ順次取得したい場合は、組み込みフィールド（recordNumber / createdAt / updatedAt）でのソート + cursorを使用してください。件数上限なく取りこぼしなく全件を traverse できます。 任意フィールドでのソート + cursor は、対象件数が 5,000 件以内の場合のみ安定して動作します。

cursor ページングの例

# 1ページ目を取得（cursor なし）
curl -H "X-API-Token: YOUR_API_TOKEN" \
  "https://example.com/api/apps/1/records?sortField=recordNumber&sortDirection=asc&perPage=100"

# レスポンス例
{
  "records": [ ... ],
  "total": 3500,
  "page": 1,
  "perPage": 100,
  "nextCursor": "eyJybiI6MTAwfQ"
}

# 2ページ目以降は nextCursor を cursor に渡す
curl -H "X-API-Token: YOUR_API_TOKEN" \
  "https://example.com/api/apps/1/records?sortField=recordNumber&sortDirection=asc&perPage=100&cursor=eyJybiI6MTAwfQ"

# nextCursor が含まれなくなったら最終ページ

クエリ文字列によるフィルタ（query パラメータ）

レコード一覧取得（GET /api/apps/{appId}/records）のquery パラメータに文字列を渡すと、 比較演算子・論理演算子・括弧・関数を使ったクエリ文字列でレコードを絞り込めます。 既存の filters（JSON配列）やfilter[フィールドコード] と同じ絞り込みを、 括弧を使った入れ子条件も含めて1本の文字列で表現できます。 このパラメータはレコード一覧取得 API 専用です（CSVエクスポート・集計・公開ビュー等の API では利用できません）。

比較演算子

条件は and /or で連結し、( ) でグルーピングできます（ネストは最大3階層）。and /or /in /like /is /not /empty /order /by /asc /desc /limit /offset の各キーワードは大文字・小文字を区別しません。 文字列値はダブルクォートで囲みます（\" でエスケープ可）。 数値やクォートなしの値もそのまま書けます。フィールドコードは日本語コードも使用できます。

※ order /limit /offset の3語だけは、クエリ全体の先頭トークンとしてはフィールド名に使えません （そこでのみ「フィルタ式が無く句が始まる」と解釈されるためです）。 これらと同名のフィールドを先頭条件で使いたい場合は括弧で包む（(order = "1")）か、 後述の filterTree を使用してください。

関数

値の位置に関数を書くと、実行時の日時や実行ユーザーに応じた値へ解決されます。

※ 未対応の関数名を指定した場合は構文エラー（400）になります。関数名も大文字・小文字を区別しません。

※ 範囲を表す関数（THIS_WEEK() 〜 LAST_7_DAYS() / LAST_N_DAYS(n) / NEXT_N_DAYS(n)、上表で「〜の範囲」と説明されている行）は演算子 = としか組み合わせられません（!= / > 等と組み合わせると構文エラー（400）になります）。

order by / limit / offset

• order by field1 [asc|desc], field2 [asc|desc], ... — ソート順（最大5件）。既存の sorts / sortField パラメータとは併用できません（同時指定は400）
• limit N — 1ページの件数（perPage 相当。1〜500にクランプ、0は400エラー）。既存の perPage とは併用できません
• offset N — 開始位置（page 相当に変換）。実効ページサイズ（limit 句を指定していればその値、なければ既定値20）の倍数である必要があります（倍数でない場合は400）。既存の page とは併用できません

上限

• query 文字列全体: 4KB（4096バイト）まで
• 条件の合計数: 50件まで（in (...) の展開後の件数も含む）
• 括弧・グループのネスト深さ: 最大3階層
• 1階層あたりの子グループ数: 最大10
• not in (...) の値: 最大200件（超過は400エラー）
• offset の値: 最大100000（超過は400エラー）
• not in (...) の値リストには関数呼び出し（TODAY() 等）を指定できません（動的な値の解決対象外になり、意図せず全件一致してしまうのを防ぐための制限です。動的な除外条件が必要な場合は!= 条件を and で並べてください）
• not in ()（値0件）と in () は非対称です。not in () は「除外対象なし」＝全件一致として扱われますが、in () は値を1件も指定できないため400エラーになります

query はfilters /filterTree /filterMode /filter[フィールドコード] のいずれとも同時に指定できません（同時指定は400）。

filterTree パラメータ（JSON形式）

絞り込み条件をクエリ文字列ではなくJSON構造で直接組み立てたい場合は、filterTree パラメータを使用します。 入れ子の AND / OR グループを持つツリー構造（FilterNode）をJSON化して渡します。 上限（ネスト深さ3・条件合計50・1階層あたりグループ数10）は query と共通です。 JSON文字列自体のサイズにも上限があります（16KB（16384バイト）まで、超過は400エラー）。

{
  "mode": "and",
  "conditions": [
    { "field": "status", "operator": "eq", "value": "open" }
  ],
  "groups": [
    {
      "mode": "or",
      "conditions": [
        { "field": "priority", "operator": "eq", "value": "high" },
        { "field": "priority", "operator": "eq", "value": "urgent" }
      ]
    }
  ]
}

1条件の operator に指定できるのはeq /neq /gt /lt /gte /lte /contains /empty /not_empty /not_in（値は候補配列をJSON文字列化したもの）です。filterTree もfilters /filterMode /filter[フィールドコード] とは同時に指定できません（同時指定は400）。

実行例

# 例1: シンプルな条件（優先度が high のレコードを取得）
curl -G \
  -H "X-API-Token: YOUR_API_TOKEN" \
  --data-urlencode 'query=priority = "high"' \
  "https://example.com/api/apps/1/records"

# 例2: 括弧を使った入れ子条件
#（優先度が high または urgent、かつステータスが open のレコード）
curl -G \
  -H "X-API-Token: YOUR_API_TOKEN" \
  --data-urlencode 'query=(priority = "high" or priority = "urgent") and status = "open"' \
  "https://example.com/api/apps/1/records"

# 例3: order by / limit 付き
#（今月中が期限のレコードを、期限の昇順で先頭20件）
curl -G \
  -H "X-API-Token: YOUR_API_TOKEN" \
  --data-urlencode 'query=dueDate = THIS_MONTH() order by dueDate asc limit 20' \
  "https://example.com/api/apps/1/records"

# 例4: filterTree で同じ内容の絞り込みを JSON で組み立てる
curl -G \
  -H "X-API-Token: YOUR_API_TOKEN" \
  --data-urlencode 'filterTree={"mode":"and","conditions":[{"field":"status","operator":"eq","value":"open"}],"groups":[{"mode":"or","conditions":[{"field":"priority","operator":"eq","value":"high"},{"field":"priority","operator":"eq","value":"urgent"}]}]}' \
  "https://example.com/api/apps/1/records"

エラーコード（query / filterTree）

query /filterTree に関するエラーは、ステータス400と共に{ "error": "説明文", "code": "..." } の形式で返されます。

アプリ公開状態の切り替え

アプリの公開状態（published /suspended）の変更はPUT /api/apps/{appId}/status で行います。 このエンドポイントは APIトークンでは利用できません。アプリ管理者（admin）権限を持つユーザーのセッションでのみ呼び出せます。

リクエスト例

curlを使ったレコード取得の例:

# レコード一覧を取得（フィルタ付き）
curl -X GET \
  -H "X-API-Token: YOUR_API_TOKEN" \
  "https://example.com/api/apps/1/records?filter[priority]=high&perPage=10"

# JSON フィルタを使う例（複数条件）
curl -X GET \
  -H "X-API-Token: YOUR_API_TOKEN" \
  --data-urlencode 'filters=[{"field":"priority","operator":"eq","value":"high"}]' \
  -G "https://example.com/api/apps/1/records"

# レコードを作成
curl -X POST \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"title":"新規タスク","priority":"medium"}}' \
  "https://example.com/api/apps/1/records"

# レコードを更新（楽観ロック付き）
curl -X PUT \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"priority":"high"},"expectedHistoryVersion":3}' \
  "https://example.com/api/apps/1/records/42"

エラーコード