Custom API
The Custom API connector imports records from an HTTP API that answers in JSON: support tickets, CRM leads, knowledge-base entries, product records. You tell it where the list of records is, which records to keep, and which fields make up each document. After the first sync, it keeps reading the API on a schedule, adds new matching records and refreshes the ones that change.
The Custom API connector is turned on per deployment. If Custom API isn't listed under Other Sources in Add Source, it isn't available on yours yet.
When to use it
Use a custom API source when:
- your records live in a system with no built-in connector (a CRM, a helpdesk, an internal service);
- the system has a list endpoint that returns records as JSON, page by page;
- each record also has a detail endpoint, like
/v1/tickets/{id}, that returns the full record.
It's not a fit when the API only answers POST requests for reads, needs a request signature, or returns XML or CSV. Use a built-in connector instead when one exists for your system: Jira, Confluence, Notion and the others handle comments, attachments and permissions that a generic API can't describe.
How it works
Setup has four steps. An Owner or Admin works through them in one dialog:
| Step | What you do | Page |
|---|---|---|
| Connection | Enter the API address, the authentication, the list endpoint and how it pages | Connecting and Choosing records |
| Records | Choose all records, or only those matching up to five conditions, and set the most documents the source may keep | Choosing records |
| Mapping | Choose the record ID, the detail path, the title, the text fields, and optional last-updated and link fields | Mapping fields |
| Review | Check a sample document, then start the first sync | Review, start and re-sync |
After the first Start, the source reads the rest of the list in parts, then checks the API again on a schedule. See Review, start and re-sync and Monitoring and scheduled checks.
Who can do what
| Action | Owner | Admin | Member |
|---|---|---|---|
| Connect, edit, review and start a custom API source | ✓ | ✓ | |
| See the source on the Sources page | ✓ | ✓ | ✓ |
| Browse, re-sync and tag its documents | ✓ | ✓ | ✓ |
| Delete its documents | ✓ | ✓ |
An organization can connect several custom API sources, each to its own API and project.
Where documents go
A source belongs to the project that is current when you connect it, and can't move to another project. Switch projects before connecting. The project needs a vector store and an embedding model before the first sync can add documents.
Limits
| Limit | Value |
|---|---|
| API address | One https:// origin per source; requests never leave it |
| Records per list request (page size) | 1 to 200 (default 100) |
| Fixed query parameters | Up to 20 |
| Conditions | Up to 5, all must match |
| Text fields per document | Up to 50 |
| Most documents per source (Maximum Documents in This Project) | 1 to 100,000 |
| One sync step | Up to 10 list pages, within about 40 seconds |
| New documents added by one step | Up to 10,000 |
| Setup actions that call your API (Test & Continue, Preview Matches, Discover Fields, saving an edit that re-samples, Start) | 30 a minute per organization. One action may make several requests to your API |
| Longest single pass through the list | 100,000 pages |
Next steps
- Connecting: the API address, authentication and allowed origins.
- Choosing records: the endpoint, pagination, conditions and the document limit.
- Mapping fields: turning a record into a document.
- Review, start and re-sync.
- Troubleshooting, FAQ and Glossary.