> For the complete documentation index, see [llms.txt](https://docs.cerrix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cerrix.com/best-practices-and-guides/using-the-cerrix-api-with-ai-assistants-claude-and-microsoft-copilot.md).

# Using the CERRIX API with AI Assistants (Claude & Microsoft Copilot)

AI assistants such as Claude and Microsoft Copilot can answer questions about your CERRIX data in natural language — "Which controls failed their most recent effectiveness test?", "Summarize the incidents reported this quarter" — by querying the CERRIX API directly. This guide shows three ways to set that up, all based on standard CERRIX API keys and without hosting any additional infrastructure.

## How it works

Modern AI assistants can work with any REST API that is described by an **OpenAPI specification**. The assistant reads the specification to learn which endpoints exist, picks the right one for your question, calls the CERRIX API with your API key (Basic authentication), and formulates an answer from the response.

This guide covers three routes:

| Assistant                 | Integration                                                     | Where it runs         |
| ------------------------- | --------------------------------------------------------------- | --------------------- |
| **Claude Desktop**        | A local tool server generated from the OpenAPI specification    | Your own workstation  |
| **Claude Code**           | Direct API calls from the terminal, guided by the specification | Your own workstation  |
| **Microsoft 365 Copilot** | A custom connector added to a Copilot Studio agent              | Your Microsoft tenant |

## Before you start

1. **Create a CERRIX API key.** Follow [API Key Management & Setup](/cerrix-functionalities/admin-settings/api-key-management-and-setup.md).
2. **Request the CERRIX OpenAPI specification** via the CERRIX service desk. For the Microsoft Copilot route, ask for the **OpenAPI 2.0 (Swagger)** version as well — Power Platform custom connectors import that format.
3. **Plan your IP allowlisting.** API keys are restricted to allowed IP addresses. For Claude Desktop and Claude Code, that is the IP address of your own workstation or (VPN) network. For Microsoft Copilot, calls originate from Microsoft's Power Platform cloud — see the notes in that section.

{% hint style="info" %}
For guidance on which endpoints answer which questions — workflow endpoints versus the DirectData reporting datasets — see [API Documentation](/cerrix-functionalities/admin-settings/api-documentation.md).
{% endhint %}

## Option 1: Claude Desktop

Claude Desktop can run local tool servers on your workstation. An off-the-shelf open-source tool, the **OpenAPI MCP Server** (published by AWS Labs), turns the CERRIX OpenAPI specification into tools Claude can call — no coding required, and your API credentials never leave your machine except to call CERRIX itself.

1. Install the [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) (used to run the tool server).
2. Save the CERRIX OpenAPI specification somewhere permanent on your machine, for example `Documents/cerrix/cerrix-api-openapi.yaml`.
3. In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`. Add:

```json
{
  "mcpServers": {
    "cerrix": {
      "command": "uvx",
      "args": ["awslabs.openapi-mcp-server[yaml]@latest"],
      "env": {
        "API_NAME": "cerrix",
        "API_BASE_URL": "https://[customer short name].cerrix.com/api",
        "API_SPEC_PATH": "/full/path/to/cerrix-api-openapi.yaml",
        "AUTH_TYPE": "basic",
        "AUTH_USERNAME": "<API key Identifier>",
        "AUTH_PASSWORD": "<API key Password>",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}
```

4. Replace the base URL with your own CERRIX environment, the spec path with the location from step 2, and the username and password with the **Identifier** and **Password** of your API key.
5. Restart Claude Desktop. The CERRIX tools appear under the tools icon in the chat input, and you can start asking questions.

{% hint style="info" %}
The CERRIX API exposes many endpoints. If the tool list becomes long, the OpenAPI MCP Server supports filtering which operations are exposed (for example with its `--include-tags` option) so you can limit it to the modules you actually use.
{% endhint %}

## Option 2: Claude Code

Claude Code, Anthropic's agent for the terminal, needs no extra tooling at all: give it the OpenAPI specification and your credentials as environment variables, and it calls the CERRIX API directly.

1. Install [Claude Code](https://code.claude.com/docs/en/overview) and create a working folder, for example `cerrix-assistant`, containing the CERRIX OpenAPI specification file.
2. Make your API key available as environment variables (for example in your shell profile), so the credentials stay out of your prompts and files:

```bash
export CERRIX_API_USER="<API key Identifier>"
export CERRIX_API_PASSWORD="<API key Password>"
```

3. In the same folder, create a `CLAUDE.md` file that tells Claude Code how to reach CERRIX:

```
# CERRIX API

- Base URL: https://[customer short name].cerrix.com/api
- The full endpoint reference is in cerrix-api-openapi.yaml in this folder.
- Authentication: HTTP Basic, using the environment variables
  CERRIX_API_USER and CERRIX_API_PASSWORD. Example:
  curl -s -u "$CERRIX_API_USER:$CERRIX_API_PASSWORD" \
    "https://[customer short name].cerrix.com/api/directdata/v3/risk"
- Use the v3 versions of the risk endpoints.
- Only use GET endpoints unless explicitly asked to create something.
```

4. Start `claude` in that folder and ask your question. Claude Code looks up the right endpoint in the specification, runs the API call, and can aggregate, cross-reference and even chart the results.

## Option 3: Microsoft 365 Copilot (via Copilot Studio)

For Microsoft Copilot, the CERRIX API is added as a **Power Platform custom connector**, which a **Copilot Studio agent** then uses as a tool. This route runs in your Microsoft tenant and can be shared with your whole team through Teams or Microsoft 365 Copilot.

1. Request the **OpenAPI 2.0 (Swagger)** version of the CERRIX specification via the service desk.
2. In the [Power Apps maker portal](https://make.powerapps.com), go to **Custom connectors → New custom connector → Import an OpenAPI file** and upload the specification.
3. On the **Security** tab, choose **Basic authentication**. Label the fields "API key Identifier" and "API key Password" so users know what to enter.
4. Create the connector, then use the **Test** tab: create a connection with your API key's Identifier and Password and test an operation such as *Get Risk Data*.
5. In [Copilot Studio](https://copilotstudio.microsoft.com), create or open an agent, go to **Tools** (Actions), add the custom connector, and select the operations the agent may use. Give the agent instructions about your use case, for example that it should answer questions about risks, controls and incidents from CERRIX data.
6. Publish the agent to the channels where your team works, such as Microsoft Teams or Microsoft 365 Copilot.

A few notes:

* **Connections are per user.** Each colleague who uses the agent connects with their **own** CERRIX API key, so data access follows each user's own credentials.
* **IP allowlisting.** Connector traffic originates from Microsoft's Power Platform, not from user workstations. Add the [outbound IP addresses](https://learn.microsoft.com/en-us/connectors/common/outbound-ip-addresses) for your Azure region to the API key's Allowed IPs.

## Good practices

* **Align with your security and privacy officers.** Data retrieved by the assistant is processed by the AI provider (Anthropic or Microsoft) under your organization's agreements with them. Confirm that the data classification of your CERRIX content fits those agreements before rolling this out broadly.
* **Plan for key renewal.** API keys are valid for at most one year, so schedule the renewal and update the configuration when the key is replaced.

## Questions to try

Once connected, try questions like:

* "Which of our risks have no linked controls?"
* "Which controls failed their most recent effectiveness test, and who owns them?"
* "Summarize the incidents reported in the last quarter by classification."
* "List the measures of improvement that are overdue, grouped by subject."


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cerrix.com/best-practices-and-guides/using-the-cerrix-api-with-ai-assistants-claude-and-microsoft-copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.