> For the complete documentation index, see [llms.txt](https://docs.erathos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.erathos.com/connectors/custom-connectors.md).

# Custom Connectors

Not every data source lives in the Erathos catalog. If you have your own API, an internal tool, or another in-house data source, you can point Erathos at a GitHub repository containing your own connec

#### How it works <a href="#how-it-works" id="how-it-works"></a>

1. Install the Erathos GitHub App on the account or organization that owns your connector's code.
2. Tell Erathos which repository to build from.
3. Every push to the watched repository rebuilds its connector image.
4. **Use it like any other connector.** Once the first build succeeds, your connector appears in the datasource catalog with a **Custom** badge, and you set up a connection the same way you would for any built-in connector.

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* Admin access on the GitHub account or organization that owns the repository you want to watch.
* A repository containing a valid **Erathos connector project** (See the [development guide](https://github.com/erathos-data/custom-api-connector))

#### Build your connector with an AI agent <a href="#build-your-connector-with-an-ai-agent" id="build-your-connector-with-an-ai-agent"></a>

You don't have to write the connector YAML by hand. The [connector template](https://github.com/erathos-data/custom-api-connector) ships with an agent skill in `.claude/skills/custom-api-connector/` that teaches a coding agent how to build, fix and validate Erathos connectors.

1. Clone the template (or open your existing connector repository and copy the `.claude/skills/` folder into it).
2. Open the repository with a coding agent such as [Claude Code](https://claude.com/claude-code). Claude Code loads the skill automatically; other agents can be pointed at `.claude/skills/custom-api-connector/SKILL.md`.
3. Describe what you need in plain language, for example *"connect the Acme API to Erathos, syncing orders and customers incrementally"* or *"why is my orders endpoint returning no rows?"*.

The agent then:

* Asks about the API: base URL, authentication, pagination and incremental filters.
* Calls the API and builds `response.path`, `fields` and `primary_key` from real responses instead of guessing them from the docs. Anything it could not verify is marked with an `# UNVERIFIED:` comment.
* Writes `_default.yml` and one file per endpoint, removes the leftover example files, and runs `validate_connector.py` until the connector validates.
* Explains where to get each credential in the source API's console.

Review the changes and push them to your watched repository. Every push is a deploy, so the agent won't push without asking you first.

#### Connect GitHub to your workspace <a href="#connect-github-to-your-workspace" id="connect-github-to-your-workspace"></a>

1. Go to **Connections → New Connection → Select datasource**, or **Settings → Workspace → Repositories**.
2. Click **Connect a custom connector via GitHub**.
3. You're sent to GitHub to install the Erathos GitHub App. Choose the account or organization, then select the repositories you want to give Erathos access to.
4. GitHub redirects you back to Erathos automatically, landing on the datasource screen with the **Watch repository** dialog already open.

If the installation fails or is cancelled, Erathos shows a short message linking back to this page.

#### Watch a repository <a href="#watch-a-repository" id="watch-a-repository"></a>

1. Open **Settings → Workspace → Repositories** and click **Add repository** (or use the **Custom connector via GitHub** tile on the datasource screen).
2. Enter the repository in `owner/repo` format, e.g. `your-org/your-connector`.
3. Click **Watch repository**.

Erathos needs to already have access to that repository through your GitHub App installation. If it doesn't, you'll see:

> Could not access this repository with the connected GitHub App installation.

To fix this, open your GitHub App installation settings on GitHub, grant it access to the repository, and try again.

Once a repository is watched, Erathos triggers the first build. This can take a few minutes — the Repositories page refreshes automatically until it completes.

#### Managing watched repositories <a href="#managing-watched-repositories" id="managing-watched-repositories"></a>

Go to **Settings → Workspace → Repositories** to see everything currently watched, including the repository name and branch.

Click **Remove** next to a repository to stop watching it. This immediately stops it from syncing — its connector will no longer rebuild on new pushes. Confirm the removal in the dialog; this cannot be undone from this page.

#### Using your custom connector <a href="#using-your-custom-connector" id="using-your-custom-connector"></a>

Once the first build succeeds, the connector built from your repository appears in **Connections → New Connection → Select datasource**, marked with a **Custom** badge. Click it, give the connection a name, and continue setup exactly as you would for any other connector.

<br>