Custom Connectors
Overview
A custom connector is a data connector extension: code you write and install on your Monospace instance (your running deployment) to reach a system Monospace has no built-in connector for. That system can be a SaaS API such as Stripe, an internal service, or a database without a native connector.
Its data appears as collections in a workspace. Callers use the same REST API, SDK, and Studio as for any database, under the same roles and permissions. Nothing is copied: each request the cache doesn't answer becomes a live query against the external system.
How It Works
- Write it. Create a project with the Monospace CLI. Describe the extension in a config file and write the connector in TypeScript.
- Build it. The CLI validates the config and bundles the code into a build.
- Install it. Copy the build into your instance's extensions directory.
- Connect it. Add a data source in the Studio. The Studio offers installed data connectors alongside the built-in connectors, each marked Extension.
The connector runs inside your instance, isolated from Monospace itself. It can reach only the network hosts you approve for it, and every other network request fails.
Get Started
| Page | Covers |
|---|---|
| Data Connector Quickstart | Build a read-only connector for the Art Institute of Chicago API, install it, and query it in the Studio |
| Build a Stripe Data Connector | A larger connector with writes and tests, built against Stripe's test mode |
| Build Data Connectors with AI Agents | Give a coding agent the extension docs and a starter prompt, and see which steps still need you |
| Install and Manage Extensions | Where your instance loads extensions from, and how to update and remove them |
Design a Connector
| Page | Covers |
|---|---|
| Data Connectors | How a request flows through a connector, and whether your system is a good fit |
| How Data Connectors Run | Where connector code runs, what it can use, and how it reaches the network |
| Map an External Data Source | Translate a system's filters, paging, keys, writes, and errors onto the connector contract |
| Handle Data Connector Errors | Map each failure to the right error class and keep secrets out of responses |
| Test a Data Connector | Test from lint and unit tests up to the Studio |
| Manage Data Sources | Create, update, recreate, and delete the data sources that use a connector |
Look Up the Reference
| Page | Covers |
|---|---|
| Extension Config and Manifest | extension.config.json, the built manifest.json, and the install directory layout |
| CLI | The monospace extension create and monospace extension build commands |
| Data Connector Module | Every export of @monospace/extension-kit/data-connector |
| Data Connector API | The dataConnector entry, its handlers, the schema document, and query requests |
| Operations and Operators | The operations a collection declares and the filter operators each field type allows |
| Network Permissions | How a connector declares the hosts it reaches, and how you approve them |
| Data Connector Runtime Limits | Hard numbers and fixed rules at runtime |
| Data Connector Limitations | What a connector can't do today, and how to work around it |
Request a Connector
If you'd rather not build a connector yourself, request a built-in connector on the roadmap.
See Also
- Connectors — every way to connect a data source
- Extensions — what extensions are and how they reach your instance
- Data Model — collections, fields, and relations