Skip to content

Open API

Guance supports obtaining and updating workspace data by calling Open API interfaces.

For a detailed list of APIs, refer to the Guance Open API Documentation Library.

Authentication Method

Before calling API interfaces, you need to create an API Key as the authentication method.

The interface uses an API Key as the authentication method. The validity of the request is verified through the DF-API-KEY field in the request header, and the workspace to which the request belongs is determined (based on the workspace to which the API Key belongs).

All GET requests (used for data query and retrieval) only require providing DF-API-KEY in the request header as the authentication credential.

Request Structure

Example: Delete a Dashboard (POST Request)

curl -X POST "https://openapi.guance.com/api/v1/dashboard/dsbd_922428e594ba44ce87229b8ca3007a90/delete" \
-H "Content-Type: application/json" \
-H "DF-API-KEY: ${DF_API_KEY}"

Example: Validate Interface (GET Request)

curl -X GET "https://openapi.guance.com/api/v1/validate" \
-H "Content-Type: application/json" \
-H "DF-API-KEY: ${DF_API_KEY}"
Note

The system simplifies HTTP request methods, using only GET and POST. GET is used for data retrieval requests (e.g., "Get Dashboard List"), and POST is used for data modification requests (e.g., "Create Dashboard" or "Delete Dashboard").

Endpoint

SaaS Deployment Node Endpoint
Alibaba Cloud https://openapi.guance.com
AWS https://aws-openapi.guance.com
Note

The private deployment edition also supports Open API access. Please use the actual deployed Endpoint.

Interface Route Naming Convention

Interface routes generally follow the naming convention below:

Naming Convention
/api/v1/{object type}/{object uuid}/{action}

For example:

  • Get Dashboard List: /api/v1/dashboard/list
  • Create a Dashboard: /api/v1/dashboard/create
  • Get a Dashboard: /api/v1/dashboard/dsbd_0e233ee4804aca011ba94a9164a9ed7f/get
  • Delete a Dashboard: /api/v1/dashboard/dsbd_0e233ee4804aca011ba94a9164a9ed7f/delete
  • Modify a Dashboard: /api/v1/dashboard/dsbd_0e233ee4804aca011ba94a9164a9ed7f/modify
  • Get Host Object List: /api/v1/object/host/list
  • Get Process Object List: /api/v1/object/process/list
Note

v1 in the route is the interface version number. Each released version of the interface must be forward compatible. In case of incompatible interface changes or major business adjustments, the version number needs to be incremented.

Response

Interface responses follow HTTP request response specifications:

  • Successful requests return HTTP status code 200.
  • API Key verification failure returns HTTP status code 403.
  • Server-side processing errors or unknown errors return HTTP status code 500.
  • Other errors (such as no permission to access data or the operation object cannot be found) return 403, 404, etc. Specific error definitions are provided below.

Response Example

{
    "code":200,
    "content":{

    },
    "pageInfo": {
        "count": 20,
        "pageIndex": 1,
        "pageSize": 100,
        "totalCount": 10
    },
    "errorCode":"",
    "message":"",
    "success":true,
    "traceId":"3412000720344969928"
}

Common Response Parameters

Field Type Description
code Number Return status code, consistent with the HTTP status code. Fixed at 200 when there is no error.
content String, Number, Array, Boolean, JSON Returned data, specific type depends on the interface business.
pageInfo JSON Pagination information for all list interfaces.
errorCode String Error status code, empty when there is no error.
message String Specific description information corresponding to the error code.
success Boolean Fixed as true when the interface call is successful.
traceId String Unique identifier used to track each request.

Common Error Definitions

Error Code HTTP Status Code Error Message
RouterNotFound 400 Requested route address does not exist.
InvalidApiKey 403 Invalid request API KEY.
InternalError 503 Unknown error.
...

For more information about the API interface list, refer to the Open API Documentation Library.

Feedback

Is this page helpful? ×