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

# Platform model

> Applications, connections, tools, and toolsets - how the pieces fit.

## The four building blocks

* **Application** - an integrable product (monday.com, Gmail, Salesforce, Priority...). Identified by a **slug**. Browse via `GET /v1/applications`; the detail view lists the application's authentication methods and whether it supports object selection.
* **Connection** - your authenticated instance of an application (an OAuth grant, an API key, DB credentials...). Identified by an **integer id**. Tools execute *through* a connection. You can mark one connection per application as your **default**.
* **Tool** - a single executable action (create an item, send an email, query records). Identified by a **slug**. The detail view embeds the tool's `inputSchema` and `outputSchema` (JSON Schema) plus capability flags (`supportsFilters`, `supportsSort`, `supportsTopOffset`). Note `supportsTopOffset` means top **and** offset together - i.e. "can I page this tool" - and some tools support capping results without paging (e.g. Salesforce takes `SelectTop` but not offset, so the flag reads `false`). The `inputSchema` is the ground truth: look for `SelectTop` / `SelectOffset` there.
* **Toolset** - a named bundle of connections plus an allow-list of tools, identified by a **GUID**. Toolsets scope what an LLM agent is allowed to call and which connection each application uses.

## Keys vs Integrations

The web UI's Connections page has two tabs, **Integrations** and **Keys**. They are the *same underlying resource*: both are connections, listed by the same endpoint and addressed by the same integer ids. They differ only by the **kind** of the application behind them.

| Web UI tab | `kind` | What it is |
| - | - | - |
| Integrations | `Regular` | A connection to an app you sign in to - typically OAuth. |
| Keys | `Key` | A connection that just holds a credential (an API key) for an app. |

One further value, `MCPClient`, exists and will appear on responses, though `GET /v1/connections` does not serve it.

**On-prem agents are not connections on the API.** The web UI shows them on the Connections page, and they share a table underneath, but `GET /v1/connections` never returns one and `?kind=OPA` is rejected. They have their own resource - `/v1/on-prem-agents`, `client.opa`, `engini opa` - because they carry operations no connection has: a token to rotate, runtime settings to push, logs to collect, an installer to download.

Because it is one resource, there is one command group. To work with what the Keys tab shows, filter:

```bash theme={null}
engini connections list --kind Key
```

### Creating a Key

Find the applications a Key can be created against, then create one the same way as any direct-credential connection:

```bash theme={null}
# 1. Which applications take a key?
engini applications list --kind Key

# 2. What does this one need? (authentication_id + its field names)
engini applications get <slug>

# 3. Create it
engini connections create <slug> --auth <id> --field apiKey=<value>
```

<Note>
  `kind` reflects the **parent application**, not the connection. You cannot change a connection's kind; you choose it by choosing the application.
</Note>

## How a tool finds its connection

When you `POST /v1/tools/{toolSlug}/execute`, the connection is resolved in this order:

1. **Explicit** `?connectionId=` - must belong to you and to the tool's application. If `?toolsetId=` is also present, the connection must be in that toolset.
2. **Toolset** `?toolsetId=` - uses the toolset's connection for the tool's application, and enforces the toolset's tool allow-list.
3. **Default** - your per-application default connection (`PUT /v1/connections/{id}/default`). If you have exactly one connection for the application, it's used and recorded as the default automatically.
4. Otherwise the call fails with `409 NO_DEFAULT_CONNECTION`.

Applications that don't require a connection (`connectionRequirement: "None"`) skip all of this.

## Object selection

Some applications (mostly databases) expose **objects** (tables, entities) that you choose from: refresh the catalog (`refresh-objects`), poll `refresh-status` until it leaves `InProgress`, browse `objects`, then `select-objects` with the ids to activate. Only applications with `supportsObjectSelection: true` use this - the CLI's `engini connect` walks you through it.


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