> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an AceDataCloud Platform Service Application

> Platform integration guide - Ace Data Cloud

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 **AceDataCloud Platform Management API**, with the unified prefix `https://platform.acedata.cloud/api/v1/`. For the complete API index, see [Get the AceDataCloud Platform Document List](https://platform.acedata.cloud/documents/platform-document-list).

## Complete Integration Process

New users usually follow these 5 steps from registration to successfully calling their first business API:

1. **Obtain an account token** → [Manage AceDataCloud Platform Account Tokens](https://platform.acedata.cloud/documents/platform-token)
2. **Choose a service** → [Get the AceDataCloud Platform Service List](https://platform.acedata.cloud/documents/platform-service-list)
3. **Create an application** (this document) → Obtain the initial quota according to the service configuration
4. **Create API credentials** → [Create AceDataCloud Platform API Credentials](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Call business APIs** → Use the obtained 32-character Token to call `https://api.acedata.cloud/<path>`

## API Overview

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

## Authentication Instructions (How to Obtain an Account Token)

Request header:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

An account token (Account Token) is an "account-level key" that developers use to manage their own account resources through APIs. How to obtain it:

1. **One-click creation in the console (recommended)**: Log in to the [AceDataCloud Platform](https://platform.acedata.cloud) → [Account Token Console](https://platform.acedata.cloud/console/platform-tokens) → 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 AceDataCloud Platform Account Tokens](https://platform.acedata.cloud/documents/platform-token).

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

## 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](https://platform.acedata.cloud/documents/platform-service-list) |

## Request Examples

### cURL

```shell theme={null}
curl -X POST 'https://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

```python theme={null}
import os
import requests

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

resp = requests.post(
    "https://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

```javascript theme={null}
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://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)

```json theme={null}
{
  "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,
  "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 AceDataCloud Platform Service Application Details](https://platform.acedata.cloud/documents/platform-application-detail).

### Already Applied For (HTTP 400)

```json theme={null}
{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}
```

This is a hard limitation by design: **each user can only have one Application for each service**. If it already exists, find the existing one through [Get the AceDataCloud Platform Service Application List](https://platform.acedata.cloud/documents/platform-application-list).

### Service Does Not Exist (HTTP 404)

```json theme={null}
{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}
```

### Service Requires Review (HTTP 403)

```json theme={null}
{
  "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` | The service has already been requested by the current account |
| 400 | `invalid` | `service_id` is missing or incorrectly formatted |
| 401 | `not_authenticated` | The account token is missing or 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:

```json theme={null}
{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}
```

## Practical Tips

* **Creation itself does not incur charges**: Upon first 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 credits.
* **Check the `paid` field to determine whether payment is required**: When first requested, `paid=false`; it becomes `true` after payment is completed by calling [Create AceDataCloud Platform Top-up Order](https://platform.acedata.cloud/documents/platform-order-create).
* **`disabled=true` indicates temporary disablement**—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 request them one by one as needed by the business; when encountering `duplication`, reuse the existing Application.

## Related APIs

* [Get AceDataCloud Platform Service List](https://platform.acedata.cloud/documents/platform-service-list) — Select a service first
* [Get AceDataCloud Platform Service Application List](https://platform.acedata.cloud/documents/platform-application-list) — View all requested applications
* [Get AceDataCloud Platform Service Application Details](https://platform.acedata.cloud/documents/platform-application-detail) — View a single application
* [Create AceDataCloud Platform API Credential](https://platform.acedata.cloud/documents/platform-credential-create) — The next step after a successful request
* [Create AceDataCloud Platform Top-up Order](https://platform.acedata.cloud/documents/platform-order-create) — Top up after free quota is exhausted


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.