コンテンツへスキップ
オーラベースのロゴ
オーラベース

REST API — 概要

Aurabase 生の HTTP サーフェス。すべての言語に対応しています。ベース URL、認証、応答形式、エラー コード - /docs/api/ のエンドポイントごとの詳細。

リファレンス7 分 読み取りレベル 参照2026/04/15 に改訂

このページは自動翻訳されました。英語版が正式です。

原点、途中のプロジェクト#

URL は プロジェクトです。各プロジェクトは独自のサブドメイン https://<slug>.<apex> (ローカルでは http://<slug>.localhost:8080) で提供され、ゲートウェイはホストからプロジェクトを解決します。パスにはプロジェクト識別子は書き込まれません。 Studio › 設定 › 接続 にこの URL が表示され、NEXT_PUBLIC_AURABASE_URL がそれを保持します。ゲートウェイは、データ プラン (SDK とアプリケーション、ローカルの :8080 ) と管理プラン (スタジオと管理、 :8090) の 2 つのプランを公開します。データ プラン サーフェスには、 /v1/db、 /v1/auth、 /v1/storage、 /v1/realtime、 /v1/functions、 /v1/notifications、 /v1/aiというプレフィックスが付けられます。

examplesbash
# NEXT_PUBLIC_AURABASE_URL = プロジェクト URL (例: http://my-app-x1y2z3.localhost:8080)

GET   $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors
POST  $NEXT_PUBLIC_AURABASE_URL/v1/auth/login
GET   $NEXT_PUBLIC_AURABASE_URL/v1/storage/avatars/u_xx/file.png
POST  $NEXT_PUBLIC_AURABASE_URL/v1/functions/ocr/invoke
情報

パスにプロジェクト UUID を含むフォーム (エンドポイントのリファレンス ページにあるように/v1/db/{project_id}/sensors、 /v1/auth/{project_id}/login) は、プロジェクト URL およびベア ゲートウェイのオリジンで引き続き受け入れられます。これらは互換性のために保持されています。識別子に依存しない上記の形式を推奨します。

注意

ストリーミング ルート /v1/realtime/ws および /v1/realtime/sse は、プロジェクト ホスト上でそのまま提供されます。プロジェクトを識別しない URL (たとえば、プロジェクト識別子のないベア ゲートウェイ オリジン) は、 400として拒否されます。

キー 2 つ、JWT 1 つ#

  • anon_key — 公開可能。あらゆるリクエストの API キーとして機能します。ヘッダー apikey、 X-API-Key、またはパラメーター ?apikey= — 後者はリアルタイム ストリーム (/ws、 /sse、 /chat/stream) でのみ受け入れられます。それ以外の場合は明示的に拒否されます。
  • service_role_key — シークレット、RLS バイパス。バックエンド用に予約されています。
  • user_jwt — 認証後に POST /v1/auth/login によって発行されます。ヘッダー Authorization: Bearer。
headers.shbash
# 匿名のお客様(ゲスト)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

# 認証されたクライアント (ユーザーを要求)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

# バックエンド (RLS バイパス)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"

適用される規格#

  • Content-Type: application/json — POST/PATCH/PUT で必須 ( multipart/form-dataのアップロード ストレージを除く)
  • Prefer: return=representation — 作成または変更された行を返します。 本文のない応答の場合は return=minimal (204)。 Prefer: count=exact は aura-db の突然変異で読み取られます (ヘッダー Content-Range + Preference-Applied)。読み取り値に依存するには、?count=exact パラメーターを使用します。
  • Range: 0-49 — は、それ自体を解釈する PostgRESTによって提供される Postgres プロジェクト上の のみです。 aura-db パス (MongoDB プロジェクト、または PostgREST が無効になっている Postgres) は、この ヘッダーを無視します。つまり、 limit および offsetのみを読み取ります。両方のエンジンで動作する limit/offsetを優先します。
  • Idempotency-Key — はデータベースでは読み取られません (POST /v1/db/…) の書き込み: 2 つの同一の POST は 2 つの行を作成します。これは、 POST /v1/notifications/{project_id}/send (および /send/batch)、および管理プラン API キー (POST /v1/db/{project_id}/api-keys、24 時間枠) の作成によってのみ尊重されます。

リミット+オフセット#

pagination.shbash
# ポータブル形式のみ - 両方のエンジンで動作します
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# キーセット「手動」: 最後に読み取られたキーにフィルターを適用します
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: aura-db のみ (MongoDB、または PostgRESTのない Postgres )。
# PostgREST では、リクエストは 400 で拒否されます。
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
ヒント

limitを使用しない場合、読み取りでは最大 1000 行 が返されます。これはデフォルトであり、上限でもあります。クエリに実際に返されたスライスを超えて一致する行がある場合、meta.has_more は true になります (追加の行が存在しない場合、または最後のスライスに到達した場合は false になります)。 meta.totalも取得するには、 count=exact を要求します。

注意

エンジンによっては、合計が同じ場所で読み取られません。aura-db パスでは、応答にヘッダー Content-Range: items 100-149/1247 が含まれます (カウントが要求されなかった場合、合計は * の価値があります)。 PostgREST パスでは、ゲートウェイはこのヘッダーを中継せず、合計を JSON エンベロープの meta.total に入れます。デフォルトではカウントは行われません。パラメータ ?count=exact (移植可能な形式、 PostgREST パス上のゲートウェイによって Prefer に変換されます)、 ?count=planned、または ?count=estimatedを使用してリクエストします。

プロジェクトの OpenAPI 記述は GET /v1/db/{project_id}/openapi.json ( apikeyとともに) で提供されます。これはライブ スキーマから生成されるため、作成したばかりのテーブルがその中に表示されます。

統一フォーマット#

error は常にオブジェクトであり、文字列ではありません。発行者に応じた 2 つのバリアント - フィールド code と message は両方に共通であり、区別するのは code (決して message、フリー テキスト) です。

Aurabase サービスによって発行されたエラーjson
{
  "error": {
    "type": "auth_unauthorized",      // マシンタイプ、ドメインの接頭辞付き
    "code": "UNAUTHORIZED",         // 安定したコード
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
ゲートウェイによって変換された PostgREST エラーjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // 生の PGRST コードは決して使用しないでください
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
注意

PostgREST/PostgreSQL コード (PGRST116、 23505…) は であり、REST API によって がそのまま返されることはありません。ゲートウェイはそれらを Aurabase コード (RECORD_NOT_FOUND、 NOT_SINGULAR、 COLUMN_NOT_FOUND、 NO_RELATIONSHIP、 SCHEMA_NOT_FOUND、 DUPLICATE_KEY、 FOREIGN_KEY_VIOLATION、 CHECK_VIOLATION、 INVALID_INPUT、 NUMERIC_OUT_OF_RANGE、 INVALID_BODY、 TABLE_NOT_FOUND、 FUNCTION_NOT_FOUND、 INSUFFICIENT_PRIVILEGE、 STATEMENT_TIMEOUT、 DB_POOL_TIMEOUTそれ以外の場合は POSTGREST_ERROR)。このバリアントには typeがありません。呼び出し元によって修正できるエラーの場合は、hint が追加されます (列または関数が欠落している場合は最も近い名前が提案され、RLS が拒否された場合は create policy が追加されます)。 JavaScript SDK は、 supabase-jsとの互換性のために、意図的に .single() / .maybeSingle() の PGRST116 を保持します。生の HTTP では、同じ状況が NOT_SINGULARになります。

コード名前説明
400不正なリクエスト不正な形式のペイロードまたはクエリ。 error.code は BAD_REQUESTです。
401無許可apikeyが欠落しているか取り消されているか、無効な JWTです。 error.code は UNAUTHORIZED、または /refreshの REFRESH_TOKEN_REJECTED です。
403禁止RLS または認可サービスが操作を拒否しました。 error.code は、 FORBIDDEN、 QUOTA_EXCEEDED 、または INSUFFICIENT_PRIVILEGE (PostgREST パス) です。
404見つかりませんリソースが存在しないか、RLS によって非表示になります。 error.code は、 NOT_FOUND、 RECORD_NOT_FOUND 、または TABLE_NOT_FOUNDです。
406受け入れられない1 行が予期されていましたが、複数の行が返されました。 error.code は NOT_SINGULARです。
409紛争一意キーまたは外部キー違反。 error.code は、 CONFLICT、 DUPLICATE_KEY 、または FOREIGN_KEY_VIOLATIONです。更新/挿入には on_conflict を使用します。
413ペイロードが大きすぎますMAX_BODY_SIZE (ゲートウェイのデフォルトでは 50 MB) より大きいリクエスト。マルチパート ストレージ アップロードを使用します。
429リクエストが多すぎますレート制限に達しました。 error.code は RATE_LIMITEDです。 message は、ヒットした制限 (IP、プロジェクト、または API キー) を指定し、hint は再試行する時期を示します。 X-RateLimit-Limit および X-RateLimit-Remaining ヘッダーが設定され、ゲートウェイ拒否では Retry-After が設定されます。
500内部サーバーエラーサーバーエラー。 error.request_id をサポートしてください。
503サービスが利用できませんゲートウェイが負荷を軽減している場合は SERVER_BUSY (実行中のリクエストが多すぎる場合、 Retry-After: 1)、プロジェクトの接続プールが飽和状態のままである場合、サーキット ブレーカーが開いている場合、インスタンスが見つからない場合、またはプロジェクトが休止状態である場合は DB_POOL_TIMEOUT (この場合はRetry-After: 5 )。ブレーカーは 30 秒後に再試行します。
504ゲートウェイのタイムアウトアップストリームのタイムアウト。 SQL ステートメントがプロジェクトのステートメント タイムアウトの 10 秒を超えて実行された場合、 error.code は TIMEOUTまたは STATEMENT_TIMEOUT になります。

ゲートウェイの IP による、さらにルートごとの制限#

  • プロジェクトおよび API キーごと: プロジェクトの計画の制限 (スタジオ › 設定 › 使用法)。 429 はヒットしたスコープに名前を付けるため、速度を落とすかアップグレードするかを判断できます。
  • ゲートウェイ、すべてのルート: IP ごとに、デフォルトで 1000 のバーストを含む 100 要求/秒 ( RATE_LIMIT_RPS / RATE_LIMIT_BURST経由で調整可能)。役割ごとに個別の階層はありません。
  • 認証に敏感な (login、 register、 forgot-password、 magic-link、 email-otp/send、 sms/send、 refresh、 mfa/verify-login): IP ごとに 5 要求/分、バースト 3。さらに、プロジェクトごとのクォータ: 30 接続デフォルトでは IP ごとの試行/時間数ですが、プロジェクト設定で調整できます。開発中 (AURA_ENV=development、ローカル スタック)、ルーターの制限が緩和され (バースト 100)、反復できるようになります。 Studio › Authentication › Configuration › Rate Limiting に表示されるプロジェクト クォータは常に適用されます。
  • Raw SQL (/raw): 30 要求/分、バースト 10。 IA: 10 要求/分、バースト 5。
注意

オーバーフロー → ヘッダー X-RateLimit-Limit および X-RateLimit-Remaining (ゲートウェイからの応答に存在) を含む 429 Too Many Requests、および拒否時の X-RateLimit-Reset および Retry-After。

サービスごとの完全なツリー#

各エンドポイントには、パラメーター、応答コード、5 か国語の例、ライブ レール コードを含む専用ページがあります。

データベース認証ストレージリアルタイム関数

あなたの言語用の SDK はまだありません#

Python や Dart パッケージはまだ公開されていません (スタジオもそう言っています)。上記の REST API は完成しているため、クライアントは数行です。 Python バージョンは標準ライブラリのみを使用します。他の例と同じ変数を読み取り、API エラーを安定した code および request_idを運ぶ例外に変換します。

aurabase_rest.pypython
import json, os, urllib.error, urllib.request

URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"]  # またはサーバー上の AURABASE_SERVICE_ROLE_KEY


def get(path):
    request = urllib.request.Request(URL + path, headers={"apikey": KEY})
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return json.load(response)
    except urllib.error.HTTPError as e:
        error = json.load(e)["error"]
        raise RuntimeError(f'{error["code"]}: {error["message"]} (request_id {error.get("request_id")})')


print(get("/v1/db/todos?limit=2"))

Dart バージョン (Flutter またはサーバー) にもパッケージは必要ありません。 dart run aurabase_rest.dartで実行します。

aurabase_rest.dartdart
import 'dart:convert';
import 'dart:io';

final url = Platform.environment['NEXT_PUBLIC_AURABASE_URL']!;
final key = Platform.environment['NEXT_PUBLIC_AURABASE_ANON_KEY']!; // or AURABASE_SERVICE_ROLE_KEY on a server

Future<dynamic> get(String path) async {
  final client = HttpClient();
  try {
    final request = await client.getUrl(Uri.parse(url + path));
    request.headers.set('apikey', key);
    final response = await request.close();
    final body = jsonDecode(await response.transform(utf8.decoder).join());
    if (response.statusCode >= 400) {
      final error = body['error'];
      throw Exception('${error['code']}: ${error['message']} (request_id ${error['request_id']})');
    }
    return body;
  } finally {
    client.close();
  }
}

Future<void> main() async {
  print(await get('/v1/db/todos?limit=2'));
}

さらに進むには#