开发者门户
编程式 API 与 AI 智能体
通过标准 PostgREST 端点、Supabase Edge Functions 以及面向 AI 的标准接口，查询、自动化和同步您的 Nine 工作区数据。
专为 AI 智能体、Gemini 与大模型构建
MCP 协议llms.txt standard通过原生 Model Context Protocol (MCP) 服务器、OpenAPI 3.0 规范和 llms.txt 上下文，将 Nine 直接连接至 Google Gemini Connected Apps、Claude Desktop 和各类 AI 智能体。
Google Gemini Connected App 配置步骤
- 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? |
认证与令牌兑换
外部请求采用双层认证流程：使用工作区长期令牌兑换有效期为 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| 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 返回的标准 HTTP 状态码。
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 令牌。