REST API

AuraBoot exposes a RESTful API for all platform operations. Every action available in the web UI -- from querying records to executing commands -- is accessible through the API.

Authentication

All API requests require a JWT bearer token. Obtain one by calling the login endpoint:

curl -X POST http://localhost:6443/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@auraboot.com",
    "password": "YourPassword"
  }'

Response:

{
  "code": "0",
  "message": "success",
  "data": {
    "jwt": "eyJhbGciOiJIUzI1NiIs...",
    "userId": "1234567890",
    "userPid": "01HXYZ...",
    "username": "admin",
    "tenantId": "1",
    "tenantStatus": "member"
  }
}

Include the token in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Base URL

All API endpoints are prefixed with:

http://localhost:6443/api

In production, replace with your domain and ensure HTTPS.

Response Format

All responses follow a consistent envelope format:

{
  "code": "0",
  "message": "success",
  "data": { ... }
}

Field	Type	Description
`code`	string	`"0"` for success, error code otherwise
`message`	string	Human-readable message
`data`	any	Response payload (object, array, or null)

Error responses use the same format with a non-zero code:

{
  "code": "VALIDATION_ERROR",
  "message": "Field 'title' is required",
  "data": null
}

Common Conventions

These rules apply to every endpoint below — verify against the matching Spring @RequestParam / @RequestBody when integrating (red line §5 prohibits guessing parameter names).

Required headers

Header	Required	Notes
`Authorization: Bearer <jwt>`	Yes	All endpoints except `/api/auth/login` and `/api/health`.
`X-Tenant-Id`	Optional	Override the tenant resolved from the JWT. Server enforces membership; mismatch → `403 TENANT_FORBIDDEN`.
`Accept-Language`	Optional	BCP-47 (`en`, `zh-CN`). Drives i18n resolution in responses.
`Content-Type: application/json`	On POST/PUT	Except multipart uploads.
`X-Idempotent-Key`	Optional	Idempotency dedupe header for command execution (`POST /api/meta/commands/execute/{commandCode}`); 24 h dedupe window. You can also use the `clientRequestId` field in the request body.

List query parameters

Every list endpoint — GET /api/dynamic/{pageKey}/list, dashboard data sources, audit log search — accepts the same parameter contract. Do not use page / size / pageNum interchangeably; the canonical names are:

Parameter	Type	Default	Notes
`pageNum`	int	`1`	1-based.
`pageSize`	int	`10`	Max `500`.
`keyword`	string	—	Full-text on the model's searchable fields.
`sortField`	string	`created_at`	Must be a field code on the bound model.
`sortOrder`	string	`desc`	`asc` or `desc`.
`filters`	JSON array	—	URL-encoded; see Filters Format below.

Error envelope

Errors share the response envelope; map by code:

`code`	HTTP	Meaning
`0`	200	Success.
`VALIDATION_ERROR`	400	Field-level error; `data.fieldErrors` is `{ fieldCode: message }`.
`UNAUTHORIZED`	401	Missing / expired JWT.
`FORBIDDEN`	403	Permission denied. `data.permission` lists the required code.
`TENANT_FORBIDDEN`	403	Cross-tenant access attempt.
`NOT_FOUND`	404	Resource missing or soft-deleted.
`IDEMPOTENT_REPLAY`	200	Duplicate `X-Idempotent-Key` / `clientRequestId`; `data` is the original result.
`RATE_LIMITED`	429	See Rate Limiting.
`INTERNAL_ERROR`	500	Server fault; `data.traceId` for log correlation.

Validation errors always include a per-field map so the UI can surface field-control errors (never a generic banner — red line §2.2):

{
  "code": "VALIDATION_ERROR",
  "message": "1 validation error",
  "data": { "fieldErrors": { "email": "$i18n:crm.lead.email.duplicate" } }
}

Dynamic CRUD Endpoints

List Records

GET /api/dynamic/{pageKey}/list

Parameter	Type	Default	Description
`pageNum`	int	1	Page number (1-based)
`pageSize`	int	10	Records per page (max 500)
`keyword`	string	—	Full-text search across searchable fields
`sortField`	string	`created_at`	Field code to sort by
`sortOrder`	string	`desc`	`asc` or `desc`
`filters`	JSON	—	Array of filter conditions

Filters Format

The filters parameter accepts a JSON array of conditions:

[
  { "fieldName": "status", "operator": "eq", "value": "active" },
  { "fieldName": "created_at", "operator": "gte", "value": "2024-01-01" }
]

Supported operators: eq, ne, gt, gte, lt, lte, like, in, not_in, is_null, is_not_null.

Example

curl "http://localhost:6443/api/dynamic/crm_lead_list/list?\
pageNum=1&pageSize=20&keyword=acme&\
filters=%5B%7B%22fieldName%22%3A%22status%22%2C%22operator%22%3A%22eq%22%2C%22value%22%3A%22new%22%7D%5D" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "code": "0",
  "data": {
    "records": [
      { "id": "1234567890", "lead_name": "Acme Corp", "status": "new", ... }
    ],
    "total": 42,
    "pageNum": 1,
    "pageSize": 20
  }
}

Execute Commands

All write operations go through a single endpoint (commandCode is a path parameter; business fields go in the request body's payload):

POST /api/meta/commands/execute/{commandCode}

Create

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:create_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "lead_name": "Jane Smith",
      "email": "jane@example.com",
      "status": "new"
    }
  }'

Update

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:update_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "UPDATE",
    "targetRecordId": "1234567890",
    "payload": {
      "lead_name": "Jane Smith-Updated"
    }
  }'

Delete

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:delete_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "DELETE",
    "targetRecordId": "1234567890"
  }'

Get Single Record

GET /api/dynamic/{pageKey}/{recordId}

where recordId is a path parameter.

Data Source Query

For custom queries (used by dashboards and reports):

GET /api/datasource/list?datasourceId={code}&maxItems=200

Pagination

List endpoints return paginated results. Use pageNum and pageSize to navigate:

Page 1: pageNum=1&pageSize=20  → records 1-20
Page 2: pageNum=2&pageSize=20  → records 21-40

The total field in the response tells you the total number of matching records.

Rate Limiting

API requests are rate-limited per user. Default limits:

Endpoint Type	Limit
Read (list, detail)	100 req/min
Write (command execute)	30 req/min
Auth (login)	10 req/min

Next Steps

Plugin API Reference — SPIs and host services
CommandExecutor service — programmatic equivalent of /api/meta/commands/execute/{commandCode}
DynamicDataService service — programmatic equivalent of /api/dynamic/{pageKey}/list
Commands — pipeline phases
Permissions — authorization model