Create an Mai Platform Service Application

An “Application” represents the current account's subscription relationship to a service—you must apply first before you can create API credentials for this application and call business APIs. When applying for a service for the first time, the Application will receive the service's currently configured free_amount; this value may be 0.

ℹ️ This API belongs to the Mai Platform Management API, with the unified prefix https://moses.platform.acedata.cloud/api/v1/. For the complete API index, see Get Mai Platform Document List.

Complete Integration Flow

New users typically go through these 5 steps from registration to successfully calling their first business API:

  1. Obtain an account token → Manage Mai Platform Account Tokens
  2. Select a service → Get Mai Platform Service List
  3. Create an application (this document) → Obtain the initial quota according to the service configuration
  4. Create API credentials → Create Mai Platform API Credentials
  5. Call a business API → Use the obtained 32-character Token to call https://api.ai.moses.day/<path>

API Overview

Item Content
Method POST
URL https://moses.platform.acedata.cloud/api/v1/applications/
Authentication ✅ Account token required
Content-Type application/json

Authentication Instructions (How to Obtain an Account Token)

Request header:

Authorization: Bearer ${PLATFORM_TOKEN}

An account token (Account Token) is an “account-level key” used by developers to manage their own account resources through the API. How to obtain it:

  1. One-click creation in the console (recommended): Log in to the Mai Platform → Account Token Console → Click “Create” to obtain a token starting with platform-v1-.
  2. API creation: Use an existing account token or browser login-session JWT to call POST /api/v1/platform-tokens/. For details, see Manage Mai Platform Account Tokens.

⚠️ Account tokens are as sensitive as passwords. Do not write them into frontend code or public repositories. If exposed, delete and recreate them in the console immediately.

Request Body

Parameter Type Required Description
service_id UUID ✅ The ID of the service to apply for. It can be obtained from items[].id in the service list

Request Examples

cURL

curl -X POST 'https://moses.platform.acedata.cloud/api/v1/applications/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452"}'

Python

import os
import requests

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
SERVICE_ID = "38ecf158-36f2-42f2-8e7f-6786cdfc2452"

resp = requests.post(
    "https://moses.platform.acedata.cloud/api/v1/applications/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={"service_id": SERVICE_ID},
    timeout=10,
)

if resp.status_code == 201:
    app = resp.json()
    print(f"申请成功！application_id={app['id']}")
    print(f"初始额度：{app['remaining_amount']} {app.get('service', {}).get('unit', '')}")
elif resp.status_code == 400 and resp.json().get("code") == "duplication":
    print("⚠️ 已经申请过此服务，请到 /applications/ 列表里找到现成的 application_id")
else:
    print(f"申请失败：HTTP {resp.status_code} - {resp.text}")

Node.js

const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://moses.platform.acedata.cloud/api/v1/applications/', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ service_id: SERVICE_ID }),
})

if (resp.status === 201) {
  const app = await resp.json()
  console.log('application_id =', app.id)
} else {
  console.error(await resp.text())
}

Response Examples

Success (HTTP 201)

{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 1.0,
  "used_amount": 0.0,
  "paid": false,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "allow_overdraft": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "client_ip": null,
  "client_fingerprint": null,
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T07:52:27.462400Z"
}

The returned field structure is consistent with Get Mai Platform Service Application Details.

Already Applied (HTTP 400)

{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}

This is a hard design limitation: each user can only have one Application for each service. If it already exists, find the existing one through Get Mai Platform Service Application List.

Service Not Found (HTTP 404)

{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}

Service Requires Review (HTTP 403)

{
  "detail": "This service requires manual verification.",
  "code": "need_verify",
  "trace_id": "..."
}

If the service has need_verify=true (this field can be seen in the service list), you need to apply for whitelisting through the ticket process.

Error Handling

HTTP code Meaning
400 duplication This service has already been applied for by the current account
400 invalid service_id is missing or incorrectly formatted
401 not_authenticated Account token is missing or the token has been deleted
403 need_verify The service requires review; please follow the ticket process
404 not_found The service does not exist or has been taken offline

Unified error response format:

{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}

Practical Tips

  • Creation itself does not incur charges: Upon initial creation, the initial quota is set according to the service's current free_amount; this value may be 0, and creating the same type of Application again does not guarantee repeated free quota.
  • Check the paid field to determine whether payment is required: When first applied for, paid=false; it becomes true after calling Create Mai Platform Top-up Order to complete payment.
  • disabled=true means temporarily disabled—for example, due to risk control triggers, overdue payments, etc. When disabled, business APIs will return 403.
  • Do not create with unbounded concurrency: First obtain the target service_id from the paginated service list, then apply for each item as needed by the business; when encountering duplication, reuse the existing Application.

allow_overdraft is disabled by default and is authorized separately by administrators; it cannot be enabled through request parameters when creating an Application.