ベース URL・ページネーション・バッチ取得・エラーレスポンスなど、Speria REST API 共通のルール

概要

このページでは Speria REST API 全体に共通するルールを説明します。

各エンドポイントの詳細は、サイドバーの API セクションから参照してください（OpenAPI 仕様から自動生成しています）。

ベース URL

https://api.speria.jp

データアクセス系のエンドポイントは、対象の Workspace をパスに含みます。

/v1/workspaces/{workspace_id}/{resource}

workspace_id は API キー／App がアクセスを許可されている Workspace である必要があります。アクセスできない Workspace を指定した場合、403 ではなく 404 を返します（Workspace の存在自体を秘匿するため）。

認証方法は認証を参照してください。

一覧を返すエンドポイントはカーソル方式のページネーションを使います。ページ番号（offset）方式は、ページ送りの途中で対象が消えるとスキップが起きるため採用していません。

GET /v1/workspaces/{workspace_id}/customers?per_page=100&after=01ABC...

パラメータ	説明
`per_page`	1 件以上 100 件以下。デフォルト 30。範囲外の値は丸められます
`after`	前ページ最後の要素の `id`。これより大きい `id` の要素を返します

レスポンス:

{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "01ABC..."
  }
}

要素は id の昇順で返ります（id は時系列順の ULID です）
pagination.has_more が true の場合、pagination.next_cursor の値を次のリクエストの after に渡してください
次のページがない場合、pagination.next_cursor は null になります

App 管理エンドポイント（GET /v1/workspaces/{workspace_id}/apps）のみ、過去の経緯から { "apps": [ ... ], "has_more": true } という異なる形状を返します。上記の共通形式には従いません。

一部のリソースは、複数の ID をまとめて指定して一括取得できます。

GET /v1/workspaces/{workspace_id}/customers/batch?ids=01ABC...,01DEF...

レスポンスの data に、各リソースの単体取得（GET .../customers/{id}）と同じ形状のオブジェクトの配列が入ります。トップレベルは配列ではなくオブジェクトです。

{
  "data": [
    { "id": "01ABC...", "name": "..." },
    { "id": "01DEF...", "name": "..." }
  ]
}

ids は必須です。カンマ区切りで指定します
結果は指定した ids と同じ順序で返ります
存在しない ID は data から除外されます。リクエスト自体は 200 で成功します。欠損は「指定した ids」と「返却された data の id」の差分で判定してください
無効化済み（deactivated）のリソースの扱いは単体取得と同じです
- customers / customer_visits / staffs: 無効化済みのリソースも含まれます（deactivated_at で状態を判定できます）
- analyses: 有効な分析ソースのみが対象です。無効化済みのものは data から除外されます
ページネーションは適用されません（pagination は返りません）
1 リクエストで指定できる ID 数の上限はエンドポイントごとに異なります。上限を超えた場合は 422 validation_failed を返し、メッセージに上限値が含まれます。各エンドポイントの上限は API リファレンスを参照してください

エラー時は HTTP ステータスコードとあわせて、次の形式の JSON を返します。

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the `customers:read` scope"
  }
}

code はプログラムから判定するための安定した識別子です。message は人間向けの説明であり、予告なく変更される可能性があるため分岐条件に使わないでください。

一部のエンドポイントは、これに加えて固有のエラーコードを返します（例: 音声アップロードの invalid_content_type、upload_blob_not_found など）。各エンドポイントで返りうるコードは API リファレンスを参照してください。

アクセスできないリソースは、403 ではなく 404 not_found を返します。「存在しない」と「アクセス権がない」を区別しないため、レスポンスからリソースの存在有無を判定することはできません。

POST /oauth/token は RFC 6749 に準拠した別形式を返します。

{
  "error": "invalid_grant",
  "error_description": "..."
}