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

# Public endpoints and schemas

> Public Loadout OpenAPI operation paths, request fields, response envelopes, and the source for live Action schemas.

The CLI reads an authenticated OpenAPI document and sends JSON to the corresponding operation routes. Prefer the CLI for agent workflows. These HTTP details are for developers who need to understand or integrate the same public contract; they do not describe internal or admin APIs.

```text theme={null}
GET  https://loadout.aident.ai/api/openapi/loadout.json
POST https://loadout.aident.ai/api/openapi/loadout/{operationId}
Content-Type: application/json
Authorization: Bearer <authorized Aident token>
```

Use Aident OAuth for an authorized caller. Do not put access tokens in a page, repository, example payload, or browser URL. The OpenAPI document is filtered by the caller's access and is the current source for complete JSON Schemas, enums, and response types. The table below covers the public workflow operations; their field lists are intentionally concise.

## Discovery and execution operations

| Operation ID / POST path suffix | Request JSON fields | Result |
| - | - | - |
| `loadout_capabilities_search` | `query?: string` or `queries?: string[]` (up to 10); optional `types`, `scope`, `limit` (1 to 100), `offset` | Matching Actions, Integrations, or Skills with canonical names. |
| `loadout_capabilities_get` | `name: string`; optional `parts: string[]` | Metadata and requested schema parts for one exact capability. |
| `loadout_capabilities_preflight` | `name: string`; optional `input: object` | Input validation and a side-effect-free USD estimate when input is valid. |
| `loadout_capabilities_execute` | `name: string`; optional `input: object`, `accountAlias: string or null`, `approvalToken: uuid`, `acknowledgementScope: once, session, or always`, `timeoutSec: integer` | The Action result and duration, or a typed error. |

For `capabilities_search`, use `types: ["action"]` for executable external operations. For `capabilities_get`, useful `parts` include `inputSchema`, `outputSchema`, `description`, and `examples`. The `input` object for preflight and execute is **Action-specific**. Read its current `inputSchema` from `capabilities_get` before constructing it. Action names use the form `<integration-type>:<integration-id>:<action-id>`.

### Request examples

Each example body goes to `POST /api/openapi/loadout/<operationId>` with the matching operation ID from the table. Replace the Action name and input with values returned by discovery and `capabilities_get`.

```json theme={null}
{ "query": "search customer email", "types": ["action"], "limit": 5 }
```

```json theme={null}
{ "name": "<exact-action-name>", "parts": ["description", "inputSchema", "outputSchema", "examples"] }
```

```json theme={null}
{ "name": "<exact-action-name>", "input": { "<field-from-live-schema>": "<value>" } }
```

The last shape is shared by preflight and execute. Execution can also select an account alias or carry a one-time approval token. Neither is a substitute for getting the user's authorization for the proposed Action.

## Guidance, access, and audit operations

| Operation ID / POST path suffix | Request JSON fields | Result |
| - | - | - |
| `loadout_skills_search` | `query: string` (1 to 500 characters); optional `tags`, `category`, `limit` (1 to 50), `cursor`, `sort` | Public Skill snippets and pagination cursor. |
| `loadout_skills_read` | `name: skill:<uuid>`; optional `artifactVersionId: uuid`, `parts`, `paths`, `traversal` | One immutable Skill revision and its requested files. |
| `loadout_vault` | `action?: status, connect, or disconnect`; optional `integrationId`, `integrationIds`, `capabilityNames`, `accountAlias` | Connection state, connection URL, or disconnection result. |
| `loadout_audit` | `action?: recent or summary`; optional `limit` (1 to 200), `integrationId`, `status`, `dateFrom`, `dateTo`, `scope` | Action-call rows or usage summary. |
| `loadout_bug_submit` | `report: string` (redacted Markdown, up to 20,000 characters); optional `surface: string` (up to 120 characters), `agentSessionId: string` | `{ recorded: true, targetType: "loadout_bug", ticketId: uuid }` on success. |

The same `loadout_vault` endpoint backs the CLI's `vault status`, `vault connect`, and `vault disconnect` commands. `loadout_audit` backs `audit recent` and `audit summary`. When connecting from an agent, omit plaintext `credentials` and show the user the returned Aident connection URL. Do not disconnect or replace an account without the user's authorization.

### Request examples

```json theme={null}
{ "query": "triage customer requests", "limit": 5 }
```

```json theme={null}
{ "name": "skill:<uuid>", "artifactVersionId": "<uuid-from-search>" }
```

```json theme={null}
{ "action": "status", "integrationId": "<integration-id>" }
```

```json theme={null}
{ "action": "recent", "limit": 20, "scope": "mine" }
```

These bodies correspond to `loadout_skills_search`, `loadout_skills_read`, `loadout_vault`, and `loadout_audit` in order. Read the live OpenAPI document for optional filters and full nested schemas, including Skill traversal state and multi-account connection fields.

## Response envelope

Operation responses use a JSON envelope. The exact `data` schema differs by operation and appears in the live OpenAPI document.

```json theme={null}
{
  "success": true,
  "data": { "...": "operation-specific result" }
}
```

```json theme={null}
{
  "success": false,
  "error": { "code": "error-code", "message": "Human-readable explanation" }
}
```

Check both HTTP status and `success`. An Action result can also contain provider-level fields such as `successful` or `ok`; inspect those before claiming the external operation succeeded. A validation error, missing OAuth scope, or unknown operation can return a typed error. The CLI handles catalog lookup and request routing for you; the [CLI reference](/loadout/cli-reference) shows the matching commands.


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