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

# OpenAI

> Connect your OpenAI account to Rootly to power AI-assisted incident workflows using your own API key, data agreements, and regional endpoint.

## Introduction

The OpenAI integration lets you connect Rootly to your organization's OpenAI account, using your own API key and Organization ID to power AI-assisted incident workflows. This gives your team control over model selection, data handling, and API usage under your organization's specific agreements with OpenAI — including data retention policies that may differ from Rootly's default OpenAI configuration.

With the OpenAI integration, you can:

* Generate AI-powered summaries, analyses, and responses within incident workflows
* Send custom prompts to GPT and reasoning models with full Liquid template support
* Use a system prompt to define the model's role, tone, or output constraints
* Route requests through a regional OpenAI endpoint to meet data residency requirements
* Access OpenAI's reasoning models (`o1`, `o3`) with configurable reasoning effort and summary output

## Before You Begin

Before setting up the OpenAI integration, make sure you have:

* A Rootly account with permission to manage integrations
* An [OpenAI API key](https://platform.openai.com/api-keys) with the following permissions:
  * **Models** permission set to `Read`
  * **Model Capabilities** permission set to `Write`
* Your [OpenAI Organization ID](https://platform.openai.com/settings/organization/general)

We recommend creating a dedicated API key for Rootly rather than using a personal key. Your key is validated on save and encrypted at rest in Rootly.

## Installation

<Frame>
  <iframe src="https://www.loom.com/embed/d2e9087c9de84b7191d09aa33099b268" frameborder="0" allowfullscreen width="100%" height="400px" />
</Frame>

<Steps>
  <Step title="Open the integrations page in Rootly" icon="plug">
    Navigate to the integrations page in your Rootly workspace and select **OpenAI**.
  </Step>

  <Step title="Enter your API key and Organization ID" icon="key">
    Paste your OpenAI API key and Organization ID into the respective fields. Rootly validates the credentials against the OpenAI API before saving.

    <Frame>
      <img alt="OpenAI integration setup in Rootly showing API key and Organization ID fields" src="https://mintcdn.com/rootly/TIlGh9cK2EiEJpcz/images/integrations/openai/images-1.webp?fit=max&auto=format&n=TIlGh9cK2EiEJpcz&q=85&s=97faf97434fc156c52732a6c9383b957" width="890" height="1546" data-path="images/integrations/openai/images-1.webp" />
    </Frame>
  </Step>

  <Step title="Select a regional host" icon="globe">
    Choose the OpenAI API host for your requests. The default is `api.openai.com`. If your organization requires data to stay within a specific region, select the appropriate regional endpoint:

    | Host                | Region         |
    | ------------------- | -------------- |
    | `api.openai.com`    | Default (US)   |
    | `us.api.openai.com` | United States  |
    | `eu.api.openai.com` | Europe         |
    | `gb.api.openai.com` | United Kingdom |
    | `ae.api.openai.com` | UAE            |
    | `au.api.openai.com` | Australia      |
    | `ca.api.openai.com` | Canada         |
    | `jp.api.openai.com` | Japan          |
    | `in.api.openai.com` | India          |
    | `sg.api.openai.com` | Singapore      |
    | `kr.api.openai.com` | South Korea    |
  </Step>

  <Step title="Integration connected" icon="circle-check">
    <Callout icon="circle-check" color="#DCFCE7">
      Your OpenAI integration is active. The **Create OpenAI Chat Completion** workflow action is now available in your incident and action item workflows.
    </Callout>
  </Step>
</Steps>

## Workflow Actions

### Create OpenAI Chat Completion

Sends a prompt to an OpenAI model and captures the response as a workflow output. Supports both standard GPT models via the Chat Completions API and reasoning models (`o1`, `o3`) via the Responses API.

| Field             | Description                                                                | Required |
| ----------------- | -------------------------------------------------------------------------- | -------- |
| Model             | The OpenAI model to use — fetched from your account                        | Yes      |
| Prompt            | The user message — supports Liquid templating                              | Yes      |
| System Prompt     | Instructions for the model's role or behavior — supports Liquid templating | No       |
| Temperature       | Sampling temperature between `0.0` and `2.0` — controls randomness         | No       |
| Max Tokens        | Maximum number of tokens in the response                                   | No       |
| Top P             | Nucleus sampling probability between `0.0` and `1.0`                       | No       |
| Reasoning Effort  | For reasoning models: `minimal`, `low`, `medium`, or `high`                | No       |
| Reasoning Summary | For reasoning models: `auto`, `concise`, or `detailed`                     | No       |

<Callout icon="code" color="#EDE9FE">
  Use Liquid variables in your prompts to include live incident context — for example `{{ incident.title }}`, `{{ incident.severity }}`, and `{{ incident.description }}`. See the [Liquid variables reference](/liquid/incident-variables) for all available fields.
</Callout>

The **System Prompt** field sets the model's persona or output format — for example: *"You are an incident response assistant. Respond in bullet points. Be concise."*

**Reasoning models** (`o1-*`, `o3-*`) use the OpenAI Responses API instead of the Chat Completions API. When using these models, use **Reasoning Effort** to control how much compute the model uses before responding, and **Reasoning Summary** to control how much of that reasoning is surfaced in the output.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The API key or Organization ID is rejected on save" icon="key">
    Rootly validates your credentials by making a test request to OpenAI. Confirm that the API key is active, has not been revoked, and has the correct permissions: **Models** set to `Read` and **Model Capabilities** set to `Write`. Also verify that the Organization ID matches the organization the API key belongs to.
  </Accordion>

  <Accordion title="The workflow action fails with an authentication error" icon="lock">
    If the integration was working and then stopped, the API key may have been rotated or revoked. Update the key in the integration settings — Rootly re-validates on save. Also confirm the Organization ID has not changed.
  </Accordion>

  <Accordion title="The workflow action fails with a rate limit error" icon="gauge-high">
    OpenAI enforces rate limits based on your usage tier. Running many concurrent workflows may exceed requests-per-minute or tokens-per-minute limits. Consider staggering workflows, reducing token usage with more focused prompts, or upgrading your OpenAI tier.
  </Accordion>

  <Accordion title="A model is not appearing in the model selector" icon="robot">
    The model list is fetched dynamically from your OpenAI account. Rootly filters for `gpt-*`, `o1-*`, and `o3-*` models. If a model you expect to see is missing, confirm your API key has access to it — some models require specific OpenAI tiers.
  </Accordion>

  <Accordion title="Reasoning model parameters are being ignored" icon="brain">
    Reasoning effort and reasoning summary only apply to `o1-*` and `o3-*` models using the Responses API. If you select a standard GPT model, these fields are ignored and only the Chat Completions parameters (temperature, max tokens, top p) apply.
  </Accordion>

  <Accordion title="Liquid variables are not rendering correctly in the prompt" icon="code">
    Check your Liquid syntax — unclosed tags or undefined variables can cause rendering failures. Use the [Liquid variables reference](/liquid/incident-variables) to confirm variable names and test your template in a low-stakes workflow first.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={3}>
  <Card title="Incident Workflows" icon="bolt" href="/workflows/incident-workflows">
    Build workflows that use OpenAI models to analyze, summarize, or respond to incidents.
  </Card>

  <Card title="Liquid Variables" icon="code" href="/liquid/incident-variables">
    Reference for all incident variables available in Liquid-templated prompts.
  </Card>

  <Card title="Rootly AI" icon="robot" href="/ai/ai">
    Learn about Rootly's built-in AI features for incident management.
  </Card>
</CardGroup>