---
head:
  - - meta
    - name: description
      content: "CaoLiao Open Platform API overview: base URL and conventions, the openapi.json URL, how the API and MCP divide the work, a first call example, and the API index."
  - - meta
    - name: keywords
      content: CaoLiao Open Platform, OpenAPI V2, openapi.json, QR code API, forms and records, scenarios, states, API 2.0, Postman
---

# API Overview

Business systems use the V2 API to read code content, read and write form records and query metrics. They can also create codes, maintain templates, edit forms and export labels. AI clients reach the same capabilities through the [Admin MCP](https://cli.im/open-api/en/agent/open-platform-mcp/quick-start.md).

Call the V2 API with a [personal API key](https://cli.im/open-api/en/openapi/v2/auth.md#create-key); third-party applications use OAuth. Organization keys created earlier work only for [a fixed set of existing endpoints](https://cli.im/open-api/en/openapi/v2/auth.md#org-key). The v1 APIs are no longer updated; their docs remain under [previous versions](https://cli.im/open-api/en/openapi/migrate-from-v1.md).

## Base URL and conventions

- **Base URL**: `https://open.cli.im`
- **Path prefix**: `/api/v2/rpc/`, so full endpoints look like `https://open.cli.im/api/v2/rpc/{service}/{method}`
- **Method**: all endpoints are **POST** with **application/json** request bodies
- **Authentication**: send `Authorization: Bearer <personal API key>` in the request header. See [Authentication](https://cli.im/open-api/en/openapi/v2/auth.md)

## First call

[Create a personal API key](https://cli.im/open-api/en/openapi/v2/auth.md#create-key) and [verify the organization](https://cli.im/open-api/en/openapi/v2/auth.md#verify-key). For a reporting integration, choose Read only. If a required level is unavailable, a super administrator can [check the organization policy](https://cli.im/open-api/en/openapi/v2/auth.md#org-policy). To fetch a page of dynamic QR codes:



```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/list' \
  -H 'Authorization: Bearer <YourAPIKey>' \
  -H 'Content-Type: application/json' \
  -d '{"page_size": 20}'
```

```python [Python + requests]
import requests

url = "https://open.cli.im/api/v2/rpc/qrcodes/list"
headers = {
    "Authorization": "Bearer <YourAPIKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json={"page_size": 20}, headers=headers)
print(response.text)
```



Once you have a code's `coding`, continue with [QR code content](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-content.md). For terms, see [Core Concepts](https://cli.im/open-api/en/start/concepts.md). If something fails, see [Error codes and rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md).

## OpenAPI spec: openapi.json {#openapi-json}

`https://open.cli.im/openapi.json` is the OpenAPI 3.x spec file. It requires no authentication; you can GET it directly. Use it to generate SDKs, debug APIs, or import into tools such as Swagger and Postman.

The file is generated from the running service on every release. It covers the paths, request schemas and responses of every `/api/v2/rpc/*` endpoint currently live, including the [management endpoints](https://cli.im/open-api/en/openapi/v2/management.md). The APIs marked `v1` below are not in it.

There is no hosted Swagger page. To browse or try the endpoints in a UI, import the URL into Postman or paste it into [Swagger Editor](https://editor.swagger.io/) (File → Import URL).

## How the API and MCP divide the work

| Your task | Use |
|---|---|
| Create codes, maintain templates and forms, export labels | [REST management endpoints](https://cli.im/open-api/en/openapi/v2/management.md) or [Admin MCP](https://cli.im/open-api/en/agent/open-platform-mcp/tools.md) |
| Have a business system regularly read code content, records, and metrics | API |
| Submit records to a form or verify certificates | API; these two are not among the default Admin MCP tools |

## API index

See the [API list](https://cli.im/open-api/en/openapi/v2/api-index.md) for every endpoint and the permission it needs. The endpoints below have their own reference pages and accept personal keys, OAuth and legacy organization keys. Endpoints for creating, editing, deleting and exporting labels are listed in [Code, template and form management](https://cli.im/open-api/en/openapi/v2/management.md) and accept personal keys or OAuth only. APIs marked `v1` accept organization keys only.

Pages marked "Chinese only" do not have an English version yet.

### QR codes

| API | Path | Description |
|------|------|------|
| [Dynamic QR code list](https://cli.im/open-api/openapi/v2/api/qrcodes-list.md) (Chinese only) | `POST /api/v2/rpc/qrcodes/list` | List dynamic QR code names and codings under the organization, with pagination |
| [QR code content](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-content.md) | `POST /api/v2/rpc/qrcodes/getContent` | Get display content (meta + fields) by coding or URL |
| [QR code operation elements](https://cli.im/open-api/en/openapi/v2/api/qrcodes-get-operation.md) | `POST /api/v2/rpc/qrcodes/getOperation` | Get flattened operation-element list by coding or URL |

### Bulk templates and sub-codes

| API | Path | Description |
|------|------|------|
| [Template list](https://cli.im/open-api/openapi/v2/api/templates/templates-list.md) (Chinese only) | `POST /api/v2/rpc/templates/list` | List bulk templates with pagination |
| [Template structure](https://cli.im/open-api/openapi/v2/api/templates/templates-get.md) (Chinese only) | `POST /api/v2/rpc/templates/get` | Meta information and field structure of a bulk template |
| [Sub-code list](https://cli.im/open-api/openapi/v2/api/templates/templates-list-qrcodes.md) (Chinese only) | `POST /api/v2/rpc/templates/listQrcodes` | List the sub-codes under a template with pagination |
| [Sub-code content](https://cli.im/open-api/openapi/v2/api/templates/templates-get-subcode.md) (Chinese only) | `POST /api/v2/rpc/templates/getSubcode` | Actual content of each field of a sub-code |
| [Create sub-code](https://cli.im/open-api/openapi/api/template-qrcodes/create-qrcode.md) `v1` (Chinese only) | `POST /api/v1/createSubCode` | Create a sub-code under a template |
| [Edit sub-code](https://cli.im/open-api/openapi/api/template-qrcodes/edit-qrcode.md) `v1` (Chinese only) | `POST /api/v1/editSubCode` | Edit sub-code content |
| [Delete sub-code](https://cli.im/open-api/openapi/api/template-qrcodes/delete-qrcode.md) `v1` (Chinese only) | `POST /api/v1/deleteSubCode` | Delete a sub-code |

### Forms and records

| API | Path | Description |
|------|------|------|
| [Get form list](https://cli.im/open-api/en/openapi/v2/api/record/record-get-form-list.md) | `POST /api/v2/rpc/record/getFormList` | List forms under current org with pagination |
| [Get form template](https://cli.im/open-api/en/openapi/v2/api/record/forms-get-template.md) | `POST /api/v2/rpc/forms/getTemplate` | Get form name, template ID, and field list by `tpl_id` |
| [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) | `POST /api/v2/rpc/record/getRecord` | Get record detail by `record_id` or `record_url` |
| [Get records](https://cli.im/open-api/en/openapi/v2/api/record/record-get-records.md) | `POST /api/v2/rpc/record/getRecords` | Query records by filters, keyword, time, and pagination |
| [Add record](https://cli.im/open-api/en/openapi/v2/api/record/record-add-record.md) | `POST /api/v2/rpc/record/addRecord` | Submit one record by `code_id + tpl_id` |
| [Verify record certificate](https://cli.im/open-api/en/openapi/v2/api/record/certificates-verify.md) | `POST /api/v2/rpc/certificates/verify` | Verify credential records (next status or target status) |

[Form component types](https://cli.im/open-api/en/openapi/v2/api/record/components-field-types.md) covers `field_type` naming, categories, shared semantics, and conventions. For configuration structure, see "Get form template"; for record value structure, see "Get a single record".

### Metrics and analysis

| API | Path | Description |
|------|------|------|
| [Metric catalog](https://cli.im/open-api/openapi/v2/api/metrics/metrics-list.md) (Chinese only) | `POST /api/v2/rpc/metrics/list` | The organization's business object catalog (forms, partitions, dynamic QR codes, recurring plans) and the metrics available; the entry point for analysis |
| [Metric definition](https://cli.im/open-api/openapi/v2/api/metrics/metrics-get.md) (Chinese only) | `POST /api/v2/rpc/metrics/get` | A metric's calculation rules, available dimensions, and caveats |
| [Query metrics](https://cli.im/open-api/openapi/v2/api/metrics/metrics-query.md) (Chinese only) | `POST /api/v2/rpc/metrics/query` | Values and distributions (grouped by form, partition, dynamic QR code, day, month, and so on); each group carries its drill-down conditions |
| [Drill-down record search](https://cli.im/open-api/openapi/v2/api/record/record-search-records.md) (Chinese only) | `POST /api/v2/rpc/record/searchRecords` | Search record summaries by multiple conditions, going from a number straight to the records behind it |

### Organization

| API | Path | Description |
|------|------|------|
| [Partition list](https://cli.im/open-api/openapi/v2/api/projects-list.md) (Chinese only) | `POST /api/v2/rpc/projects/list` | Partitions under the organization; partitions can be used for grouping statistics and filtering by scope |
| [Add members in bulk](https://cli.im/open-api/openapi/api/member/add-member.md) `v1` (Chinese only) | `POST /api/member/addMember` | Add or edit members in bulk |

### APIs outside `/api/v2/rpc/`

These APIs use different URLs and authentication from the main APIs. Note that `open.cli.im` and `open-api.cli.im` are two different domains.

| Capability | URL | Authentication |
|------|------|------|
| [Generate QR code](https://cli.im/open-api/en/qrcode-api/create-qr-code.md), [Decode](https://cli.im/open-api/en/qrcode-api/read-qr-code.md) | `https://api.2dcode.biz/v1/` | None |
| [Identify a code's source](https://cli.im/open-api/en/openapi/api/qr-codes/scan-url.md) `v1` | `https://open.cli.im/api/v1/qrcode/scan_url` | Organization key |
| [Label Generation](https://cli.im/open-api/en/label-api/intro.md) | `https://open-api.cli.im/cli-open-platform-service/v1/` | None for public styles; `api_key` plus signature for private styles |

No v1 API is updated any more. APIs marked `v1` have no one-to-one replacement in the current version and remain available. Every other v1 API has a replacement. See [Migrate from v1 to the Current Version](https://cli.im/open-api/en/openapi/migrate-from-v1.md).

## Typical scenarios

- [Query forms and records linked to a QR code](https://cli.im/open-api/en/openapi/v2/scenarios/query-qrcode-records.md)
- [Submit a record to a form under a QR code](https://cli.im/open-api/en/openapi/v2/scenarios/add-record-by-qrcode.md)
- [Bulk add records from Excel](https://cli.im/open-api/en/openapi/v2/scenarios/bulk-import-records.md)
