> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useinvent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Understand general concepts, response codes, and authentication strategies.

<Note>
  **Are you an AI agent?** Everything you need is machine-readable:

  * **OpenAPI spec:** `https://api.useinvent.com/openapi.json`
  * **Index:** [llms.txt](https://docs.useinvent.com/llms.txt) and [llms-full.txt](https://docs.useinvent.com/llms-full.txt)
  * **Any page as Markdown:** add `.md` to its URL (for example [introduction.md](https://docs.useinvent.com/api-reference/getting-started/introduction.md))
  * **Interactive reference:** [api.useinvent.com/docs](https://api.useinvent.com/docs)
</Note>

## Two ways in

| | API | MCP |
| :- | :- | :- |
| **Recommended for** | Scripts, servers and agents that run on their own | Working with an agent yourself, choosing what it can reach |
| **Works in** | Any agent or code | ChatGPT, Claude, Claude Code, Codex, Cursor, OpenCode and other MCP apps |
| **Connect** | `Authorization: Bearer YOUR_API_KEY` | Add `https://api.useinvent.com/mcp` and sign in |
| **Access** | Admin of the key's organization and its sub-organizations | The organizations you pick, with **View** or **Write** each |
| **Revoke** | Delete the key on the API Keys page | **Account → Connected apps**, any time |
| **Set up** | [API Keys page](https://www.useinvent.com/o/settings/api-keys) | [AI Apps (MCP)](/workspace-management/ai-apps) |

Or paste this into your agent (Claude Code, Codex, Cursor, OpenCode or any harness):

```text theme={"system"}
Connect my Invent account and help me manage my AI support assistants.
Read https://useinvent.com/llms.txt and follow it.
```

## Explore the full API

The complete API is described by an OpenAPI 3.1 spec. Browse it interactively or hand the raw spec to your client or agent.

<CardGroup cols={2}>
  <Card title="OpenAPI spec" icon="code" href="https://api.useinvent.com/openapi.json">
    The full machine-readable spec (`openapi.json`). Import it into your client or pass it to an agent.
  </Card>

  <Card title="Swagger UI" icon="compass" href="https://api.useinvent.com/docs">
    Navigate and try every endpoint interactively.
  </Card>
</CardGroup>

### Base URL

The Invent API is built on **REST** principles. We enforce **HTTPS** in every request to improve data security, integrity, and privacy. The API does not support **HTTP**.

All requests contain the following base URL:

```
https://api.useinvent.com
```

### Authentication

To authenticate, you need to add an Authorization header with the contents being `Bearer YOUR_API_KEY`.

```
Authorization: Bearer YOUR_API_KEY
```

Go to the [API Keys page](https://www.useinvent.com/o/settings/api-keys) and create a new API key.

### Permissions and scope

A key is not a master credential. Three boundaries decide what it can reach:

| Boundary | What it allows |
| :- | :- |
| **Route surface** | Keys reach the org routes under `/orgs` and the chat routes under `/chats`. Any other route answers `401`. |
| **Organization** | The org the key was created in, plus that org's sub-organizations when it is a parent key. Any other workspace answers `403`. |
| **Permissions** | The key acts as an Admin of the organization, whoever created it, so it holds every permission. |

Permissions are named `resource:action`: a resource such as contacts, inbox, assistants or tables, at read or write level. Every endpoint requires the one it needs, and a call that lacks it answers `403` with `"message": "ORGS/PERMISSION_REQUIRED"` and the missing permission in `"details"` (for example `"Requires permission: contacts:read"`). The current set lives in the role editor and the permissions matrix in your workspace; [custom roles](/workspace-management/custom-roles) explains both.

Keys cannot be narrowed to a subset of permissions today: a custom role on the person who created the key does not limit it.

### Organization-scoped routes

Resources are under `/orgs/...` (for example `GET https://api.useinvent.com/orgs/assistants`). The API key already names its organization, so the path omits the org id.

To act inside a **sub-organization** with a **parent** key, put the sub-org's id after `/orgs/`: `GET https://api.useinvent.com/orgs/SUB_ORG_ID/assistants`. See [sub-organizations in API Keys](/workspace-management/api-keys#parent-organization-keys-and-sub-organizations).

### Response codes

Invent uses standard HTTP codes to indicate the success or failure of your requests.

In general, `2xx` HTTP codes correspond to success, `4xx` codes are for user-related failures, and `5xx` codes are for infrastructure issues.

| Status | Description |
| - | - |
| `200` | Successful request. |
| `400` | Check that the parameters were correct. |
| `401` | Check that the API key is correct. |
| `403` | Not allowed: wrong workspace, or the endpoint needs a permission the call does not have. |
| `404` | The resource was not found. |
| `429` | The rate limit was exceeded. |
| `5xx` | Indicates an error with Invent servers. |

### Rate limits

Invent enforces rate limits to ensure fair usage of the API. If you exceed a rate limit, you will receive a `429` status code.

Limits are applied **per endpoint** and keyed per caller (your API key's owner, or IP address). They vary by action: write-heavy endpoints are capped much tighter than reads — for example, creating an assistant is limited to **10 per hour**. Expect `429`s on those well below any general per-minute ceiling, and back off when you receive one. A broad edge limit of roughly **500 requests per minute per IP** may also apply at the gateway.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.