AI GO System Integration Guide

This document comprehensively explains how third-party applications (Integrations) can connect to the AI GO system via "References" and APIs, covering all referencable API Endpoints, Tables, Custom Tables (dynamic data tables), Schemas, and field definitions.

1. System Overview and Architecture

1.1 System Positioning

AI GO is an enterprise-grade PaaS ERP platform offering comprehensive modules for Accounting, Sales, Procurement, Inventory, CRM, HR, MRP, Project Management, etc. Through the Integration mechanism, third-party developers can build Self-Built Apps to securely access enterprise data within AI GO.

1.2 Three Application Access Modes

This document focuses on the Self-Built mode, which is the core use case for third-party integrations.

1.3 Overall Architecture Flow

sequenceDiagram
    participant Dev as Developer (Admin)
    participant AIGO as AI GO API
    participant App as Third-Party App

    Note over Dev,App: === Stage 1: Create Integration ===
    Dev->>AIGO: POST /integrations (Create Self-Built App)
    AIGO-->>Dev: Returns app_id, slug

    Dev->>AIGO: POST /integrations/{app_id}/api-keys (Generate API Key)
    AIGO-->>Dev: Returns sk_live_xxx... (Once only)

    Note over Dev,App: === Stage 2A: Configure System Table References ===
    Dev->>AIGO: GET /refs/available-tables (Check available tables)
    Dev->>AIGO: GET /refs/tables/{name}/columns (Check fields)
    Dev->>AIGO: POST /refs/apps/{app_id} (Create reference + set permissions)

    Note over Dev,App: === Stage 2B: Create Custom Table ===
    Dev->>AIGO: Create Custom Table and fields via AI GO Admin UI

    Note over Dev,App: === Stage 3: Publish ===
    Dev->>AIGO: POST /integrations/{app_id}/publish (Publish reference config)
    AIGO-->>Dev: Snapshots columns + permissions as published version

    Note over Dev,App: === Stage 4: Access Data ===
    App->>AIGO: GET /open/proxy/{table} (System tables)
    AIGO-->>App: Returns data for authorized fields (tenant isolated)
    App->>AIGO: GET /open/data/objects/{slug}/records (Custom Table)
    AIGO-->>App: Returns Custom Table records (tenant isolated)

2. Authentication Mechanisms

2.1 API Key Server-to-Server Authentication

Ideal for backend-to-backend communication for Self-Built applications.

API Key Format: sk_live_ + 64-character hexadecimal random string

Usage: Include it in the Header of every HTTP request:

X-API-Key: sk_live_a1b2c3d4e5f6...

Validation Flow:

The system automatically validates the API Key and its associated application, extracting the app_id and tenant_id without requiring them to be passed manually. Invalid or revoked keys return 401 Unauthorized.

Security Recommendations:

• The API Key is only returned as plaintext once upon creation. Keep it secure.
• Store the Key in environment variables or a secret management service; do not hardcode it.
• Rotate Keys regularly (revoke old Key ??create new Key).
• A single integration can have multiple Keys (e.g., separating Production and Staging).

2.2 Custom App User Authentication

The AI GO platform provides a complete, independent user authentication system for self-built integrations, including:

• Email + Password: Registration / Login
• OAuth Third-Party Login: LINE, Google, Facebook, etc. (See 禮2.4)
• JWT Access Token + Refresh Token Rotation
• Builder-side User Management: Enable / Disable / Delete

Important: In Independent mode, third-party developers do not need to build their own authentication system. AI GO provides ready-to-use Auth APIs; developers simply call these endpoints to achieve complete user registration and login functionalities for their apps.

2.3.1 Authentication Flow Overview

sequenceDiagram
    participant User as End User
    participant App as Third-Party Frontend
    participant AIGO as AI GO API

    alt Email + Password
        User->>App: Fill registration / login form
        App->>AIGO: POST /custom-app-auth/{slug}/register or login
        AIGO-->>App: { access_token, refresh_token, user }
    else OAuth Login (e.g., LINE)
        User->>App: Click LINE login
        App->>AIGO: GET /custom-app-oauth/{slug}/line/authorize
        AIGO-->>User: 302 Redirect to LINE authorization page
        User->>AIGO: Authorization callback
        AIGO-->>App: 302 redirect?oauth_token=<base64 encoded tokens>
    end

    Note over App: Store access_token + refresh_token

    App->>AIGO: GET /custom-app-auth/{slug}/me (Bearer Token)
    AIGO-->>App: { user info }

    Note over App: When Token is about to expire
    App->>AIGO: POST /custom-app-auth/{slug}/refresh
    AIGO-->>App: { new access_token, new refresh_token }

Path Note: All Custom App User authentication endpoints use app_slug (not app_id) as the path parameter. The slug can be found next to the title on the integration details page (a 12-character hex string). The system also supports using subdomain instead of slug.

2.3.2 Register

POST /api/v1/custom-app-auth/{app_slug}/register

Auth: No Auth Required (Public Endpoint)

Request Body:

{
  "email": "user@example.com",
  "password": "my_secure_password",
  "display_name": "John Doe"
}

Response 201 Created:

{
  "access_token": "eyJhbGciOiJIUzI1NiI...",
  "refresh_token": "a1b2c3d4e5f6...",
  "expires_in": 900,
  "token_type": "Bearer",
  "user": {
    "id": "uuid",
    "custom_app_id": "uuid",
    "tenant_id": "uuid",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": null,
    "extra_data": {},
    "is_active": true,
    "last_login_at": null,
    "created_at": "2026-04-01T00:00:00Z",
    "updated_at": null
  }
}

Error Codes:

2.3.3 Login

POST /api/v1/custom-app-auth/{app_slug}/login

Auth: No Auth Required (Public Endpoint)

Request Body:

{
  "email": "user@example.com",
  "password": "my_secure_password"
}

Response 200 OK: Same format as the Response for 禮2.3.2 Register

Error Codes:

2.3.4 Get Current User (Me)

GET /api/v1/custom-app-auth/{app_slug}/me

Auth: Bearer Token (Access Token)

Authorization: Bearer eyJhbGciOiJIUzI1NiI...

Response 200 OK:

{
  "id": "uuid",
  "custom_app_id": "uuid",
  "tenant_id": "uuid",
  "email": "user@example.com",
  "display_name": "John Doe",
  "avatar_url": "https://...",
  "extra_data": {},
  "is_active": true,
  "last_login_at": "2026-04-01T12:00:00Z",
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": null
}

Error Codes:

2.3.5 Refresh Token

POST /api/v1/custom-app-auth/{app_slug}/refresh

Auth: No Bearer Token Required (Public endpoint, requires refresh_token in Body)

Request Body:

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Response 200 OK: Same format as the Response for 禮2.3.2 Register (Contains new access_token and refresh_token)

?? Token Rotation: Upon successful refresh, the old Refresh Token is immediately invalidated (revoked). You must store and use the newly returned refresh_token.

Error Codes:

2.3.6 Logout

POST /api/v1/custom-app-auth/{app_slug}/logout

Auth: Bearer Token (Access Token)

Request Body:

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Response 200 OK:

{
  "message": "Logged out"
}

2.3.7 ext/ Endpoints: Custom App User API

The following endpoints require Custom App User Token (Bearer) authentication and are used for Independent mode frontends directly accessing data:

Usage:

# Access system tables using Custom App User Token
curl -H "Authorization: Bearer <access_token>" \
     https://api.ai-go.app/api/v1/ext/proxy/customers

# Access Custom Tables using Custom App User Token
curl -H "Authorization: Bearer <access_token>" \
     https://api.ai-go.app/api/v1/ext/data/objects/group_tour/records

Difference from Open Proxy:

• /ext/* endpoints use Bearer Tokens (Custom App User Token). tenant_id and custom_app_id are automatically parsed from the Token payload.
• /open/* endpoints use API Keys (X-API-Key). Suitable for backend Server-to-Server calls.
• Both share the same reference whitelists and data filtering engines.

2.3.8 Domain Whitelist (Origin Check)

Once allowed_origins is configured, Custom App Auth endpoints (register / login, etc.) check the HTTP Origin header:

?? Port Note: The Port is part of the Origin (RFC 6454), e.g., http://localhost:3000 ??http://localhost:8000. Ensure the whitelist includes the complete scheme://host:port.

2.3.9 Builder-side User Management API

The following endpoints allow integration administrators (Builders) to manage Custom App users via the AI GO Management UI. They require main site JWT authentication (builder.access permission):

Upon disabling or deleting a user, their authentication cache is cleared immediately. Any issued Access Tokens will become invalid after the cache TTL (60 seconds) expires.

2.3 OAuth Third-Party Login (LINE, etc.)

Self-built integrations can be additionally configured with OAuth Providers (e.g., LINE Login) allowing end users to log in directly via third-party accounts.

2.4.1 Prerequisites

The Builder must configure the OAuth Provider for the App within the AI GO Management Interface:

1. Go to Integration Management ??Select App ??Settings Tab
2. Enter the Provider's Client ID and Client Secret (Stored encrypted via AES-256)
3. In the third-party platform (e.g., LINE Developers Console), configure the Callback URL as:

https://<YOUR_API_HOST>/api/v1/custom-app-oauth/{app_slug}/{provider}/callback

2.4.2 OAuth Endpoints List

Currently supported provider values: line (LINE Login). Frameworks for Google, Facebook, GitHub, etc., are in place.

2.4.3 OAuth Login Flow

sequenceDiagram
    participant User as End User
    participant App as Third-Party Frontend
    participant AIGO as AI GO API
    participant LINE as LINE Login

    App->>AIGO: GET /{slug}/auth-providers
    AIGO-->>App: [{ "provider": "line" }]

    User->>App: Click LINE Login Button
    App->>AIGO: GET /{slug}/line/authorize
    AIGO-->>User: 302 ??LINE Authorization Page
    User->>LINE: Agree to authorize
    LINE-->>AIGO: callback?code=xxx&state=yyy

    alt Has email
        AIGO-->>App: 302 ??{app_url}?oauth_token=<base64>
        Note over App: base64 decode yields<br/>{ access_token, refresh_token, user }
    else No email
        AIGO-->>App: 302 ??{app_url}?oauth_pending=<token>
        App->>User: Display form to supply email
        User->>App: Enter email
        App->>AIGO: POST /{slug}/oauth/complete-email
        AIGO-->>App: { access_token, refresh_token, user }
    end

2.4.4 OAuth Token Transmission Method

Upon successful OAuth login, the system returns tokens to the App's live_url via query parameters:

Frontend Decoding Example:

// Decode token upon successful OAuth login
const params = new URLSearchParams(window.location.search);
const encoded = params.get('oauth_token');
if (encoded) {
  const decoded = JSON.parse(atob(encoded));
  // decoded = { access_token, refresh_token, expires_in, user }
  localStorage.setItem('access_token', decoded.access_token);
  localStorage.setItem('refresh_token', decoded.refresh_token);
}

2.4.5 OAuth Account Binding Behavior

?? OAuth users have a null password_hash and cannot log in using Email + Password. If password login is required, the user must set a password separately.

2.4 Token Technical Specifications

Token mechanism used for Custom App User authentication:

Access Token JWT Payload Example

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "custom_app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "11111111-2222-3333-4444-555555555555",
  "auth_type": "custom_app_user",
  "scope": "app_runtime",
  "iat": 1711929600,
  "exp": 1711930500
}

Key Distinction: The auth_type field is fixed to "custom_app_user", which /ext/* endpoints use to verify identity.

2.4.1 Quick Start: Complete Integration in 30 Minutes

Here are the minimal steps for end-to-end integration:

Step 1 ??Create Integration and Get API Key:

# Create a new integration in the AI GO Admin Interface
# Obtain the app_slug (e.g., e9abbb866184) and API Key (e.g., sk_live_xxx)

Step 2 ??Configure Domain Whitelist:

Add the frontend Origin (e.g., https://myapp.example.com) to the whitelist in the Settings Tab.

Step 3 ??Frontend Integration Example (JavaScript):

const API_BASE = 'https://api.ai-go.app/api/v1';
const APP_SLUG = 'e9abbb866184';

// ?€?€ 1. User Registration ?€?€
async function register(email, password, displayName) {
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password, display_name: displayName }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  // Store tokens
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data.user;
}

// ?€?€ 2. User Login ?€?€
async function login(email, password) {
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data.user;
}

// ?€?€ 3. Fetch Data using Token ?€?€
async function fetchCustomers() {
  const token = localStorage.getItem('access_token');
  const res = await fetch(`${API_BASE}/ext/proxy/customers`, {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return res.json();
}

// ?€?€ 4. Refresh Tokens ?€?€
async function refreshTokens() {
  const refreshToken = localStorage.getItem('refresh_token');
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refresh_token: refreshToken }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  // ?? Must update both tokens (Token Rotation)
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data;
}

Step 4 ??Backend Server-to-Server Data Access (Python):

import requests

API_KEY = 'sk_live_a1b2c3d4...'
API_BASE = 'https://api.ai-go.app/api/v1'

# Access data directly using API Key (does not involve user authentication)
resp = requests.get(
    f'{API_BASE}/open/proxy/customers',
    headers={'X-API-Key': API_KEY},
)
print(resp.json())

3. Integration Management API

Prefix: /api/v1/integrations Auth: Main Site JWT (requires builder.access permission)

3.1 List All Integrations

GET /api/v1/integrations

Response 200 OK:

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "name": "My ERP Integration",
    "slug": "e9abbb866184",
    "subdomain": "my-erp",
    "live_url": "https://my-erp.example.com",
    "allowed_origins": ["https://my-erp.example.com"],
    "api_key_count": 2,
    "created_at": "2026-03-01T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z"
  }
]

3.2 Create New Integration

POST /api/v1/integrations

Response 201 Created: IntegrationDetail object

3.3 Get Integration Details

GET /api/v1/integrations/{app_id}

Response 200 OK:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "name": "...",
  "slug": "...",
  "subdomain": null,
  "live_url": null,
  "allowed_origins": [],
  "access_mode": "self_built",
  "created_at": "...",
  "updated_at": "..."
}

3.4 Rename

PATCH /api/v1/integrations/{app_id}/name

3.5 Update Settings

PATCH /api/v1/integrations/{app_id}/settings

3.6 Delete Integration

DELETE /api/v1/integrations/{app_id}

Response 204 No Content (also deletes all associated API Keys)

3.7 API Key Management

List API Keys

GET /api/v1/integrations/{app_id}/api-keys

Response 200 OK:

[
  {
    "id": "uuid",
    "app_id": "uuid",
    "key_prefix": "sk_live_a1b2",
    "name": "Production Key",
    "is_active": true,
    "last_used_at": "2026-03-20T12:00:00Z",
    "expires_at": null,
    "created_at": "2026-03-01T00:00:00Z"
  }
]

Create API Key

POST /api/v1/integrations/{app_id}/api-keys

Response 201 Created:

{
  "id": "uuid",
  "app_id": "uuid",
  "key_prefix": "sk_live_a1b2",
  "name": "Production Key",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8...",
  "created_at": "..."
}

?? The api_key field is only returned once upon creation; please save it securely immediately.

Revoke API Key

DELETE /api/v1/integrations/{app_id}/api-keys/{key_id}

Response 204 No Content

3.8 Publish Approval Workflow

After modifying reference configurations, they must be "Published" before taking effect in the Open Proxy.

Publish Integration

POST /api/v1/integrations/{app_id}/publish

Behavior:

• With builder.publish permission ??Publishes directly (auto-approved)
• Without builder.publish permission ??Creates a pending request awaiting review

List Publish Requests

GET /api/v1/integrations/{app_id}/publish-requests

Approve / Reject / Cancel Publish Request

POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/approve
POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/reject
POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/cancel

• approve: Requires builder.publish permission
• reject: Requires builder.publish permission, Body: { "reject_reason": "..." }
• cancel: Only the requester can cancel

Get Publish Status

GET /api/v1/integrations/{app_id}/publish-status

Response:

{
  "can_publish": true,
  "is_locked": false,
  "pending_request": null,
  "published_at": "2026-03-20T00:00:00Z"
}

4. Reference System API

Prefix: /api/v1/refs Auth: Main Site JWT (requires builder.access permission)

A Reference is the core data authorization mechanism in AI GO. Every integration must first establish references specifying which tables and fields it intends to access, and what operational permissions it holds.

4.1 List Referencable Tables

GET /api/v1/refs/available-tables

Response 200 OK:

[
  { "name": "customers", "comment": "Customer" },
  { "name": "sale_orders", "comment": "Sales Order" },
  { "name": "product_products", "comment": "" }
]

4.2 Get Table Field Information

GET /api/v1/refs/tables/{table_name}/columns

Response 200 OK:

[
  {
    "name": "name",
    "type": "VARCHAR",
    "nullable": false,
    "is_system": false
  },
  {
    "name": "email",
    "type": "VARCHAR",
    "nullable": true,
    "is_system": false
  },
  {
    "name": "customer_id",
    "type": "UUID",
    "nullable": true,
    "is_system": false,
    "is_fk": true,
    "fk_target": "customers.id"
  }
]

4.3 Reference CRUD

List All References for an App

GET /api/v1/refs/apps/{app_id}

Create Reference

POST /api/v1/refs/apps/{app_id}

Update Reference

PATCH /api/v1/refs/{ref_id}

Delete Reference

DELETE /api/v1/refs/{ref_id}

4.4 Permission Values Explanation

4.5 Unreferencable Tables

System core tables (e.g., authentication, tenant management, permission settings, audit logs, etc.) can never be referenced due to security reasons. Attempting to reference these tables will return a 403 Table is not referencable error via the API.

Please use the GET /api/v1/refs/available-tables API to query the list of tables that can be referenced.

4.6 System Fields

The following fields are automatically managed by the system and will be automatically excluded when writing:

4.7 Shared Business Field: custom_data (JSONB)

All functional data tables contain a custom_data field, designed specifically for third-party applications to store custom data specific to their business operations.

Usage: Include custom_data in the columns list when creating the reference:

{
  "table_name": "customers",
  "columns": ["id", "name", "email", "custom_data"],
  "permissions": ["read", "create", "update"]
}

?? If custom_data is not included in the referenced columns, the App will not see this field when reading, and it will be automatically ignored when writing.

5. Data Proxy API (Open Proxy)

Prefix: /api/v1/open/proxy Auth: API Key (X-API-Key Header) Data Isolation: Automatic row-level filtering based on the tenant_id associated with the Key Reference Version: Uses the published reference snapshot

5.0 Three Proxy Endpoints Comparison

The system provides three sets of Proxy endpoints that share the same core query engine. The differences lie solely in authentication methods and reference versions:

Important: Self-Built Apps accessing via the Open Proxy also fully support advanced query functionalities (filters, search, order_by, select, count_only, etc.), not just limit / offset. Simply use POST /{table_name}/query.

External Proxy Auth Note: The External Proxy (/ext/proxy/) requires Custom App User Token (Bearer) authentication, suitable for Independent mode frontends directly accessing data. See 禮2.3 Custom App User Authentication for obtaining tokens.

5.1 Simple Query

GET /api/v1/open/proxy/{table_name}?limit=100&offset=0

Response 200 OK:

[
  {
    "id": "uuid",
    "name": "Customer A",
    "email": "a@example.com",
    "phone": "0912345678"
  }
]

5.2 Advanced Query

POST /api/v1/open/proxy/{table_name}/query

Request Body:

{
  "filters": [
    { "column": "status", "op": "eq", "value": "active" },
    { "column": "amount_total", "op": "gte", "value": 1000 }
  ],
  "order_by": [
    { "column": "created_at", "direction": "desc" }
  ],
  "search": "keyword",
  "search_columns": ["name", "email"],
  "select_columns": ["id", "name", "email"],
  "limit": 50,
  "offset": 0,
  "count_only": false
}

Filter Operators

Filter Combination Logic

• Multiple filters are combined using AND.
• OR combinations are not supported (Exception: The search feature applies OR across multiple search columns).
• Nested grouped conditions are not supported (e.g., (A AND B) OR (C AND D)).
• For a BETWEEN effect, combine gte + lte filters.

Example ??Query sales orders with amount >= 1000 AND state is active:

{
  "filters": [
    { "column": "amount_total", "op": "gte", "value": 1000 },
    { "column": "state", "op": "eq", "value": "sale" }
  ]
}

Search Full-Text Behavior

• search executes ILIKE '%keyword%' on search_columns (or all authorized non-id fields).
• Multiple search columns are combined using OR (matches if any field hits).
• Combining search with filters applies an AND operation (both must be satisfied).
• Field values are cast to the text type during search, meaning numeric or UUID fields can also be searched.

count_only Mode

When setting "count_only": true, the endpoint only returns the total record count matching the conditions (both filters and search apply):

{ "total": 42 }

5.3 Insert Record

[!WARNING] Proxy API Operations Do Not Trigger Business Document Auto-Generation (Workflow Triggers) Inserting or updating business data via the Proxy API (e.g., changing an order state to sale) will not automatically generate subsequent documents (like auto-generating delivery orders or invoices). The Proxy API acts purely as a "data-layer proxy." Third-party applications must explicitly INSERT all related documents, though the system will automatically maintain specific fields (like invoiced quantity, payment status, etc.). Refer to Chapter 8 for the "Auto-Trigger Workflows (Triggers)" of each table.

POST /api/v1/open/proxy/{table_name}

Request Body:

{
  "name": "New Customer",
  "email": "new@example.com",
  "phone": "0912345678",
  "custom_data": {
    "passport_no": "A123456789",
    "travel_pref": ["eco", "window_seat"]
  }
}

custom_data accepts any JSON structure (objects, arrays, nested).

Response 201 Created:

{
  "id": "uuid",
  "created_at": "2026-03-24T00:00:00Z",
  "data": {
    "name": "New Customer",
    "email": "new@example.com",
    "custom_data": "{\"passport_no\": \"A123456789\"}"
  }
}

tenant_id is automatically injected by the system and is not required manually.

5.4 Update Record

PATCH /api/v1/open/proxy/{table_name}/{row_id}

Request Body:

{
  "name": "Updated Name",
  "phone": "0987654321"
}

Response 200 OK:

{ "id": "uuid", "updated": true }

5.5 Delete Record

DELETE /api/v1/open/proxy/{table_name}/{row_id}

Response 204 No Content

5.6 Automatic Type Conversion

The Proxy automatically casts strings into their corresponding PostgreSQL types:

?? UUID Field Notes:

• All fields ending in _id (e.g., product_id, order_id) will automatically attempt to cast to the UUID type upon writing.
• If the value is an empty string "", the system automatically casts it to NULL (avoiding PostgreSQL type errors).
• If the value is not a valid UUID format (e.g., LINE ID U1234567890), the original string is preserved.

5.7 AI GO Approval Workflow Integration

? Applies to: POST, PATCH, DELETE, or any Proxy operation that modifies data.

AI GO provides a flexible approval workflow engine. When system administrators configure an approval workflow for specific tables (e.g., sale_orders) in the backend, your Proxy API calls will automatically be intercepted and reviewed by the approval system.

Interception and API Bypass Mechanism

1. Standard Case (Interception): When an approval flow is triggered, the API operation does not take effect directly. Instead, the system will:
   • For POST (Insert-then-flag): Insert the unvalidated record first, ensuring an ID is generated for referencing.
   • For PATCH / DELETE (Pre-guard): Completely pause the actual database mutation, encapsulating the changed content into an "Approval Request" pending a decision.
   • Your API call will receive a response indicating approval_status: "pending".
2. API Bypass: If administrators enable the "Allow API Bypass" option for the corresponding workflow in the backend, third-party APIs can ignore approval rules and forcefully write data. The system only records a Bypass Audit Log in the background for future auditing.

Response Format When Intercepted

When bypass is not enabled and the operation triggers an approval condition, the API does not return the standard success format, but rather:

Example of an Intercepted Update Operation:

{
  "id": "e305d21a-e75b-42e1-886d-a1112345abcd",
  "updated": false,
  "approval_status": "pending",
  "approval_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "approval_message": "This update requires approval (2 levels). Request created."
}

Developer Note: When integrating with Tables that possess potential approval rules (e.g., Purchase Orders, Sales Orders, Leave Requests), you must catch the approval_status === "pending" property in your API Response to prevent treating a Pending state as an actual successful modification.

6. Custom Table API

Prefix: /api/v1/open/data Auth: API Key (X-API-Key Header) Data Isolation: Automatic row-level filtering based on the tenant_id associated with the Key Reference Whitelist: Not applicable (Custom Tables belong to the App itself, not the reference mechanism)

6.0 Differences Between Custom Tables and System Tables

AI GO provides two distinct data storage mechanisms, using different API endpoints:

?? Common Error: Do not use the /open/proxy/ endpoint to access Custom Tables. Custom Tables are not physical PostgreSQL tables and do not exist within the reference system. Accessing them via Proxy endpoints will return a 403 App is not authorized to access table error.

6.1 Custom Table Concepts

Custom Tables represent AI GO's dynamic database system, allowing each App to define its own data table structures:

• CustomObject (Table Definition): Logically equates to a "table", possessing a name and an api_slug (API identifier).
• CustomField (Field Definition): Each Object can define multiple fields (name, type, required status, etc.).
• CustomRecord (Data Record): The actual data is stored within a data field in JSONB format.

erDiagram
    CustomObject ||--o{ CustomField : "has fields"
    CustomObject ||--o{ CustomRecord : "has records"
    CustomObject {
        UUID id PK
        UUID app_id FK
        string name
        string api_slug
    }
    CustomField {
        UUID id PK
        UUID object_id FK
        string name
        string field_key
        string field_type
        boolean is_required
        int sequence
    }
    CustomRecord {
        UUID id PK
        UUID object_id FK
        JSONB data
    }

6.2 List the App's Custom Tables

GET /api/v1/open/data/objects

Response 200 OK:

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "app_id": "uuid",
    "name": "Group Tour",
    "api_slug": "group_tour",
    "created_at": "2026-03-20T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z",
    "fields": [
      {
        "id": "uuid",
        "object_id": "uuid",
        "name": "Tour Name",
        "field_key": "tour_name",
        "field_type": "text",
        "is_required": true,
        "sequence": 10
      },
      {
        "id": "uuid",
        "object_id": "uuid",
        "name": "Amount",
        "field_key": "amount",
        "field_type": "number",
        "is_required": false,
        "sequence": 20
      }
    ]
  }
]

The returned fields array contains comprehensive field definitions, useful for dynamically generating forms or tables.

6.3 List Custom Table Records

GET /api/v1/open/data/objects/{obj_id}/records

Path Parameters:

Response 200 OK:

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "object_id": "uuid",
    "data": {
      "tour_name": "Tokyo 5-Day Tour",
      "amount": 35000,
      "departure_date": "2026-05-01"
    },
    "created_at": "2026-03-20T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z"
  },
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "object_id": "uuid",
    "data": {
      "tour_name": "Seoul 3-Day Tour",
      "amount": 18000,
      "departure_date": "2026-06-15"
    },
    "created_at": "2026-03-21T00:00:00Z",
    "updated_at": "2026-03-21T00:00:00Z"
  }
]

The data field is JSONB; its structure is determined by the Custom Table's fields definitions.

6.4 Insert Record

POST /api/v1/open/data/objects/{obj_id}/records

Path Parameters: obj_id supports UUID or api_slug

Request Body:

{
  "data": {
    "tour_name": "Bangkok 4-Day Tour",
    "amount": 22000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["Grand Palace", "Floating Market", "Pattaya"]
  }
}

data accepts any JSON structure, including objects, arrays, and nested formats. field_key corresponds to the Custom Table's field definitions.

Response 201 Created:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "object_id": "uuid",
  "data": {
    "tour_name": "Bangkok 4-Day Tour",
    "amount": 22000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["Grand Palace", "Floating Market", "Pattaya"]
  },
  "created_at": "2026-03-29T00:00:00Z",
  "updated_at": null
}

tenant_id is automatically injected by the system based on the API Key and does not need to be provided.

6.5 Update Record

PATCH /api/v1/open/data/records/{record_id}

Path Parameters:

Request Body:

{
  "data": {
    "amount": 25000,
    "status": "confirmed"
  }
}

Updates operate in Merge Mode: Only the supplied fields are overwritten; omitted fields remain unchanged. For example, the above request only updates amount and adds status, leaving other fields (like tour_name) unaffected.

Response 200 OK:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "object_id": "uuid",
  "data": {
    "tour_name": "Bangkok 4-Day Tour",
    "amount": 25000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["Grand Palace", "Floating Market", "Pattaya"],
    "status": "confirmed"
  },
  "created_at": "2026-03-29T00:00:00Z",
  "updated_at": "2026-03-29T01:00:00Z"
}

6.6 Delete Record

DELETE /api/v1/open/data/records/{record_id}

Response 200 OK:

{
  "message": "Deleted",
  "id": "uuid"
}

6.7 Field Types Explanation

Because data is a JSONB field, it can actually store arbitrary JSON structures (arrays, nested objects, etc.). The field_type is primarily used for UI form rendering and frontend validation.

6.8 Custom Table Complete Usage Example

Below demonstrates the full flow for a third-party travel agency ERP integrating with Custom Tables:

# ?€?€ Step 1: Obtain API Key, then list the App's Custom Tables ?€?€
curl -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/objects

# Example Response:
# [
#   {
#     "id": "...", "name": "Group Tour", "api_slug": "group_tour",
#     "fields": [{"field_key": "tour_name", "field_type": "text"}, ...]
#   },
#   {
#     "id": "...", "name": "Booking Record", "api_slug": "booking",
#     "fields": [{"field_key": "customer_name", ...}, ...]
#   }
# ]


# ?€?€ Step 2: Use api_slug to list all records in "Group Tour" ?€?€
curl -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records


# ?€?€ Step 3: Insert a new tour record ?€?€
curl -X POST \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
       "data": {
         "tour_name": "Okinawa 4-Day Tour",
         "amount": 28000,
         "departure_date": "2026-08-10",
         "max_people": 25
       }
     }' \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records


# ?€?€ Step 4: Update record (Merge mode, only updates specified fields) ?€?€
curl -X PATCH \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{"data": {"amount": 32000, "status": "full"}}' \
     https://api.ai-go.app/api/v1/open/data/records/{record_id}


# ?€?€ Step 5: Delete record ?€?€
curl -X DELETE \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/records/{record_id}

6.9 Endpoint Comparison with Open Proxy

If you need to access both system tables (like customers) and Custom Tables concurrently, ensure you use the correct API endpoints:

# ?€?€ Accessing System Tables (e.g., customers) ??Use Open Proxy ?€?€
curl -H "X-API-Key: sk_live_xxx" \
     https://api.ai-go.app/api/v1/open/proxy/customers

# ?€?€ Accessing Custom Tables (e.g., group_tour) ??Use Open Custom Data ?€?€
curl -H "X-API-Key: sk_live_xxx" \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records

7. Complete List of Referencable Tables and Schemas

The following lists all referencable data tables (applicable only to Open Proxy; for Custom Tables see 禮6). Every table includes four system fields: id(UUID), created_at(timestamptz), updated_at(timestamptz), tenant_id(UUID), as well as a custom_data(JSONB) custom data field (See 禮4.7), which are not repeated below.

7.1 Customer Module

customers ??Customers

customer_levels ??Customer Levels

customer_tags ??Customer Tags

customer_tag_rel ??Customer-Tag Relations

customer_tag_prices ??Tag Exclusive Prices

7.2 Supplier Module

suppliers ??Suppliers

7.3 Product Module

product_categories ??Product Categories

product_templates ??Product Templates

product_products ??Product Variants

product_price_tiers ??Tiered Pricing

product_supplierinfo ??Supplier Pricing

7.4 Sales Module

sale_orders ??Sales Orders

?? Auto-Trigger Workflows (Triggers)

• When inserting or updating this table (and sale_order_lines), the system automatically compares delivered versus invoiced quantities to recalculate and update the order's invoice_status (no, to_invoice, invoiced).

sale_order_lines ??Sales Order Lines

7.5 Procurement Module

purchase_orders ??Purchase Orders

?? Auto-Trigger Workflows (Triggers)

• When inserting or updating this table (and purchase_order_lines), the system automatically recalculates and updates the invoice status for this order.

purchase_order_lines ??Purchase Order Lines

7.6 Accounting Module

?? Core Accounting Logic and Dedicated API Warning Note: If you directly use the Open Proxy API to INSERT into account_moves and account_move_lines, the system will not trigger accounting fail-safes and automated processing (e.g., auto-numbering, auto-balancing entries, etc.). This can lead to unbalanced debits and credits generating dirty data.

If you are developing an independent accounting/invoicing integration, it is strongly recommended that you exclusively use AI GO's dedicated Accounting Business APIs:

1. POST /api/v1/accounting/vouchers (Create Voucher: auto-configures entry and mappings)
2. POST /api/v1/accounting/vouchers/{id}/post (Post Voucher: automatically inserts an "auto-balance entry" based on settlement gaps and generates a Voucher Number)

In these dedicated APIs, if a Debit ??Credit mismatch is detected, the system automatically injects an "auto-balance entry" to forcibly balance the total amounts, ensuring accounting constraints do not collapse! For detailed Endpoint specs, please see the system's /docs Swagger page.

account_moves ??Journal Entries / Invoices

?? Auto-Trigger Workflows (Triggers)

• When updating this invoice or its lines, along with associated payment reconciliation (account_payments), the system automatically recalculates the invoice's payment_state (e.g., paid, partial, not_paid).

account_move_lines ??Journal Entry Lines

The Accounting Module also includes account_accounts, account_journals, account_taxes, account_payment_terms, account_fiscal_positions, account_payments, account_bank_statements, account_move_templates, etc. For their structures, query the GET /refs/tables/{table_name}/columns API in real-time.

7.7 Inventory Module

stock_warehouses ??Warehouses

stock_locations ??Locations

stock_pickings ??Pickings/Transfers

stock_moves ??Stock Moves

?? Auto-Trigger Workflows (Triggers)

• When updating the status of this table, the system automatically recalculates the partial incoming/outgoing completion status of the associated picking (stock_pickings).

stock_quants ??Stock Quantities

?? Regarding Stock Quantity Maintenance (Triggers): When inserting or updating stock_move_lines (stock move details), the system automatically calculates and updates the reserved quantity (stock_quants.reserved_quantity) for the corresponding items in their respective locations.

The Inventory Module also includes stock_lots, stock_picking_types, stock_move_lines, stock_routes, stock_rules, stock_packages, stock_scraps, stock_warehouse_orderpoints, stock_landed_costs, stock_picking_batches, delivery_carriers, inventory_check_batches, inventory_check_items, inventory_converts, freight_groups, freight_group_tiers, etc.

7.8 CRM Module

crm_leads ??Leads / Opportunities

Also includes crm_stages, crm_teams, crm_team_members, crm_lost_reasons, crm_tags, crm_recurring_plans, crm_activities, etc.

7.9 HR Human Resources Module

hr_employees ??Employees

?? Auto-Trigger Workflows (Triggers)

• Attendance (hr_attendances): Creating or updating an attendance record automatically updates the employee's current attendance state.
• Leaves (hr_leaves): When a leave request state is updated to validate (approved), it automatically deducts from the employee's available leave allocations (hr_leave_allocations).
• Timesheets (hr_timesheets): Filling out timesheets automatically accumulates project_tasks.effective_hours (task actual hours) and updates project task progress percentages.

Also includes hr_departments, hr_jobs, hr_work_locations, hr_attendances, hr_leave_types, hr_leaves, hr_leave_allocations, hr_expense_sheets, hr_expenses, hr_skill_types, hr_skills, hr_timesheets, hr_work_entry_types, hr_work_entries, etc.

7.10 MRP Manufacturing Module

mrp_productions ??Manufacturing Orders

?? Auto-Trigger Workflows (Triggers)

• When updating the state of associated work orders (mrp_workorders), the system automatically calculates and refreshes the completion progress of this manufacturing order.

Also includes mrp_workcenters, mrp_boms, mrp_bom_lines, mrp_bom_byproducts, mrp_routing_workcenters, mrp_workorders, mrp_unbuilds, etc.

7.11 Project Management Module

project_projects ??Projects

?? Auto-Trigger Workflows (Triggers)

• When creating or deleting associated tasks (project_tasks), the system automatically maintains and updates the total task count (task_count) of this project master record.

project_tasks ??Tasks

Also includes project_project_stages, project_task_types, project_milestones, project_tags, project_roles, project_collaborators, project_task_recurrences, project_updates, etc.

7.12 Core Reference Tables

countries ??Countries

currencies ??Currencies

uom_uom ??Units of Measure

Also includes country_states, currency_rates, languages, uom_categories, ir_sequences, etc.

7.13 Other Modules

The complete fields of all tables can be queried dynamically via GET /api/v1/refs/tables/{table_name}/columns.

8. Error Codes and Limits

8.1 HTTP Status Codes

8.2 Common Error Messages

8.3 Rate Limiting

The system implements Per-App rate limiting on all API requests. Exceeding the limit returns 429 Too Many Requests.

8.4 Security Considerations

• All data queries automatically enforce row-level isolation using tenant_id, preventing cross-tenant access.
• tenant_id is automatically determined by the API Key and cannot be forged.
• During write operations, system fields (id, created_at, updated_at, tenant_id) are automatically excluded.
• Field names are regex validated (^[a-zA-Z_][a-zA-Z0-9_]*$) to prevent SQL injection.
• Only whitelisted operators are permitted; arbitrary SQL is not accepted.

9. Proxy Query Security Mechanisms and Functional Limits

9.1 Security Validation Flow

Every Proxy call sequentially executes the following validations:

??AppDataReference Whitelist Validation
   ??Checks if the App has a reference to the target table (Open Proxy requires a published snapshot)
??CRUD Permission Check
   ??The referenced permissions must include the requested action (read / create / update / delete)
??Blacklist Table Check
   ??The 14 system core tables are permanently inaccessible
??Field Whitelist Validation
   ??Fields in filter / select / insert / update must be in the authorized columns list
??Field Name Regex Validation
   ??Only allows ^[a-zA-Z_][a-zA-Z0-9_]*$ to prevent SQL injection
??Operator Whitelist Validation
   ??Only accepts 11 defined operators (eq, ne, gt, gte, lt, lte, like, ilike, in, is_null, is_not_null)
??Tenant Isolation Injection
   ??Automatically appends WHERE tenant_id = :tid to all queries (cross-tenant access impossible)
??System Field Protection
   ??Automatically excludes id, created_at, updated_at, tenant_id during INSERT / UPDATE

9.2 Open Proxy Access Methods Comparison

9.3 Known Query Functional Limitations

9.4 Filter Field Validation Rules Summary

Tip: The latest field structures for all tables can be dynamically fetched via GET /api/v1/refs/tables/{table_name}/columns, including data types, Nullable status, and foreign key targets. It is highly recommended to pair your development with this API.

10. Enum Values Quick Reference

The complete list of VARCHAR fields that only accept fixed enum values.

• [DB]: Has a PostgreSQL CHECK CONSTRAINT; writing an illegal value directly triggers a 400 / 500 error.
• [Suggested]: No database constraint; functions as a system suggestion. Frontend and backend interfaces rely on these, and while the API will not reject other values, they may cause UI display anomalies.

10.1 Customer Module

10.2 Supplier Module

10.3 Product Module

10.4 Sales Module

10.5 Procurement Module

10.6 Accounting Module

10.7 Inventory Module

10.8 CRM Module

10.9 HR Human Resources Module

10.10 MRP Manufacturing Module

10.11 Project Management Module

10.12 Announcement Module

10.13 Fixed Asset Module

10.14 Finance/Bank Module

10.15 Core Reference Tables

10.16 System Management Module

Usage Tips:

• When querying via filters, use the eq operator for precise matching on enum fields, e.g., {"column": "state", "op": "eq", "value": "draft"}.
• To query multiple enum values, use the in operator, e.g., {"column": "state", "op": "in", "value": ["draft", "sent"]}.
• When inserting or updating records, enum fields with [DB] constraints must use the values strictly from the list; otherwise, a 400 / 500 error will be returned.

11. Third-Party Application Best Practices & Gotchas

[!TIP] A summary of common pain points for third-party developers, covering data isolation mechanisms, query safeguards, migration scripts, and CI/CD caveats.

11.1 Best Practices for Multi-App Tenants

[!IMPORTANT] Why is this important? In the AI GO system, a single Tenant might run multiple Custom Apps simultaneously (e.g., a "Booking Platform" and an "E-Commerce Store"). Without data isolation, users on the E-Commerce Store might see "Luxury Ocean View Room" listed as a retail product.

Recommended Strategies:

• Data Domain Separation (App Domain): Strictly enforce that all Custom Apps utilizing shared tables (like product_templates, sale_orders) must inject a domain identifier tag when creating data (e.g., custom_data: { "app_domain": "ec-platform" }).
• Proxy Layer Interception: If you implement an API Request Interceptor on your frontend or write your own API Proxy layer, it is recommended to automatically append the app_domain filter or default field in create and list operations to achieve transparent, site-wide isolation.

11.2 Formatting Traps with PostgreSQL JSONB Queries (Gotchas)

[!WARNING] Trap Warning! Whitespace characteristics during JSON serialization can cause intuitive ilike queries to fail.

Recommended Strategies:

• String Query Characteristics: AI GO stores custom_data in JSONB format within the database. When using the Open Proxy API (like the /query endpoint) to perform ilike filters, using a precise {"app_domain":"ec-platform"} as the condition will often fail to match any data.
• Solution: When PostgreSQL serializes a JSONB object into text for comparison, it often automatically adds a space after the JSON colon (e.g., {"app_domain": "ec-platform"}). Therefore, you should use loose string matching:
  • ??Incorrect: custom_data::text ilike '%"app_domain":"ec-platform"%'
  • ??Correct: custom_data::text ilike '%app_domain%ec-platform%'

11.3 API Proxy Secure Access Control (Access & Auth Models)

[!CAUTION] Certain core system tables (like sale_order_lines) possess low-level strict permission protections, denying arbitrary inserts or deletes.

Recommended Strategies:

• Distinguishing Open Proxy vs. Ext Proxy: Clarify which scenarios (like public catalog reading) can use API Keys, and which scenarios (like consumers checking themselves out) strictly require Bearer Tokens (Custom App User Tokens).
• Capability Matrix Limitations: For specific tables, even if you hold the Delete reference permission, if you trigger an underlying safeguard (e.g., unable to delete lines from a paid order), the API will return a 403 Forbidden error. You should guide the user to the "AI GO Admin Interface" for GUI-based operations or authorized refunds instead.

11.4 Data Migration Script Example (Data Migration Boilerplate)

[!TIP] As an application evolves to its next stage (e.g., introducing data isolation networks late in development), you inevitably need to batch-update the custom_data of historical records.

Node.js Migration Script Example: To ensure backward compatibility, you can prepare a batch script locally to automate the updates:

const axios = require('axios');
const API_URL = 'https://api.ai-go.app/api/v1/open/proxy/product_templates/query';
const API_KEY = 'sk_live_xxxxxx';

async function migrate() {
    let offset = 0;
    while (true) {
        // Query records that do not have the tag yet (illustrative; adapt as needed)
        const resp = await axios.post(API_URL, {
            limit: 100,
            offset: offset
        }, { headers: { 'X-API-Key': API_KEY } });

        const products = resp.data.data || [];
        if (products.length === 0) break;

        for (const p of products) {
            // Check and PATCH each old record to inject app_domain
            if (!p.custom_data || !p.custom_data.app_domain) {
                await axios.patch(`https://api.ai-go.app/api/v1/open/proxy/product_templates/${p.id}`, {
                    custom_data: { ...(p.custom_data || {}), app_domain: 'ec-platform' }
                }, { headers: { 'X-API-Key': API_KEY } });
            }
        }
        offset += 100;
        console.log(`Migrated batch offset ${offset}`);
    }
}
migrate();

11.5 End-to-End Deployment and CI/CD (E2E Deployment)

Recommended Strategies:

• Environment Variable Sync Protocols: Before pushing your frontend application to Vercel or GitHub Actions for building, triple-check that VITE_API_BASE, VITE_APP_SLUG, and AIGO_API_KEY in .env.production or your CI/CD Secrets dashboard are correctly configured with their corresponding Production values.
• Repository Visibility Reminder: If you use Vercel's automated git-pull deployments (Git Integration), you must grant the Vercel app permissions to read that Private GitHub Repository. If module missing errors occur during the build, verify repository permissions or consider setting the source repository to Public.