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

# OpenAPI Import

> Generate OpenCX actions from an OpenAPI spec — upload from the dashboard or sync automatically from CI when the spec changes.

If your product already exposes an OpenAPI spec, you can generate one OpenCX action per operation instead of authoring each by hand.

<Warning>
  **Import replaces every action previously generated from your spec.** Hand-authored actions in the dashboard are left alone. If you mix both, keep hand-authored actions in a clearly separate naming convention.
</Warning>

## What OpenCX Accepts

|                      | Value                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **OpenAPI versions** | 2.0, 3.0, 3.1                                                                                                                  |
| **File format**      | JSON or YAML                                                                                                                   |
| **Base URL**         | Read from `servers[0].url`, or you can override at import time                                                                 |
| **Auth**             | Operations call out auth in the spec, but **secrets** live in global variables — see [Authentication](/actions/authentication) |
| **Default channel**  | Imported actions are enabled on the widget channel only; toggle others from the action's page                                  |

## Custom Extensions

OpenCX reads three vendor extensions to pre-configure each action:

| Extension                        | Effect                                                                        |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `x-open-require-form-submission` | When `true`, the AI pauses on a form the customer must submit before the call |
| `x-open-pinned`                  | When `true`, the action is pinned at the top of the dashboard list            |
| `x-open-tags`                    | Array of tag strings applied to the action for dashboard filtering            |

Drop these at the operation level:

```yaml theme={"dark"}
paths:
  /orders/{order_id}:
    get:
      operationId: getOrder
      summary: Look up an order by ID
      x-open-tags: ['orders', 'support']
      x-open-pinned: true
```

## Upload

<Tabs>
  <Tab title="From the dashboard">
    Go to **[Actions](https://platform.open.cx/actions)**, click **Import from OpenAPI**, and pick your `spec.json` or `spec.yaml`. Watch the actions list for new rows. If validation fails, the dashboard surfaces the first invalid operation — fix and re-upload.
  </Tab>

  <Tab title="From CI">
    Use the public API endpoint `PUT https://api.open.cx/actions/import` with a multipart file upload. Auth is a bearer API key with the `actions:write` scope — generate one under **[Settings → Access](https://platform.open.cx/settings/access)**. See [API authentication](/api-reference/authentication).

    ### GitHub Actions

    ```yaml theme={"dark"}
    name: Sync OpenCX actions

    on:
      push:
        branches: [main]
        paths:
          - 'openapi.yaml'

    jobs:
      sync:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Push spec to OpenCX
            env:
              OPENCX_TOKEN: ${{ secrets.OPENCX_API_TOKEN }}
            run: |
              curl --fail-with-body \
                -X PUT https://api.open.cx/actions/import \
                -H "Authorization: Bearer $OPENCX_TOKEN" \
                -F "file=@openapi.yaml"
    ```

    ### GitLab CI

    ```yaml theme={"dark"}
    sync-opencx-actions:
      image: curlimages/curl:latest
      rules:
        - if: $CI_COMMIT_BRANCH == "main"
          changes:
            - openapi.yaml
      script:
        - |
          curl --fail-with-body \
            -X PUT https://api.open.cx/actions/import \
            -H "Authorization: Bearer $OPENCX_API_TOKEN" \
            -F "file=@openapi.yaml"
    ```

    The import runs in a single transaction — old actions generated from your previous spec are soft-deleted and new ones inserted atomically. No separate cleanup step is needed.
  </Tab>
</Tabs>

## What Fails And Why

| Error                           | What it means                                                                                                                       | Fix                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `failed_to_parse_spec`          | The file isn't valid OpenAPI or the format doesn't match the extension                                                              | Run your spec through a validator; confirm JSON vs YAML          |
| `invalid_tool_schema`           | One operation uses schema features the AI tool-call validator rejects (deeply nested `oneOf`, circular refs, non-JSON-Schema types) | Simplify the offending operation, remove custom types, re-upload |
| `cannot_determine_api_endpoint` | No `servers[0].url` in the spec and no override passed                                                                              | Add a `servers` block, or send `serverBaseUrl` with the API call |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    Hand-author a single action from the dashboard form.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Where secrets live for imported actions.
  </Card>

  <Card title="Execution" icon="diagram-project" href="/actions/execution">
    Timeout, retries, response handling.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    Import errors and post-import failures.
  </Card>
</CardGroup>