Development API: Gateway API Reference

For browser authorization, permissions and project connections from Codex and other MCP clients, see MCP connection and authorization.

This page summarizes commonly used interfaces for TGateway, Studio, and Watchdog. Sign in and send a valid token when calling protected endpoints. Ordinary Studio language-service requests allow anonymous access; analysis involving project paths still requires authentication.

Reading path: retrieve the API definition → authentication → API reference → request troubleshooting. MCP is optional; use MCP access and authorization only when choosing that client.

Access and authentication

Interface Terminology Comparison

Basic Agreements

Studio and Watchdog listen on 0.0.0.0 by default, and the current version allows clients to call them over standard http://<ip>:<port> addresses. Standard HTTP access requires remote management and AllowInsecureRemoteHttp to be enabled. Watchdog project deployment and process control also require RemoteDeploymentEnabled.

Browser CORS

TGateway Web APIs allow any browser origin by default when CorsOrigins is empty. A configured list matches complete origins, including scheme, host, and nondefault port. A domain suffix, substring, or different port does not match the same origin.

Origin permission and API authorization are separate checks. Protected endpoints still require valid tokens, roles, and API permissions. Send Bearer tokens according to the endpoint contract. Server applications are not governed by browser CORS but must still pass authentication and authorization.

The default language address is https://roslyn.thingsgateway.cn; use your own root address for a self-hosted Studio. Reverse proxies must preserve CORS headers and forward OPTIONS preflight or return an equivalent response. HTTP 200 alone does not prove a browser can call the service: check expected JSON, a matching Access-Control-Allow-Origin, and preflight permission for the actual method and headers.

For example, inspect the language service response with the Gateway page’s actual origin:

# 使用实际 Gateway 网页的 Origin 检查响应头及 JSON。
curl -i \
  -H 'Origin: http://192.168.10.30:6100' \
  https://roslyn.thingsgateway.cn/api/completion/assemblies

Ordinary language responses include Access-Control-Allow-Origin: *. This mode does not grant cross-site cookie credentials; callers should not depend on cross-site cookies for authentication. Complete connection, completion, and analysis checks in the real Gateway editor. See Code Editor Operations.

Retrieve OpenAPI JSON

TGateway provides a standard OpenAPI JSON document at the following address:

GET http://<gateway-ip>:6100/api/openapi.json

You can also save the document to a local file with curl:

curl http://<gateway-ip>:6100/api/openapi.json -o openapi.json

The returned JSON can be imported into Swagger Editor, Postman, or other OpenAPI-compatible clients and code generators. Use the document returned by the target TGateway version as the authoritative interface definition.

Studio and Watchdog Login Password Encryption

Before calling the Studio or Watchdog login API, obtain a temporary public key and encrypt the password:

1. Call the corresponding public key endpoint to obtain keyId, publicKey, algorithm, nonce, and expiresAt.
2. Confirm that algorithm equals RSA-OAEP-SHA256.
3. Use the RSA 2048 SubjectPublicKeyInfo DER Base64 public key in the publicKey to encrypt the following UTF-8 JSON. Field names are case-fixed.

{
  "Password": "The actual password",
  "Nonce": "NONCE in public key responses"
}

4. Encode the RSA-OAEP-SHA256 ciphertext in Base64 as the login request’s password, and submit keyId as passwordKeyId.
5. After successful login, subsequent protected requests are uniformly sent Authorization: Bearer <token>.

The temporary public key expires after two minutes and allows a single login request. It becomes invalid after that request succeeds or fails. Obtain a new public key before retrying. The API accepts only the encrypted format described above.

Browser clients can use node-forge to execute RSA-OAEP-SHA256 on a regular HTTP IP page and generate OAEP random seeds using crypto.getRandomValues; Do not rely on the crypto.subtle.importKey, which is usually unavailable in this scenario.

TGateway Authentication Interface

External identity and single sign-on

External identity requires the same-origin browser, original flow state, and matching purpose. A completion code is not an access token. See Identity Authentication.

TGateway API reference

System monitoring

Snapshots can reuse samples collected within 30 seconds. Monitoring, package lists, and manual GC check their respective permissions. GC does not guarantee an immediate working-set decrease. See System Monitoring for measurement scopes and operation steps.

Status and debug WebSocket connections

1. Use the current Bearer token with POST /api/gatewaywebsocketcontroller/createstatusticket or createdebugticket to request a status or read-only debug ticket.
2. Within 30 seconds, connect to /ws/gateway/status?ticket=<ticket> or /ws/gateway/debug?ticket=<ticket>. Use wss for HTTPS sites.
3. A ticket is consumed once and cannot be exchanged between purposes. Request another before reconnecting; do not reuse expired or consumed tickets or place long-lived access tokens in connection URLs.

Status tickets require variable-read permission; debug tickets require debug-query permission. A ticket does not grant write access.

TGateway Overview and Metadata

Collect and configure interfaces

Plugin method RPC

POST /api/gatewayrpccontroller/invokepluginmethod uses a Bearer Token and rpc:invoke_plugin_method API permission. Enable Allow method calls on the called device or target; no variable binding or additional method allowlist is required.

{"subjectType":"CollectDevice","subjectId":1001,"methodName":"ReadAsync","parameters":["400001","UInt16",1],"timeoutMs":30000}

Replace 1001 with the actual instance ID; use DataForwardTarget for forwarding targets. There is no business request ID, deduplication cache, or method concurrency quota. Check data.status, isSuccess, operCode, message, content, executionTime, and executionMayHaveOccurred separately from HTTP success.

The dangerous-debug endpoint POST /api/debugController/invokespecialmethod uses parametersJson, a JSON text positional array, and returns contentJson as complete JSON text. The formal endpoint uses an actual parameters JSON value. Preserve number precision and do not mix these shapes. See Plugin Method Calls for MQTT, UA, timeouts, and logs.

Data forwarding interface

In the data forwarding interface, forwarding group variable relations determine whether a variable belongs to a group, while target variable properties only describe how one target uses it. Group relations and target properties are paged by one group or target with a maximum page size of 200; remote group-variable searches return at most 50 candidates. In Manual scope, add the variable to the group through savegroupvariablechanges before saving target variable properties.

Data Query and Real-Time Alarm Interface

Historical query contract

Historical paging endpoints use the following common request fields:

Standard history endpoints return wall-clock values projected to the target’s configured time zone. The typed endpoints GetTypedHisDataRecordsByTarget and GetTypedHisNumberDataRecordsByTarget use UTC time ranges and return UTC instants. Custom SQL endpoints return the target table’s raw columns and values: IoTDB and QuestDB wide-table timestamps may retain a Z suffix, which means UTC and must not be converted twice.

Custom SQL columns

Call /api/customsqldatacontroller/GetCustomSqlColumns?targetName=... and build the table and filters from the returned column set. The first column is the target time column used for time-range filtering and descending order; the remaining columns come from CustomTemplateConfig.Columns. Do not force standard CreateTime, VariableId, or Value fields onto a custom wide table.

Custom SQL queries still return paged records and total. total is the database count under the target, time range, and conditions, not records.length; clients must drive pagination from the server total.

Query limits

Typed history, numeric series, and export endpoints are protected by the variable-count, time-range, page-size, series-point, source-record, and export-row limits in Configuration/HisDataQueryOptions.json. Split wide ranges or use series aggregation instead of requesting millions of raw rows in one call.

Typed historical queries should use the UTC start and end times and are protected by variable count, time span, page size, sequence number of points, source record count, and export row limits. The default upper limit is maintained in Configuration/HisDataQueryOptions.json; The integrator should design requirements based on pagination and numerical sequence aggregation capabilities, and should not pull all original records at once over an extremely large time frame.

MQTT clients and MQTT server producers can call the same history capabilities through the default RpcHistory topic. The request topic is RpcHistory/<32-character-hex-request-id>, and the response topic is RpcHistory/<request-id>/Response. The protocol supports target queries, record queries, numeric sequences, historical alarms, alarm confirmation, and request cancellation. Large responses are compressed with gzip and split into Base64 blocks, subject to request body, response body, block size, concurrency, and timeout limits.

Device and forwarding target debugging interface

Rules, scripts, node interfaces

DefinitionJson describes the executable graph with stable node type IDs and named ports; layout is separate. POST validateruleflow returns positioned diagnostics without saving or executing. Enabled flows must pass semantic validation.

POST setruleflowenabled takes id, enabled, and the current controlRevision. Save/control responses report runtimeReloaded and runtimeReloadError separately from configuration persistence. Reload and compare the current revision after a conflict.

Node observations distinguish current activity, last execution, explicit Skipped reasons, and idle waitingReason. Connection activity retains the last actual delivery result/time after later skips. See Runtime Observation.

Plugins, certificates, and system settings interfaces

Log Interface

Management permissions interface

Studio and Watchdog interface

Studio authentication

Sign in to a new Studio installation with admin / 111111. Studio creates the default account when its account configuration is missing. Successful login returns a JWT Bearer valid for seven days. Change the password from the user menu.

Watchdog Authentication

Watchdog supports direct login with the default admin / 111111 account, or the valid credentials already configured. After login, it returns accessToken, username, and expiresAt. The random opaque token is valid for eight hours; the server keeps only its SHA-256 digest in memory. Logout or a Watchdog restart invalidates it.

Request troubleshooting

Keep the request time, endpoint, status and redacted error message. Do not log login ciphertext, tokens, passwords or full production payloads. After a failed import or batch mutation, query the actual saved scope before retrying.

Usage Note

• Interface Paths Call according to the case and path in the table.
• Import/export, upload, and download interfaces may return files or receive form files; please call them in the request format in the interface documentation.
• Management interfaces are restricted by menu, button, and API permissions; If the role authorization is insufficient, even if the token is valid, it may return as no permission.