> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/getting-started/ai-copilot.md).

# AI Copilot

<figure><img src="https://4113719406-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzU8KYStPfR8N1iZXsgad%2Fuploads%2FxKoULY4CZjYgY21tkOT0%2Fbuild%20with%20ai%20copilot.gif?alt=media&amp;token=0f8c64dc-b2cd-4b5d-bbd1-9d8b78eb541f" alt=""><figcaption></figcaption></figure>

AI Copilot is an assistant built into the Appmixer Designer that builds, edits and explains flows from natural language. Ask it to "Create a flow that posts new Typeform responses to Slack" and it designs the flow directly on the canvas — selecting connectors, wiring components, and filling in parameters.

Copilot can:

* **Build new flows** from a natural-language description.
* **Edit existing flows** — add, replace or remap components in the open flow. For running flows, Copilot works on a draft so the live flow keeps running unchanged.
* **Explain flows** — describe what an existing flow does, step by step.

## Enabling Copilot

Copilot ships as a system plugin of the Appmixer engine. It is loaded when it is listed in the `SYSTEM_PLUGINS` environment variable and an LLM API key is configured:

```
SYSTEM_PLUGINS=copilot
COPILOT_LLM_API_KEY=sk-ant-...
```

Additional configuration:

| Environment Variable                       | Default                                  | Description                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COPILOT_LLM_PROVIDER`                     | `anthropic`                              | LLM provider.                                                                                                                                                                                                                                                                                                                |
| `COPILOT_LLM_API_KEY`                      | *(unset)*                                | LLM provider API key. The plugin is skipped when no API key is set.                                                                                                                                                                                                                                                          |
| `COPILOT_LLM_MODEL`                        | `claude-sonnet-5`                        | LLM model used by the assistant.                                                                                                                                                                                                                                                                                             |
| `COPILOT_LLM_EFFORT`                       | `medium`                                 | Reasoning effort requested from the model on the direct provider path — `low`, `medium`, `high`, `xhigh` or `max`. Requested only on models known to accept it; any other model is sent neither field and runs with its own defaults. Thinking tokens are billed as output tokens. Ignored on the Appmixer Cloud proxy path. |
| `COPILOT_MAX_TOKENS`                       | *(unset)*                                | Per-step output token ceiling. Unset leaves it to the provider — the model's own maximum for a model id the SDK recognizes, but a conservative 4096 fallback for one it does not, so set it explicitly on a deployment pinned to an aliased or unlisted model.                                                               |
| `COPILOT_MAX_TURNS`                        | `25`                                     | Maximum agent turns per chat request.                                                                                                                                                                                                                                                                                        |
| `COPILOT_CONVERSATION_RETENTION_DAYS`      | `0`                                      | How many days a conversation is retained after its last turn. `0` keeps it forever. Expiry is swept periodically by a garbage-collector job, so deletion is not instant. Replaces `COPILOT_CONVERSATION_TTL`.                                                                                                                |
| `COPILOT_CONVERSATION_MAX_STORED_MESSAGES` | `500`                                    | Cap on the messages kept per conversation. The oldest fall off first.                                                                                                                                                                                                                                                        |
| `COPILOT_CONVERSATION_PROMPT_CHAR_BUDGET`  | `400000`                                 | Cap, in characters, on how much of a conversation is replayed into the prompt on each turn. Storage is unaffected and the history endpoint always returns the full transcript.                                                                                                                                               |
| `COPILOT_MAX_RUN_TIME`                     | `600000`                                 | Wall-clock cap (ms) on a single chat turn. A turn runs on the server and is no longer aborted by the client disconnecting, so this is what ends one whose provider connection has stalled.                                                                                                                                   |
| `COPILOT_PRICING_PATH`                     | *(unset)*                                | Optional path to a custom model pricing JSON file used for cost computation in the usage API.                                                                                                                                                                                                                                |
| `COPILOT_LLM_URL`                          | *(unset)*                                | Base URL for direct LLM provider access, e.g. an Anthropic-compatible gateway. Unset uses the provider SDK default. No effect when the Appmixer Cloud proxy is used.                                                                                                                                                         |
| `COPILOT_APPMIXER_CLOUD_API`               | `https://cloud.appmixer.com/api/copilot` | Appmixer Cloud proxy endpoint (OpenAI-compatible).                                                                                                                                                                                                                                                                           |
| `COPILOT_APPMIXER_CLOUD_API_KEY`           | *(unset)*                                | When set, LLM requests are routed through the Appmixer Cloud proxy instead of calling the provider directly.                                                                                                                                                                                                                 |
| `COPILOT_FORWARDED_HEADERS`                | *(unset)*                                | Comma-separated allow-list of request header names forwarded from the incoming chat request to the LLM request. A trailing `*` matches a prefix, e.g. `X-Acme-*,X-Request-Id`. See [LLM gateway headers](#llm-gateway-headers).                                                                                              |
| `COPILOT_LLM_HEADERS`                      | *(unset)*                                | JSON object of static headers added to every LLM request, e.g. `{"X-Acme-Installation": "acme"}`. See [LLM gateway headers](#llm-gateway-headers).                                                                                                                                                                           |
| `COPILOT_LLM_REFUSED_HEADERS_EXCEPTIONS`   | *(unset)*                                | Comma-separated header names lifted from the built-in list of headers that are refused on an LLM request whatever the two settings above say.                                                                                                                                                                                |
| `COPILOT_CUSTOM_CONTEXT`                   | *(unset)*                                | Additional context about your use cases, connectors and data, injected into the system prompt. Up to 16000 characters. See [Writing Custom Context for Copilot](https://docs.appmixer.com/getting-started/ai-copilot/custom-context.md).                                                                                     |
| `COPILOT_TONE_OF_RESPONSE`                 | *(unset)*                                | Tone, vocabulary and register of Copilot's replies. Up to 4000 characters.                                                                                                                                                                                                                                                   |
| `USER_AI_CONTEXT_MAX_LENGTH`               | `8000`                                   | Maximum length of a single user's `aiContext` (see [Per-user context](#per-user-context)). An engine-level setting rather than a Copilot one: the user API enforces it when the field is written, and Copilot trims to it again when reading.                                                                                |
| `COPILOT_VARIABLES_MAX_VARIABLES`          | `100`                                    | Cap on output variables listed per component when Copilot reads live flow variables.                                                                                                                                                                                                                                         |
| `COPILOT_VARIABLES_MAX_OPTION_FIELDS`      | `25`                                     | Cap on inspector fields whose options are read.                                                                                                                                                                                                                                                                              |
| `COPILOT_VARIABLES_MAX_OPTIONS_PER_FIELD`  | `50`                                     | Cap on options read per field.                                                                                                                                                                                                                                                                                               |
| `COPILOT_VARIABLES_MAX_RESPONSE_CHARS`     | `24000`                                  | Cap on the whole variables tool result. Raising these shows the model more data at a higher token cost per request.                                                                                                                                                                                                          |
| `COPILOT_VARIABLES_MAX_EXAMPLE_CHARS`      | `160`                                    | Cap, in characters, on the example value shown next to each output variable: the value it held in the flow's most recent run, or else the example declared in the component manifest. These values reach the model and, when Langfuse tracing is enabled, the traces. `0` switches examples off, so no run data is read.     |
| `COPILOT_LANGFUSE_PUBLIC_KEY`              | *(unset)*                                | Langfuse project public key. Copilot sends traces only when this key and the secret key are both set. See [Tracing Copilot with Langfuse](https://docs.appmixer.com/getting-started/ai-copilot/langfuse.md).                                                                                                                 |
| `COPILOT_LANGFUSE_SECRET_KEY`              | *(unset)*                                | Langfuse project secret key.                                                                                                                                                                                                                                                                                                 |
| `COPILOT_LANGFUSE_BASE_URL`                | `https://cloud.langfuse.com`             | URL of the Langfuse instance: a Langfuse Cloud region or a self-hosted instance.                                                                                                                                                                                                                                             |
| `INTERNAL_API_URL`                         | *(falls back to `APPMIXER_API_URL`)*     | In-cluster engine URL. Copilot calls the platform API to persist flows while building them; set this so those calls do not route through the external load balancer.                                                                                                                                                         |

Copilot's configuration lives in the cluster configuration and can be edited from the Backoffice. Changes apply without restarting a pod.

{% hint style="info" %}
`COPILOT_CUSTOM_CONTEXT` and `COPILOT_TONE_OF_RESPONSE` are injected as a delimited, lower-authority section of the system prompt. They can refine Copilot's context and phrasing, but cannot override its core role, its safety rules or its flow-building rules, and cannot make it reveal the system prompt.
{% endhint %}

When the plugin is not enabled, the Copilot button is automatically hidden in the Designer.

## LLM gateway headers

Some LLM gateways need a header on every request to identify the installation, the tenant or the end user behind it. Copilot can add such headers in two ways. Both are unset by default — nothing changes for a deployment that does not configure them — and both live in the cluster configuration, so they can be edited from the Backoffice without restarting a pod.

* **`COPILOT_FORWARDED_HEADERS`** forwards headers from the incoming chat request, for a value that differs per user or per request.
* **`COPILOT_LLM_HEADERS`** adds static headers to every LLM request, for a value that is the same for the whole deployment.

Both apply to whichever endpoint Copilot talks to: the gateway named by `COPILOT_LLM_URL`, the Appmixer Cloud proxy, or the provider's own API when neither is set. The static headers are also sent with the model availability check Copilot runs at startup.

### Forwarding request headers

`COPILOT_FORWARDED_HEADERS` is a comma-separated allow-list of header names, matched case-insensitively. A trailing `*` matches every header with that prefix:

```
COPILOT_FORWARDED_HEADERS=X-Acme-*,X-Request-Id
```

Only headers named on the list are forwarded from `POST /system-plugins/copilot/chat` to the LLM request. A bare `*` is not a wildcard — the Backoffice rejects it, as it does any entry that is not a valid header name. An entry that can match no header is reported in a warning on every chat request.

{% hint style="warning" %}
The headers have to be added **server-side**, by a proxy in front of Appmixer. A browser cannot send them: the CORS preflight allows a fixed list of headers.
{% endhint %}

### Static headers

`COPILOT_LLM_HEADERS` is a JSON object of headers added to every LLM request:

```
COPILOT_LLM_HEADERS={"X-Acme-Installation": "acme"}
```

Being administrator data, it may carry an `Authorization` header for a gateway that authenticates with a bearer token. On the Appmixer Cloud proxy path that would replace the proxy's own token, so set it only for a direct gateway.

When both settings carry the same header, the static value wins, so a client can never override an administrator-pinned header. A malformed value in the environment is reported and ignored rather than stopping the node; the Backoffice rejects one up front.

### What is never sent

Any holder of a valid access token can call the chat endpoint directly with headers of their choosing, so the forwarded values are treated as untrusted input. Whatever the allow-list matches, these headers are never placed on an LLM request:

* **Credential headers** — `Authorization`, `Proxy-Authorization`, `api-key`, `x-api-key`, `Cookie`, `Set-Cookie`. `Authorization` is the one exception for static headers, as described above; a forwarded header can never carry it.
* **Transport, framing and encoding headers** — `Host`, `Connection`, `Content-Length`, `Content-Type`, `Content-Encoding`, `Accept-Encoding`, `Transfer-Encoding`, `TE`, `Trailer`, `Upgrade`, `Keep-Alive`, `Expect`.
* **Headers the provider SDK owns** — `anthropic-version`, `anthropic-beta`, `User-Agent`.

Further limits apply to every header from either source:

* Values must be printable ASCII. A value carrying a line break is dropped rather than failing the whole chat request.
* A value is capped at 4096 characters.
* At most 32 headers are forwarded per request.
* Only header names are logged, never values, and the values are kept out of the Langfuse traces.

`COPILOT_LLM_REFUSED_HEADERS_EXCEPTIONS` lifts individual names from that list, for a gateway that needs a header the list cannot anticipate:

```
COPILOT_LLM_REFUSED_HEADERS_EXCEPTIONS=api-key
```

{% hint style="warning" %}
An exception weakens the guard for **both** the static and the forwarded headers. A name lifted here can be set by whoever sends the chat request whenever `COPILOT_FORWARDED_HEADERS` also matches it — lifting `x-api-key` on the direct path, for example, would let a caller replace the server's own API key.
{% endhint %}

## Per-user context

`COPILOT_CUSTOM_CONTEXT` applies to everyone on the instance. When different users need different context, each user can also carry their own in the optional `aiContext` field on the user object. Copilot reads it on every chat request and injects it into the system prompt, so its answers and the flows it builds can take account of who it is helping — their timezone or locale, or the group, property or account that a user stands for.

It is aimed at embedded deployments that provision [virtual users](https://docs.appmixer.com/tutorials/appmixer-virtual-users.md) through the admin API, where a single Appmixer user often represents a whole customer, site or tenant.

### Setting the field

`aiContext` is written through the [User API](https://docs.appmixer.com/api/user.md), either when the user is created:

```bash
curl -XPOST "[TENANT_API_URL]/user" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
        "username": "tower@acme.example",
        "email": "tower@acme.example",
        "password": "[PASSWORD]",
        "aiContext": "Timezone: Europe/Prague. This user represents Acme Tower, a 40-unit residential building. Flows built here usually notify the building manager."
      }'
```

or later, on an existing user:

```bash
curl -XPUT "[TENANT_API_URL]/users/[USER_ID]" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "aiContext": "Timezone: America/New_York. Represents the Brooklyn site." }'
```

Send `null` or an empty string to clear it:

```bash
curl -XPUT "[TENANT_API_URL]/users/[USER_ID]" \
  -H "Authorization: Bearer [ADMIN_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{ "aiContext": null }'
```

The field is returned by `GET /user`, `GET /users/:userId` and `GET /users`, so a user can read the context that describes them.

{% hint style="warning" %}
Writing `aiContext` always requires an **admin token** — including on `POST /user`, which is open to unauthenticated sign-ups by default. Copilot splices the value into its system prompt, so letting end users set their own would be a prompt-injection vector. A request without the `admin` scope is rejected with `403 Setting aiContext requires the admin scope.`
{% endhint %}

### Limits and precedence

* The value is capped at `USER_AI_CONTEXT_MAX_LENGTH` characters, 8000 by default. The API rejects a longer value outright; Copilot also trims when reading, so an oversized stored value can never bloat the prompt.
* Like `COPILOT_CUSTOM_CONTEXT`, the text is injected as a delimited, lower-authority **User AI Context** section. It can inform Copilot's answers, but cannot change its core role, override its safety or flow-building rules, or make it reveal the system prompt.
* The field is optional and backward compatible: a user without it produces exactly the same prompt as before the field existed.

## Using Copilot in the Designer

Open a flow in the Designer and click the Copilot button to open the chat panel. Type what you want to build or change. Copilot streams its progress, and when it produces a flow, the canvas is updated and reloaded.

* The conversation is stored per flow on the server. Re-opening the panel on the flow restores its latest conversation, also after a page reload or in another browser.
* Replies are rendered as Markdown.
* The panel is resizable — drag its edge to change the width, or double-click the resize handle to reset it to the default width.
* A hint under the chat composer — *"AI Copilot can make mistakes. Please double-check your flows."* — reminds users to review what the Copilot builds. Embedding hosts can reword or hide it; see the widget options below.
* When editing a **running** flow, Copilot's changes are applied to a draft — publish the draft to apply them (see [Flow Versioning](https://docs.appmixer.com/api/flows.md#flow-versions)).

### Designer widget options

When embedding the Designer via the [Appmixer UI SDK](https://docs.appmixer.com/appmixer-ui-sdk/ui-and-widgets/designer.md), the Copilot panel can be configured with the `options.copilot` object:

```javascript
appmixer.ui.Designer({
    el: '#designer',
    flowId: FLOW_ID,
    options: {
        copilot: {
            // Show the built-in, localized example prompts:
            examplePrompts: true,

            // — or — provide your own (replaces the defaults):
            // examplePrompts: [
            //     'When a Stripe payment succeeds, add a row to Google Sheets',
            //     'Summarize new Zendesk tickets to Slack every morning'
            // ]

            // Omit or set false to keep them hidden (default).

            // Reword the hint under the chat composer — e.g. if you call your flows
            // something else:
            disclaimer: 'AI Copilot can make mistakes, please double-check your automations.'

            // Omit it to keep the built-in text (shown by default), or set false to
            // hide it.
        }
    }
});
```

To reword the hint for more than one language, override the localization key `ui/designer/copilotPanel/disclaimer` rather than passing a string — the option holds one value for every language, while the key can be translated per language. Overriding that key with an empty string hides the hint, the same as `disclaimer: false`.

## Monitoring AI Usage

The **Insights** menu in Appmixer Studio contains two sections:

* **Flow activity** — the flow execution logs (previously the "Insights" page).
* **AI usage** — Copilot consumption and cost monitoring. This section is visible to administrators only.

The **AI usage** page shows:

* Summary cards with the total spend, the number of requests and the total tokens consumed in the selected period, including an input/output token breakdown.
* Daily consumption for the selected month.
* A paged breakdown table grouped by user, group or scope, with free-text search. Expanding a row drills down into the individual LLM requests (or the users within a group/scope), also paged.

The page is backed by the usage API described below.

## Copilot API

All Copilot endpoints live under the `/system-plugins/copilot` prefix and require a valid access token.

### Chat

<mark style="color:green;">`POST`</mark> `[TENANT_API_URL]/system-plugins/copilot/chat`

Send a chat message. The response is a Server-Sent Events (SSE) stream.

#### Request Body

| Name                                      | Type   | Description                                                                                                             |
| ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| message<mark style="color:red;">\*</mark> | string | The user's message.                                                                                                     |
| threadId                                  | string | Conversation thread ID. Omit to start a new conversation (a new ID is generated and returned in the `connected` event). |
| flowId                                    | string | Optional ID of the flow to give Copilot as context, enabling editing/explaining of that flow.                           |

#### SSE events

`connected` (carries the `threadId`), `text-delta` (streamed assistant text), `tool-call` / `tool-result` / `tool-error` (progress of the assistant's tool use), `flow-result` (the generated flow descriptor with `flowName`, optional `followUpQuestions` and an optional `validationUnavailable` flag, set when flow validation could not be reached — clients can use it to warn that the flow was not validated), `done` (carries token `usage`) and `error`.

#### `flow-result` fields

| Field                   | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowId`                | string or `null` | The flow Copilot works on: the flow being edited, or the one Copilot created. `null` when there is none, for example because saving a new flow failed; `flow` is then the only copy of the result.                                                                                                                                                                                                                                                                                 |
| `flow`                  | object           | The flow descriptor.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `flowName`              | string           | Name of the flow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `followUpQuestions`     | string or `null` | What the user still has to do, as Markdown. A notice in English is appended as one more paragraph for each list below that is present, and for `validationUnavailable`.                                                                                                                                                                                                                                                                                                            |
| `saveError`             | string           | The last save failed, so `flow` is newer than what is stored in `flowId`, for example because the flow is running.                                                                                                                                                                                                                                                                                                                                                                 |
| `snapshotVersionId`     | string           | ID of the [flow version](https://docs.appmixer.com/api/flows.md#flow-versions) Copilot created before its first change in this request: the flow as the user had it. Absent when Copilot created the flow, when the flow was empty and when no save was attempted.                                                                                                                                                                                                                 |
| `snapshotError`         | string           | Copilot changed the flow, but could not create that version first, so the earlier state is not kept.                                                                                                                                                                                                                                                                                                                                                                               |
| `validationUnavailable` | boolean          | `true` when the returned flow was not validated: the validation could not be reached, or Copilot's final save changed the flow after the last validation.                                                                                                                                                                                                                                                                                                                          |
| `removedOptionValues`   | array            | Settings the last save left out because their value is not one the component offers. Each item has `componentId`, `componentType`, `field`, `descriptorPath`, `removed` (the values left out) and `fieldDropped` (`true` when the whole field was left out, `false` when only some of its values were).                                                                                                                                                                            |
| `unknownPorts`          | array            | Connections Copilot removed because they named a port that does not exist. Each item has a `componentId` and `errors`. Each error has the `keyword` `unknownPort`, a `message`, a `descriptorPath` (`source.<inPort>`, or `source.<inPort>.<upstreamId>` for an output port of the upstream component) and `params` with the `port`, the `validPorts` and `portOwnerId`, the component the port belongs to. For an output port, that is the upstream component, not `componentId`. |
| `unavailableComponents` | array            | Components (`componentId`, `componentType`) the user is not allowed to use, for example because the component ACL disables them. The flow is saved, but it does not start until they are removed or enabled for the user.                                                                                                                                                                                                                                                          |
| `hiddenComponents`      | array            | Components (`componentId`, `componentType`) marked private that the user may not see. The Designer shows them as unknown steps that cannot be opened, but the flow runs them.                                                                                                                                                                                                                                                                                                      |
| `orphanComponents`      | array            | Components Copilot added in this request with nothing connected to them, so they never run. Each item has a `componentId` and `errors`. Each error has the `keyword` `orphanComponent`, a `message`, the `descriptorPath` `source` and `params.validPorts`, the input ports a connection can go to.                                                                                                                                                                                |

The lists are present only when they are not empty. The `message` of an error is written for Copilot's model; to tell the user, show the notice from `followUpQuestions` or build your own text from the other fields.

### List Conversations

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/conversations`

{% hint style="info" %}
Available since Appmixer 6.5.5.
{% endhint %}

Return the signed-in user's stored conversations, the most recently changed first. A conversation in which nothing was stored yet, for example one whose first turn failed, is not listed. The Designer uses this endpoint with `flowId` and `limit=1` to resume the latest conversation of a flow.

`curl "[TENANT_API_URL]/system-plugins/copilot/conversations?flowId=9c4673d7-a550-45a2-91c1-ad057fac0385&limit=1" -H "Authorization: Bearer [ACCESS_TOKEN]"`

#### Query Parameters

| Name   | Type   | Description                                                                                                      |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------------- |
| flowId | string | Only the conversations bound to this flow.                                                                       |
| offset | number | Number of conversations to skip. `0` by default.                                                                 |
| limit  | number | Maximum number of conversations returned, `1` or more. `50` by default; a larger value than `200` returns `200`. |

An empty `flowId` or one sent more than once answers `400`, and so does an `offset` or `limit` that is not a whole number, or a `limit` of `0`.

#### Response

```json
{
  "items": [
    {
      "threadId": "2f0c7f4e-8a51-4c1e-9d36-0b8f2b6e4a19",
      "flowId": "9c4673d7-a550-45a2-91c1-ad057fac0385",
      "createdAt": "2026-09-08T09:12:44.102Z",
      "updatedAt": "2026-09-08T09:20:03.551Z"
    }
  ],
  "totalCount": 3
}
```

`totalCount` is the number of matching conversations before `offset` and `limit` apply. `flowId` is `null` for a conversation not bound to a flow. Read the messages of a conversation with [Get Conversation](#get-conversation).

### Get Conversation

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/conversations/:threadId`

Return the transcript of a prior conversation (`{ threadId, messages: [{ role, content }] }`). Users can only read their own threads. Returns an empty message list for a thread the conversation garbage collector has already swept (see `COPILOT_CONVERSATION_RETENTION_DAYS`).

### Enabled Check

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/enabled`

Returns `{ "enabled": true }` when the Copilot plugin is loaded. Clients use this to decide whether to show Copilot UI.

### Usage

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/usage`

Aggregated LLM usage and cost. Admin only.

#### Query Parameters

| Name    | Type   | Description                                                                               |
| ------- | ------ | ----------------------------------------------------------------------------------------- |
| from    | string | Start of the period (ISO date). Defaults to the start of the current month.               |
| to      | string | End of the period (ISO date). Defaults to now.                                            |
| groupBy | string | `user` (default), `group` or `scope`.                                                     |
| user    | string | Filter by user ID.                                                                        |
| group   | string | Filter by group ID.                                                                       |
| scope   | string | Filter by scope.                                                                          |
| q       | string | Free-text filter.                                                                         |
| offset  | number | Optional paging offset. Omit both `offset` and `limit` to return the complete result set. |
| limit   | number | Optional page size (must be a positive integer).                                          |

#### Response

The response contains the aggregated `rows` for the requested page, a `totalCount` with the number of rows in the whole filtered set, and `totals` that are always computed over the **full** filtered set — a paged response still describes the whole reporting window, not just the page. Rows are ordered deterministically (request count descending), so pages are stable across requests. When grouping by `group` or `scope`, each row also contains a per-user breakdown.

{% hint style="info" %}
Cost is computed from the model pricing table (see `COPILOT_PRICING_PATH`). Requests made with models that have no pricing entry do not add to the cost — they are reported with their token counts but priced as zero.
{% endhint %}

### Daily Usage

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/usage/daily`

Daily consumption totals for a month (`month=YYYY-MM`, defaults to the current month; optional `user`, `group`, `scope` filters). Admin only.

### User Usage

<mark style="color:blue;">`GET`</mark> `[TENANT_API_URL]/system-plugins/copilot/usage/user/:userId`

Individual LLM request breakdown for a user (optional `from`/`to`). Admins can view any user; non-admin users can only view their own usage.

Supports the same optional `offset`/`limit` paging parameters as the [Usage](#usage) endpoint and returns a `totalCount` alongside the request rows. Omitting `offset` and `limit` returns the complete list. Rows are ordered by timestamp, newest first.


---

# 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.appmixer.com/getting-started/ai-copilot.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.
