> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/api-integration/api-conventions.md).

# API Conventions

A summary of common rules for calling the MaiAgent platform API, including URLs and version prefixes, API Key authentication, rate limits, error responses, pagination, field formats, and upload size l

The [API Conventions](https://docs.maiagent.ai/api/preparation/conventions) page in the API documentation is the authoritative source for rules shared across API endpoints. Refer to that page when building integrations. This page provides only a one- or two-sentence summary of each section, with a link to the corresponding section in the API documentation.

{% hint style="info" %}
For endpoint fields and examples, see the [API documentation site](https://docs.maiagent.ai/api). For instructions on creating and managing API Keys in the UI, see [API Key Management](https://docs.maiagent.ai/org/developer/api-keys) in the user manual.
{% endhint %}

## Base URL and Version Prefix <a href="#base-url" id="base-url"></a>

The SaaS API URL is `https://api.maiagent.ai/api/v1/`. For on-premises and private cloud deployments, replace the domain with your company's platform domain. Always use `/api/v1/` for new integrations. See [API Conventions: Base URL and Version Prefix](https://docs.maiagent.ai/api/preparation/conventions#base-url).

## Authentication <a href="#authentication" id="authentication"></a>

For server-to-server calls, include `Api-Key <key>` in the `Authorization` header. Each key is tied to a member and has the permissions of that member's role. For conditions that invalidate keys, authentication failure responses, and recommendations for integration keys, see [API Conventions: Authentication](https://docs.maiagent.ai/api/preparation/conventions#authentication).

Each member can hold multiple active keys at the same time, with no limit on the number of keys (see [API Key Management](https://docs.maiagent.ai/org/developer/api-keys#key-concepts) in the user manual). Keys can also be issued through the API: administrators can issue keys on behalf of members using `POST /api/v1/organizations/{organizationPk}/api-keys/` (requires the “API Key Management” permission and supports setting a name, expiration time, and RPM), while members can create their own using `POST /api/v1/organizations/{organizationPk}/my-api-keys/`. Revoke keys using the corresponding `DELETE` endpoint. The full key appears only once, in the creation response. For fields, see [Organizations and Members](https://docs.maiagent.ai/api/api-reference/zu-zhi-he-cheng-yuan) in the API documentation.

## Rate Limits <a href="#rate-limits" id="rate-limits"></a>

The platform API has no default global limit. The main limits are RPM per API Key and TPM for AI Gateway. Exceeding a limit returns `429` with `Retry-After`. For the full scope of rate limiting, see [API Conventions: Rate Limits](https://docs.maiagent.ai/api/preparation/conventions#rate-limits).

## Error Responses <a href="#errors" id="errors"></a>

Identify errors using the HTTP status code and `code`; do not match the text in `detail`. For the error response structure, recommended handling for each status code, and cases that return `402`, see [API Conventions: Error Responses](https://docs.maiagent.ai/api/preparation/conventions#errors).

## Pagination <a href="#pagination" id="pagination"></a>

Most lists use page-based pagination with `page` and `page_size` (default 20, maximum 100). Use `next` to retrieve the next page. Conversation and message lists use cursor-based pagination. See [API Conventions: Pagination](https://docs.maiagent.ai/api/preparation/conventions#pagination).

## Field Formats <a href="#field-format" id="field-format"></a>

Response keys always use camelCase. Time fields are typically millisecond timestamp strings. See [API Conventions: Field Formats](https://docs.maiagent.ai/api/preparation/conventions#field-format).

## Upload Size Limits <a href="#upload-limits" id="upload-limits"></a>

The response from `GET /api/v1/allowed-file-specs/` is the authoritative source for upload limits. For current limits by use case, see [API Conventions: Upload Size Limits](https://docs.maiagent.ai/api/preparation/conventions#upload-limits). For the presigned upload flow, see [Presigned File Upload Mode](/tech/en/api-integration/api_knowledge.md).

## Request Content Encoding <a href="#encoding" id="encoding"></a>

All request and response JSON uses UTF-8. Fields such as role instructions (`instructions`) and message content can contain Chinese and other Unicode characters directly, without conversion to ASCII or escaping. Include `Content-Type: application/json` in the request and ensure that your HTTP client sends it using UTF-8 encoding. Response JSON also returns UTF-8 characters directly, without converting them to `\uXXXX`. After an update, use the corresponding `GET` endpoint to read back and verify the stored content. The admin interface displays the same data.

## Request Size and 413 <a href="#request-size" id="request-size"></a>

* The platform API itself does not return `413`. A JSON request body exceeding Django's default limit (2.5 MB) returns `400`. This limit counts only JSON and form fields, excluding multipart file bodies.
* File size limits are determined by `GET /api/v1/allowed-file-specs/`. Exceeding a limit returns `400` when obtaining an upload URL or registering a file. See [Upload Size Limits](#upload-limits).
* Receiving `413` means that the proxy layer in front of the platform (CDN or load balancer) blocked the entire request. This usually occurs when files are embedded in JSON as Base64 or large files are sent directly via multipart. Switch to [Presigned File Upload Mode](/tech/en/api-integration/api_knowledge.md): upload the file directly to storage and include only the file's key in the API request.

## Frequently Asked Questions <a href="#faq" id="faq"></a>

For keys that keep returning `401`, whether a key's call scope can be restricted, and the difference between `/api/` and `/api/v1/`, see [API Conventions: Frequently Asked Questions](https://docs.maiagent.ai/api/preparation/conventions#faq).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/api-integration/api-conventions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.