Skip to content

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 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

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:

bash
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
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 taskUse
Create codes, maintain templates and forms, export labelsREST management endpoints or Admin MCP
Have a business system regularly read code content, records, and metricsAPI
Submit records to a form or verify certificatesAPI; 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 ​

APIPathDescription
Dynamic QR code list (Chinese only)POST /api/v2/rpc/qrcodes/listList dynamic QR code names and codings under the organization, with pagination
QR code contentPOST /api/v2/rpc/qrcodes/getContentGet display content (meta + fields) by coding or URL
QR code operation elementsPOST /api/v2/rpc/qrcodes/getOperationGet flattened operation-element list by coding or URL

Bulk templates and sub-codes ​

APIPathDescription
Template list (Chinese only)POST /api/v2/rpc/templates/listList bulk templates with pagination
Template structure (Chinese only)POST /api/v2/rpc/templates/getMeta information and field structure of a bulk template
Sub-code list (Chinese only)POST /api/v2/rpc/templates/listQrcodesList the sub-codes under a template with pagination
Sub-code content (Chinese only)POST /api/v2/rpc/templates/getSubcodeActual content of each field of a sub-code
Create sub-code v1 (Chinese only)POST /api/v1/createSubCodeCreate a sub-code under a template
Edit sub-code v1 (Chinese only)POST /api/v1/editSubCodeEdit sub-code content
Delete sub-code v1 (Chinese only)POST /api/v1/deleteSubCodeDelete a sub-code

Forms and records ​

APIPathDescription
Get form listPOST /api/v2/rpc/record/getFormListList forms under current org with pagination
Get form templatePOST /api/v2/rpc/forms/getTemplateGet form name, template ID, and field list by tpl_id
Get a single recordPOST /api/v2/rpc/record/getRecordGet record detail by record_id or record_url
Get recordsPOST /api/v2/rpc/record/getRecordsQuery records by filters, keyword, time, and pagination
Add recordPOST /api/v2/rpc/record/addRecordSubmit one record by code_id + tpl_id
Verify record certificatePOST /api/v2/rpc/certificates/verifyVerify 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 ​

APIPathDescription
Metric catalog (Chinese only)POST /api/v2/rpc/metrics/listThe 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/getA metric's calculation rules, available dimensions, and caveats
Query metrics (Chinese only)POST /api/v2/rpc/metrics/queryValues 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/searchRecordsSearch record summaries by multiple conditions, going from a number straight to the records behind it

Organization ​

APIPathDescription
Partition list (Chinese only)POST /api/v2/rpc/projects/listPartitions under the organization; partitions can be used for grouping statistics and filtering by scope
Add members in bulk v1 (Chinese only)POST /api/member/addMemberAdd 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.

CapabilityURLAuthentication
Generate QR code, Decodehttps://api.2dcode.biz/v1/None
Identify a code's source v1https://open.cli.im/api/v1/qrcode/scan_urlOrganization key
Label Generationhttps://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.

Typical scenarios ​