Guide

Introduction

Welcome to the Zenative OpenAPI. This document aims to help you understand how to effectively interact with our API. Please read the following sections carefully to understand the basic concepts, authentication methods, request and response formats, and error handling.

Authentication

To access the API, you need to authenticate using the OAuth 2.0 Client Credentials Grant flow. This involves exchanging your ClientId and ClientSecret for an AccessToken.

1. Obtain Credentials: You will need a ClientId and ClientSecret. You can obtain these from the management console. Keep your ClientSecret confidential.
2. Request Access Token: Make a POST request to our token endpoint:
   • URL: https://app.zenativeai.com/connect/token
   • Headers:
     • Content-Type: application/x-www-form-urlencoded
   • Body (form-urlencoded):
     • grant_type=client_credentials
     • client_id=YOUR_CLIENT_ID
     • client_secret=YOUR_CLIENT_SECRET
3. Receive Access Token: If successful, the token endpoint will return a JSON response containing the access_token and its expires_in time (in seconds), among other details.

   {
     "access_token": "YOUR_ACCESS_TOKEN",
     "token_type": "Bearer",
     "expires_in": 3600
   }

4. Use Access Token: Include the obtained access_token in the Authorization header of your API requests, prefixed with Bearer .
   • Example Header: Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens have a limited lifetime. Your application should request a new token before the current one expires or when receiving a 401 Unauthorized response.

Please ensure your ClientId and ClientSecret are kept secure and are not exposed in client-side code or insecure storage.

Refer to the endpoint for more details on obtaining an access token.

Making Requests

API Endpoint

The base URL for all API requests is:

https://app.zenativeai.com/api/platform

Request Methods

We follow standard HTTP methods:

• GET: Used to retrieve resources.
• POST: Used to create new resources.
• PUT: Used to update existing resources.
• DELETE: Used to delete resources.

Request Headers

In addition to the authentication header, you may need to include the following request headers:

• Content-Type: For POST, PUT, PATCH requests, this should typically be set to application/json.
• Accept: Specifies the desired response format, usually application/json.

Request Parameters

• Path Parameters: Embedded in the URL path, e.g., /api/platform/chat/history/chatuser.
• Query Parameters: Appended to the end of the URL, e.g., /api/platform/chat/history/chatuser?sessionId={sessions}.
• Request Body: For POST, PUT, PATCH requests, data is usually sent in the request body using JSON format.

Please refer to the documentation for each specific endpoint to understand the required parameters.

Responses

Status Codes

We use standard HTTP status codes to indicate the result of a request:

• 200 OK: Request successful.
• 204 No Content: Request successful, but no response body (e.g., for DELETE requests).
• 400 Bad Request: Invalid request (e.g., parameter error, format error).

Response Format

Successful requests (2xx status codes) typically return data in JSON format. Error responses (4xx status codes) also return JSON format and include error details.

Successful Response Example (GET /api/platform/knowledge/query/{knowledgebaseId}):

[
  {
    "score": 0.399245607763001,
    "id": "1355084446436425728",
    "byteSize": 221,
    "context": "Knowledge Point Content",
    "tagData": []
  }
]

Error Response Example (POST /api/platform/chat/history):

{
  "data": {
    "model": [
      "The model field is required."
    ],
    "$.sendTime": [
      "Invalid token type String for DateTime conversion."
    ]
  },
  "code": "INVALID_MODEL",
  "msg": "invalid model",
}

Error Handling

When an API request fails, please check the status code and the object in the response body for detailed information. code provides a machine-readable error type, msg provides a human-readable description, and data may contain more specific debugging information.

If you encounter a 500 Internal Server Error, it indicates an issue on our side. Please contact the Zenative team for assistance.

Rate Limiting

To ensure service stability, we implement rate limiting on API requests.

• Limit Rule: 1000 requests per minute per ClientId.
• When the limit is exceeded, the API will return a 429 Too Many Requests status code.
• The response headers may include fields like X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset to indicate the current limit status.

Please design your application to handle rate limiting gracefully, for example, by using an exponential backoff strategy for retries.

Contact Us

If you encounter any problems or have any questions while using the API, please contact us via support@zenative.ai.