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.
Call the V2 API with a personal API key; third-party applications use OAuth. Organization keys created earlier work only for a fixed set of existing endpoints. The v1 APIs are no longer updated; their docs remain under previous versions.
Base URL and conventions
- Base URL:
https://open.cli.im - Path prefix:
/api/v2/rpc/, so full endpoints look likehttps://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
First call
Create a personal API key and verify the organization. For a reporting integration, choose Read only. If a required level is unavailable, a super administrator can check the organization policy. To fetch a page of dynamic QR codes:
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}'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. For terms, see Core Concepts. If something fails, see Error codes and rate limits.
OpenAPI spec: 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. 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 (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 or Admin MCP |
| 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 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 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 (Chinese only) | POST /api/v2/rpc/qrcodes/list | List dynamic QR code names and codings under the organization, with pagination |
| QR code content | POST /api/v2/rpc/qrcodes/getContent | Get display content (meta + fields) by coding or URL |
| QR code operation elements | 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 (Chinese only) | POST /api/v2/rpc/templates/list | List bulk templates with pagination |
| Template structure (Chinese only) | POST /api/v2/rpc/templates/get | Meta information and field structure of a bulk template |
| Sub-code list (Chinese only) | POST /api/v2/rpc/templates/listQrcodes | List the sub-codes under a template with pagination |
| Sub-code content (Chinese only) | POST /api/v2/rpc/templates/getSubcode | Actual content of each field of a sub-code |
Create sub-code v1 (Chinese only) | POST /api/v1/createSubCode | Create a sub-code under a template |
Edit sub-code v1 (Chinese only) | POST /api/v1/editSubCode | Edit sub-code content |
Delete sub-code v1 (Chinese only) | POST /api/v1/deleteSubCode | Delete a sub-code |
Forms and records
| API | Path | Description |
|---|---|---|
| Get form list | POST /api/v2/rpc/record/getFormList | List forms under current org with pagination |
| Get form template | POST /api/v2/rpc/forms/getTemplate | Get form name, template ID, and field list by tpl_id |
| Get a single record | POST /api/v2/rpc/record/getRecord | Get record detail by record_id or record_url |
| Get records | POST /api/v2/rpc/record/getRecords | Query records by filters, keyword, time, and pagination |
| Add record | POST /api/v2/rpc/record/addRecord | Submit one record by code_id + tpl_id |
| Verify record certificate | POST /api/v2/rpc/certificates/verify | Verify credential records (next status or target status) |
Form component types 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 (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 (Chinese only) | POST /api/v2/rpc/metrics/get | A metric's calculation rules, available dimensions, and caveats |
| Query metrics (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 (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 (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 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, Decode | https://api.2dcode.biz/v1/ | None |
Identify a code's source v1 | https://open.cli.im/api/v1/qrcode/scan_url | Organization key |
| Label Generation | 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.