• English

      • Open Platform API

      The Open Platform is a separate API for external systems. Use these APIs to add HeiChat's open capabilities to your own system.

      Use the Base URL shown on the credential page in the admin app. All requests must use HTTPS.

      Authentication

      Send both headers on every request:

      X-Platform-Access: pk_...
X-Platform-Secret: sk_...

      The access key identifies the shop. The secret proves the caller is allowed to use that key. Do not send the secret in query parameters, logs, or client-side code.

      The following cases all return 401. The API does not distinguish between them:

      • The access key or secret is missing
      • The secret does not match
      • The credential is disabled
      • The shop is disabled

      The secret is shown only once, when the credential is created in the admin app. It cannot be retrieved later.

      Rate limits

      Limits are applied per shop, not per access key.

      PlanRequests per minuteRequests per calendar month
      No paid plan101,000
      Pro Basic, Pro105,000
      Pro Plus and above3020,000

      The month is a UTC calendar month. Usage already consumed is not cleared when the plan changes. Both limits apply to every Open Platform request.

      When a limit is exceeded, the API returns 429 and a Retry-After header. The value is the number of seconds to wait before retrying. A per-minute limit resets at the next minute. A monthly limit resets at the next UTC month.

      Repeated invalid credentials can return 429 before the shop quota is affected.

      Errors

      Only non-2xx responses return an error object:

      {
  "error": "RATE_LIMITED",
  "message": "rate limit exceeded"
}

      error is a stable code for programs. message is a short human-readable description.

      HTTPerrorWhen it happens
      400INVALID_REQUESTA required field is missing, blank, or a parameter is out of range.
      401UNAUTHORIZEDThe access key or secret is missing, does not match, or the credential is disabled.
      403FORBIDDENThe caller is authenticated, but the operation is not allowed.
      404NOT_FOUNDThe resource does not exist, or it does not belong to the authenticated shop.
      409QUOTA_EXCEEDEDA business quota has been reached.
      429RATE_LIMITEDThe per-minute limit, monthly limit, or failed-authentication limit was exceeded.
      500INTERNAL_ERRORAn unexpected server error occurred.

      A missing resource and a resource owned by another shop both return 404.

      Response format

      • 200 and 201 return a JSON object. There is no code, message, or data wrapper.
      • 204 has no body.
      • Timestamps use UTC and ISO-8601, for example 2026-09-04T00:00:00Z.
      • A list endpoint returns an object with items and pagination fields. It does not return a bare array.
      • Existing fields are not removed or renamed. New fields may be added. Ignore unknown fields when parsing responses, so an added field does not break deserialization.

      Available APIs

      • Knowledge Base API: List, get, and delete knowledge entries, and create a user-input entry.
      • Conversations API: List conversations, and get one conversation with its messages.