開発者ポータル

プログラム用 API & AI エージェント

標準 PostgREST エンドポイント、Supabase Edge Functions、および AI 連携用エンドポイントを介して、Nine ワークスペースのデータをクエリ、自動化、同期します。

AI エージェント、Gemini & LLM に最適化

MCP プロトコルllms.txt standard

独自の MCP (Model Context Protocol) サーバー、OpenAPI 3.0 仕様、および llms.txt コンテキストを介して、Nine を Google Gemini 接続アプリ、Claude Desktop、IDE エージェントに直接連携できます。

Google Gemini 接続アプリの設定

1. Gemini > 拡張機能 / 接続アプリ > カスタム接続アプリを設定を開きます。
2. 「カスタムアプリのリンクを追加」に MCP サーバー URL を入力します:
https://ninehoang.com/mcp?token=YOUR_API_TOKEN
3. Client ID と Client Secret は空欄のまま「次へ」をクリックします。

対応している MCP ツール

Tool Name	Description	Parameters
create_expense	Record an expenditure in the workspace ledger.	name (string), amount (number), category_id (enum), method_id (enum), occurred_at?, note?
list_expenses	Retrieve recent expense records with date filtering, category filter, search, and pagination (up to 1,000).	limit? (max 1000), offset?, category_id?, method_id?, start_date?, end_date?, search?
update_expense	Modify an existing expense (amount, category, vendor title, payment method, date, or notes).	id (uuid), name?, amount?, category_id?, method_id?, occurred_at?, note?
delete_expense	Permanently delete an expense record by its UUID.	id (uuid)
list_funds	List active collective funds, target budgets, and real-time balance totals.	none (returns all funds in workspace)
get_fund	Retrieve full details, budget targets, participants, and ledger for a specific fund.	fund_id (uuid)
create_fund	Create a new group fund (trips, sports seasons, event budgets).	name (string), kind? ('Travel' \| 'Badminton'), currency?, target_amount?, description?
update_fund	Update fund name, target goal, status ('Upcoming', 'In Progress', 'Completed'), or description.	fund_id (uuid), name?, status?, target_amount?, description?
create_fund_transaction	Record an income contribution or expense payout in a group fund.	fund_id (uuid), name (string), amount (number), category_id (enum), method_id (enum), occurred_at?
list_fund_transactions	Retrieve transactions and payouts across group funds with date filtering and pagination.	fund_id?, limit? (max 1000), offset?, category_id?, start_date?, end_date?
delete_fund_transaction	Delete a fund transaction record by its UUID.	id (uuid)
list_contacts	Query member roster and contact address book in the workspace with optional search.	search? (name, nickname, or phone query)
create_contact	Add a new member or participant to the workspace directory.	name (string), nickname?, phone?, email?, gender?, nationality?
update_contact	Update member information (name, nickname, phone, email).	id (uuid), name?, nickname?, phone?, email?

認証 & トークン交換

外部リクエストは2段階トークン交換で認証します。ワークスペースのベアラートークンを1時間有効な JWT に交換します。

Step 1: Exchange API Token for 1-hour JWT

curl -X POST \
  "https://pdkklibrvyqnatsqwtyg.supabase.co/functions/v1/api-token" \
  -H "Authorization: Bearer nh_ws_YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Step 2: Query PostgREST with Bearer JWT

curl "https://pdkklibrvyqnatsqwtyg.supabase.co/rest/v1/personal_transactions?select=*&order=occurred_at.desc&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "apikey: sb_publishable_gZdZ09nTdrxLCHPa36rXeg_6DraJ4Ps"

SDK & クイックスタート

標準のHTTPクライアント、JavaScript/TypeScript SDK、またはPythonを使用してワークスペースに接続します。

curl "https://pdkklibrvyqnatsqwtyg.supabase.co/rest/v1/personal_transactions?select=*&order=occurred_at.desc&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "apikey: sb_publishable_gZdZ09nTdrxLCHPa36rXeg_6DraJ4Ps"

リソースエンドポイント & スキーマ

厳格な Row Level Security 分離のもと、PostgREST 経由でワークスペースリソースに直接アクセスできます。

GETPOSTPATCHDELETE

/rest/v1/personal_transactions

Workspace expense ledger, spending records, and day-to-day outlays.

Field	Type	Description / Valid Options
id	uuid	Primary key identifier
name	text	Expense description / item (max 255 chars)
amount	numeric	Amount in workspace currency
category_id	enum	Options: 'food-drinks', 'entertainment', 'local-transport', 'clothing', 'beauty-care', 'sports', 'essentials', 'fixed-expenses', 'credit-repayment', 'installment-payment', 'family-support', 'travel', 'work-expenses', 'investments', 'other'. Read from `transaction_categories` (the rows offered to Expenses), so this list can grow without a deploy.
method_id	enum	Slugs from the transaction_methods table: 'cash', 'bank-transfer', 'mobile-wallet', 'credit-card', 'installment'. Read the live list from /openapi.json.
occurred_at	timestamptz	Date and time of transaction
note	text	Optional context or memo

HTTP ステータスコード & レート制限

PostgREST および Supabase Edge Functions から返される標準ステータスコード。

200 OK

Standard successful response for GET, PATCH, and DELETE operations.

201 Created

Resource successfully created (POST personal_transactions, funds, etc.).

400 Bad Request

Malformed JSON payload, out-of-bounds numbers, or invalid enum selection.

401 Unauthorized

Missing API token, expired 1-hour JWT, or token revoked via 0-ms kill switch.

403 Forbidden

Attempted to access an ungranted table (e.g. workspace_members, passwords).

429 Too Many Requests

Rate limit exceeded (60 req/min). Returns Retry-After header with wait seconds.

テナント分離 & セキュリティ

すべての API リクエストは Postgres Row Level Security (RLS) により厳格に分離されます。システム認証情報などの内部設定へのアクセスは完全に遮断されます。

Zero Cross-Tenant LeakPostgres RLS filters every table query automatically by workspace ID.

Excluded TablesWorkspace members, passwords, billing, and credentials are completely ungranted.

0-ms Instant Kill SwitchTurning off the workspace API switch revokes access across all external tokens instantly.

ワークスペースを連携する準備はできましたか？

ワークスペース設定から直接、読み取り専用または読み書き権限の API トークンを発行・管理できます。

ワークスペース API 設定へ