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

# OpenAPI

> Connect your REST API

Upload an OpenAPI (Swagger) spec to let your agent call your API endpoints.

## Setup

### 1. Configure Connection

In **Integration → OpenAPI**:

| Field         | Description                                            |
| ------------- | ------------------------------------------------------ |
| **Base URL**  | Your API root (e.g., `https://api.yourcompany.com/v1`) |
| **Auth Type** | None, API Key, Bearer Token, or JWT Forward            |

### 2. Configure Auth

<CodeGroup>
  ```text API Key theme={null}
  Header name: X-API-Key
  Value: your-secret-key
  ```

  ```text Bearer Token theme={null}
  Header name: Authorization
  Value: Bearer your-token-here
  ```

  ```text JWT Forward theme={null}
  Forwards the authenticated user's identity token to your API.
  See OpenAPI Authentication for details.
  ```
</CodeGroup>

### 3. Upload Spec

Drag and drop your `.json` or `.yaml` OpenAPI spec file.

### 4. Enable Tools

Go to [Actions](/agent/actions) and select which endpoints to enable.

***

## Example Spec

```yaml theme={null}
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get order details
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details
```

***

## Client-Side Tools

To let the agent trigger browser-side actions (like navigation), add paths prefixed with `/client/`:

```yaml theme={null}
paths:
  /client/navigateToPage:
    post:
      operationId: navigateToPage
      summary: Navigate to a page
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
```

Then register the matching tool in your frontend:

```javascript theme={null}
window.argide('registerTools', {
  navigateToPage: async ({ path }) => {
    router.push(path);
    return { success: true };
  }
});
```

<Info>
  The `operationId` must match the key in `registerTools`.
</Info>

***

## Tips

* Use descriptive `summary` and `description` fields
* Use clear `operationId` names (`getOrderStatus` not `get1`)
* Only expose safe operations

## Troubleshooting

| Issue               | Solution                                                   |
| ------------------- | ---------------------------------------------------------- |
| Spec won't upload   | Validate at [editor.swagger.io](https://editor.swagger.io) |
| API calls failing   | Check base URL and auth credentials                        |
| Agent not using API | Enable tools in Actions, test in Sandbox                   |

<Card title="OpenAPI Authentication" icon="key" href="/integration/openapi-auth">
  Detailed auth guide including JWT Forward
</Card>