Skip to main content

​
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. 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:

​
Creating a Key

Find the applications a Key can be created against, then create one the same way as any direct-credential connection:
kind reflects the parent application, not the connection. You cannot change a connection’s kind; you choose it by choosing the application.

​
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.