Add New Connector
Connectors are how Airweave pulls data from external systems, turns it into entities, and makes it searchable for agents. If your favorite tool or API is not yet supported, you can build a connector and either use it locally or contribute it back to the community.
This guide will walk you through the full process step by step:
- Setting up your environment and forking the repo
- Defining authentication and configuration schemas
- Creating entity definitions for your data
- Implementing the source connector itself
- Testing your connector inside the Airweave dashboard
Once complete, your connector will behave like any built-in integration. You can create collections, sync data, and query it through Airweave’s search APIs or MCP server.
If you plan to contribute your connector back to the project, please also review our Contributing Guidelines for details on branch naming, development workflow, and pull request process. For help at any point, you can join the Airweave Discord to connect with other contributors and maintainers.
How to add a Connector
Create authentication schema
Define what credentials your source needs in backend/airweave/platform/configs/auth.py.
Create source configuration
Define optional configuration options in backend/airweave/platform/configs/config.py.
Define entity schemas
Create entity schemas in backend/airweave/platform/entities/your_source.py that define the structure of the data in the source.
Key points about entities:
- Inherit from
ChunkEntityfor searchable content (documents, posts, issues) - Inherit from
FileEntityfor downloadable files (PDFs, images, attachments) - Use
Field(...)for required fields,Field(default=...)for optional ones - Add source-specific fields that are relevant for search and metadata
Implement source
Create your source connector in backend/airweave/platform/sources/your_source.py.
Key implementation points:
- Import your custom entity classes
- Use the
@source()decorator with your auth and config classes - Implement
create()classmethod that handles credentials and config - Implement
generate_entities()that yields your custom entity objects - Handle authentication based on your auth type
- Use config options to customize behavior
Test your source
Verify everything works by running Airweave and creating a test connection.
- Start Airweave: Your connector appears automatically in the dashboard
- Create a collection and add your new source
- Test the connection and verify data syncs correctly
- Search your data to confirm everything works end-to-end
File Structure
Your complete implementation will create files in these locations:
Notes
Be careful about what kind of authentication your app uses. Airweave supports many auth types including API keys, various OAuth2 flows, and database connections. Check your data source’s API documentation to determine the correct AuthType to use in your @source() decorator.
For OAuth2 sources, you’ll also need to add your integration to the dev.integrations.yaml file.