> 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/quickstart.md).

# Quickstart

Start calling the MaiAgent platform API: the base URL, two ways to obtain an API key (self-issued by members or issued by administrators), key permissions, and an example of your first request.

This page walks you through preparing to call the platform API: confirm the URL, obtain an API key, and send your first request. Refer to the [API documentation](https://docs.maiagent.ai/api) for endpoint fields and complete examples. For rules that apply across endpoints, such as authentication, rate limits, and error formats, see [API Conventions](https://docs.maiagent.ai/api/preparation/conventions).

## API Integration Documentation and Example Code <a href="#examples" id="examples"></a>

{% embed url="<https://github.com/Playma-Co-Ltd/maiagent-api-examples/>" %}

## Base API URL <a href="#base-url" id="base-url"></a>

```
https://api.maiagent.ai/api/v1/
```

For on-premises and private cloud deployments, replace this with your company's platform domain. Always use the `/api/v1/` prefix for new integrations. See [URLs and Version Prefixes](https://docs.maiagent.ai/api/preparation/conventions#base-url) for details.

## Obtain an API Key <a href="#get-api-key" id="get-api-key"></a>

There are two ways to obtain an API key. Both types of keys are used in the same way when making requests.

### Self-Issued by Members <a href="#self-issued-key" id="self-issued-key"></a>

Any active member of an organization can create their own key in the admin console by selecting their avatar in the upper-right corner → <mark style="color:blue;">Account</mark> → <mark style="color:blue;">API Keys</mark>. No additional permissions are required. The key is created in the **organization you are currently switched to**, and the full key is displayed only once, when it is created. For the steps, see [Members Creating Their Own Keys](https://docs.maiagent.ai/org/developer/api-keys#self-issued-keys) in the user manual.

### Issued by Administrators <a href="#admin-issued-key" id="admin-issued-key"></a>

Administrators with “API Key management permissions” can issue keys for specific members under <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">API Key Management</mark>. They can also set expiration times and requests per minute (RPM), or disable or revoke keys. For the steps, see [Create an API Key](https://docs.maiagent.ai/org/developer/api-keys#create-api-key) in the user manual.

## Key Permissions <a href="#key-scope" id="key-scope"></a>

A key is bound to a member: the organization and permissions used for API calls are determined by that member's identity and role permissions in the organization. Requests do not need a separate organization ID, and there are no endpoint-specific permission scopes. When a member is disabled or removed from the organization, the key becomes invalid immediately. For the full rules and recommendations for integration keys, see [API Conventions: Authentication](https://docs.maiagent.ai/api/preparation/conventions#authentication).

## Send Your First Request <a href="#first-request" id="first-request"></a>

Include the key in the `Authorization` header using the format `Api-Key <key>` (not `Bearer`):

```
Authorization: Api-Key <YOUR API KEY>
```

For example, to list Agents:

```bash
curl https://api.maiagent.ai/api/v1/chatbots/ \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

The response is paginated (`count`, `next`, `previous`, `results`), and all field names use camelCase. See [Pagination](https://docs.maiagent.ai/api/preparation/conventions#pagination) and [Field Format](https://docs.maiagent.ai/api/preparation/conventions#field-format) for details. If you receive a `401`, check the key's status and the header format. See [Error Responses](https://docs.maiagent.ai/api/preparation/conventions#errors).

## Next Steps <a href="#next-steps" id="next-steps"></a>

* Endpoint and authentication details: [API Documentation: API Authentication](https://docs.maiagent.ai/api/preparation/authentication)
* Rules across endpoints: [API Conventions](https://docs.maiagent.ai/api/preparation/conventions)
* Create conversations and send messages and attachments: [Create Conversations and Messages](/tech/en/api-integration/conversations-and-messages.md)
* Get Agent replies (streaming or synchronous): [Conversation and Message Replies (Streaming/Synchronous)](/tech/en/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md)
* Manage knowledge base files and retrieval: [Using the Knowledge Base—Upload, Search, and Manage](/tech/en/api-integration/knowledge-base-api.md)
* Push conversation events to your system: [Webhook](/tech/en/serve/webhook.md)


---

# 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/quickstart.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.