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

# OpenAPI

> Configure custom actions in Onyx with OpenAPI

You can create custom actions in Onyx using an OpenAPI 3.0 or 3.1 specification of an API.
This enables your AI agents to interact with REST APIs and trigger workflows in external systems.

<Tip>
  Include only the endpoints you want your agent to call in the OpenAPI spec.
  Remove any endpoints you don't want the agent to access.
</Tip>

## Setting Up Custom Actions

<Steps>
  <Step title="Navigate to the Actions Dashboard">
    Click your user profile icon and select **Admin Panel**, then click the **OpenAPI Actions** tab in the sidebar.

    <div style={{ display: 'flex', gap: '1rem', alignItems: 'start' }}>
      <img className="rounded-image" src="https://mintcdn.com/danswer/4ThtzPnPeCwXOo-y/assets/admins/actions/admin_panel_openapi.png?fit=max&auto=format&n=4ThtzPnPeCwXOo-y&q=85&s=a6506b8e66c87fe77a670f1a455ce038" alt="OpenAPI Actions tab in Onyx Admin Panel sidebar" style={{ flex: '0 0 18%', minWidth: 0, objectFit: 'contain' }} width="464" height="1814" data-path="assets/admins/actions/admin_panel_openapi.png" />

      <img className="rounded-image" src="https://mintcdn.com/danswer/4ThtzPnPeCwXOo-y/assets/admins/actions/openapi_dashboard.png?fit=max&auto=format&n=4ThtzPnPeCwXOo-y&q=85&s=c992501302c3ca96eca0dde2cebf17c5" alt="OpenAPI Actions dashboard in Onyx Admin Panel" style={{ flex: '1 1 0%', minWidth: 0, objectFit: 'contain' }} width="1768" height="916" data-path="assets/admins/actions/openapi_dashboard.png" />
    </div>
  </Step>

  <Step title="Add an OpenAPI Action">
    Click the **Add OpenAPI Action** button.

    Paste your OpenAPI spec and configure any required authentication or headers.

    <img className="rounded-image" src="https://mintcdn.com/danswer/4ThtzPnPeCwXOo-y/assets/admins/actions/openapi_modal.png?fit=max&auto=format&n=4ThtzPnPeCwXOo-y&q=85&s=736b5757edee817be0e6df3cb6da7a20" alt="Add OpenAPI Action modal in Onyx Admin Panel" width="1066" height="1754" data-path="assets/admins/actions/openapi_modal.png" />
  </Step>
</Steps>

## Example

The below OpenAPI spec can be used to create a Custom Action for fetching and creating Agents in Onyx.

```json OpenAPI expandable theme={null}
{
  "openapi": "3.1.0",
  "info": {
    "title": "Agents API",
    "version": "1.0.0",
    "description": "Minimal OpenAPI schema for creating and fetching agents in Onyx"
  },
  "servers": [
    {
      "url": "https://cloud.onyx.app/api"
    }
  ],
  "paths": {
    "/persona": {
      "post": {
        "summary": "Create Agent (Persona)",
        "operationId": "create_persona",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "document_set_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "num_chunks": { "type": "number" },
                  "is_public": { "type": "boolean" },
                  "recency_bias": {
                    "type": "string",
                    "enum": ["favor_recent", "base_decay", "no_decay", "auto"]
                  },
                  "llm_filter_extraction": { "type": "boolean" },
                  "llm_relevance_filter": { "type": "boolean" },
                  "tool_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "system_prompt": { "type": "string" },
                  "task_prompt": { "type": "string" },
                  "datetime_aware": { "type": "boolean" }
                },
                "required": [
                  "name",
                  "description",
                  "document_set_ids",
                  "num_chunks",
                  "is_public",
                  "recency_bias",
                  "llm_filter_extraction",
                  "llm_relevance_filter",
                  "tool_ids",
                  "system_prompt",
                  "task_prompt",
                  "datetime_aware"
                ]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Created" }
        }
      }
    },
    "/persona/{persona_id}": {
      "get": {
        "summary": "Get Agent (Persona) By ID",
        "operationId": "get_persona",
        "parameters": [
          {
            "name": "persona_id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  }
}
```