Custom Connectors

Custom connectors allow you to integrate data from sources not supported by our native connectors, or when you need to manage the connection and ingestion process yourself.

When to use one

Reach for a custom connector when:

You want to manage the connection yourself. Stand up your own pipeline against any source — including ones we support natively — and forward the same first-party event shapes (email, page, message, …) to Adapter via /ingest/typed. Downstream processing — entity extraction, relationship resolution, the whole pipeline — runs identically.
The source isn’t on the supported providers list. Internal tools, legacy systems, anything you can hit with HTTPS — push it as a typed kind if it fits one of our shapes, otherwise as custom.
You want to mix typed first-party data with arbitrary records that Adapter doesn’t otherwise see — system logs, ticket metadata, audit events. One connector can emit any combination of kinds it’s configured to accept.

Creating a connector

Open the Console

Go to Connectors in mind.adapter.com and switch to the Custom tab. Click Create connector.

Name it

Give it a display name and a source slug (auto-derived from the name, lowercase + hyphens). The slug is immutable after creation — it shows up in the event source (custom:your-slug), the storage path, and the name of the table your records land in. Use lowercase letters, digits, _ and -, up to 48 characters. Each slug can be used once per workspace, and - and _ count as the same character.

Pick accepted kinds

Select which first-party event types this connector may emit (email, page, message, calendar, issue, or generic custom). Selecting none means all kinds are accepted. Anything outside the list is rejected with a 400.

Save the connector ID

The console shows the connector_id. Copy it — you’ll need it in the ingest endpoint paths below.

Create an API key

Create an API key under Settings → API keys and store it securely — the secret is shown only once. See API keys for the full flow. Use this pk_live_… key as the bearer token when calling the ingest endpoints.

Pushing data

Each connector exposes four ingest endpoints under /v1/custom-connectors/{connector_id}. All require Authorization: Bearer pk_live_….

Typed events (recommended)

Use the typed path when your data fits one of Adapter’s first-party shapes (email, page, etc.). Adapter applies the same processing as native connectors — entity extraction, relationship resolution, the works.

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "kind": "email",
        "payload": {
          "sender": "alice@acme.com",
          "subject": "Q2 review",
          "body_snippet": "Numbers look good."
        }
      }
    ]
  }'

The response echoes an external_ids list — useful if you want to look up the resulting document later.

Generic events

When your data doesn’t fit a typed shape — free-text notes, log lines, custom records from a tool that doesn’t have an Adapter integration — use the generic /ingest endpoint. It stores the data field verbatim as a StandardCustom event with event_type: "adapter.data.custom". Free text:

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "data": { "text": "Quick note from the standup: we shipped the migration." } }
    ]
  }'

The data field accepts any JSON value — it’s stored as-is. There’s no required shape, but using a stable key (e.g. text, body, content) makes downstream queries easier. Custom record with structure:

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "ticket-9182",
        "data": {
          "title": "Customer reported login loop",
          "severity": "high",
          "tags": ["auth", "regression"],
          "reported_by": "casey@acme.com"
        }
      }
    ]
  }'

Batch: post multiple items in a single request — Adapter accepts up to a few hundred per call.

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "external_id": "log-001", "data": { "text": "user signed in" } },
      { "external_id": "log-002", "data": { "text": "password reset requested" } },
      { "external_id": "log-003", "data": { "text": "two-factor enabled" } }
    ]
  }'

LLM enrichment does not run on /ingest (JSON-only). If you have a long blob of text and want Adapter to extract summary/key-facts from it, save it to a file and post via /ingest/upload — the enricher picks up text-based documents, PDFs, images, and Office docs.

Realtime vs bulk

Each pushed item is scheduled on one of two lanes. Fresh items ride the realtime lane, which fires triggers as they are processed. Two kinds of push are moved to the bulk lane automatically, where they are processed on their own queue without delaying other tenants’ realtime data:

Items whose timestamp is more than 7 days old. History is loaded in bulk, and no trigger fires for it.
Any push once a connector has sent more than 2,000 items in the trailing 10 minutes. Chunking a corpus into 500-item requests is still the right shape; the lane just changes.

Bulk items are searchable and askable exactly like realtime ones. The only difference is scheduling and that triggers do not fire for them.

Binary uploads

For files (PDFs, images, Office docs, and text-based documents), use the multipart upload endpoint:

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed/upload" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -F "file=@/path/to/contract.pdf" \
  -F "kind=page" \
  -F 'payload={"title":"Q2 contract"}'

Adapter stores the bytes and runs LLM enrichment automatically — supported types include PDFs, images (PNG/JPEG/GIF/WebP), Office files (.docx/.xlsx/.pptx), and text-based documents. The resulting document carries an enriched_content block with summary, extracted text, and key facts. Use /ingest/upload (without /typed/) for binaries that don’t map to a typed kind.

Delivering a file

A file’s metadata and its bytes travel on different routes. The JSON evidence route (POST /v1/knowledge/connectors/{connector_id}/evidence, and /ingest/typed) carries a file record’s metadata only; it has no field for bytes. To deliver the bytes, upload them here with kind=file and the record’s fields in payload:

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed/upload" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -F "file=@/path/to/q3-review.pptx" \
  -F "kind=file" \
  -F 'payload={"external_id":"deck-q3","filename":"Q3 review.pptx","attachment_source":"api_upload"}'

Adapter stores the bytes and publishes a file record that names them: storage_uri, size_bytes, and a SHA-256 file_hash computed from the uploaded bytes. mime_type, filename and original_filename default to the uploaded part’s content type and filename unless payload sets them. Adapter then extracts the text (PDF, .docx, .pptx, spreadsheets, CSV/TSV and plain text, Markdown or JSON) and indexes it as the file’s content. storage_uri, size_bytes, file_hash and file_hash_algorithm describe the uploaded bytes, so a payload that sets any of them is rejected with a 400. Adapter validates the payload before it stores anything, so a rejected upload (a 400 or a 422) stores no bytes. The bytes are stored at an address derived from their SHA-256, so each file record’s storage_uri keeps naming the bytes it was published with: uploading different bytes under the same external_id stores a second object and publishes a record that names it, and uploading the same bytes again names the same object.

Evidence types

kind also accepts any evidence type from GET /v1/knowledge/evidence-types — order, line_item, deal, contact, company, product, task, invoice and the rest of the catalogue, including provider-shaped types such as salesforce_opportunity and hubspot_deal. The payload is validated against that type’s schema and rejected with a 422 on the first mismatch or unknown field, so nothing is stored partially.

curl -X POST https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "kind": "order",
      "timestamp": "2025-03-14T09:00:00Z",
      "payload": {
        "info_type": "transaction",
        "order_id": "801Wt00000PGtQSIA1",
        "order_number": "00001042",
        "order_date": "2025-03-14T00:00:00Z",
        "total_amount": 1250.0,
        "currency": "USD"
      }
    }]
  }'

Two things differ from the first-party kinds:

Identity. Types with an identity in their update contract (an order’s order_id, a deal’s deal_id, a contact’s contact_id) are stored under the id derived from those payload fields, not under external_id. The response reports the stored id in external_ids; re-pushing the same identity follows the type’s update contract.
Dates. The item’s timestamp is the record’s own time and is what the knowledge graph dates the evidence by when the record carries no created_at. It defaults to payload.timestamp, then the record’s created_at, then the ingest time. Send the business date (order_date, a contract’s signed date) as timestamp so time-filtered retrieval finds the record where it belongs.

Asserting facts

Content alone never creates a person. A name in an email body is a mention, not an identity, so the graph only mints a person from a structured position (a sender, an attendee, a CRM contact). When you know something the data does not say outright, send it as a fact. A fact is your word: Adapter resolves the people and organizations it names against the graph, creates the ones that are missing, records the relation on each, and attaches corroborating evidence it finds by searching the statement. Facts go through the same endpoint as every other kind. The connector needs fact in its accepted kinds, or an empty list, which accepts everything.

curl -X POST https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "kind": "fact",
      "payload": {
        "fact_id": "kapoor-advisor",
        "statement": "Rhea Kapoor'"'"'s financial advisor is Tomas Lindqvist at Northwind Advisory",
        "subject": { "name": "Rhea Kapoor", "email": "rhea@kapoor-holdings.com" },
        "predicate": "advised_by",
        "inverse_predicate": "advises",
        "object": { "name": "Tomas Lindqvist" },
        "reason": "Stated on the onboarding call; the call notes name him.",
        "evidence": [{ "ref": "l1_01hx4k2q8r7m9n3p5t6v8w0y2z", "note": "onboarding call notes" }],
        "asserted_at": "2026-03-02T16:00:00Z"
      }
    }]
  }'

Field	Type	Required	Notes
`fact_id`	string	✓	Your stable id. Re-sending it replaces the earlier assertion.
`statement`	string	✓	The fact in plain language. Parsed when `subject` and `predicate` are absent; indexed for search either way.
`asserted_at`	datetime	✓	When the fact was stated.
`subject`	object		`name` plus optional `kind` (`person` or `organization`), `email`, `domain`, `urn`.
`predicate`	string		Lower snake_case: `parent_of`, `works_at`, `prefers_airline`.
`inverse_predicate`	string		The relation as seen from the object, recorded on it when it is an entity.
`object`	object		Another entity (`name`, `kind`, `email`, `domain`, `urn`) or a literal `value`.
`reason`	string		Why you believe it. Kept on every claim the fact produces.
`evidence`	array		The chain of evidence: `{ "ref": "<urn from a search or ask citation>", "excerpt": "...", "note": "..." }` per item. Each becomes a support on the claims and a citation on the entities.
`confidence`	number		0 to 1, default 1.
`asserted_by`	string		Who stated it.

What happens to a fact:

Resolution. Each party resolves by urn, then email or domain, then an exact name that only one known entity goes by. A name no one is known by mints a new entity at the asserted tier.
Trust. Asserted entities and claims outrank what Adapter inferred from activity and are outranked only by a synced source record such as a CRM contact. A later enrichment pass cannot drop an asserted claim.
Evidence. Supports on a claim are the evidence you passed, marked caller, plus what Adapter found by searching the statement, marked search. Entities cite the fact and the caller’s evidence directly, so a later ask can trace the claim back to the record that justified it.
Graph. The relation appears on both entities and, between two people, as a knows edge carrying the stated relation. Every graph node built from the spine carries source_tier in its metadata (l1_contact, asserted, or inferred), so a reader can separate synced records from stated facts from inference. The fact itself is searchable as evidence and every entity it touched cites it.
Withdrawal. Deleting the item retracts its claims and removes entities that existed only on its word.

Closing the loop from an ask

The common pattern: an ask surfaces someone who has no entity yet, because they never appeared as a sender, attendee, or contact. The answer is right, but there is nothing in the graph to come back to. Take the citations off that response and post them back as a fact.

# 1. Ask. The response cites the evidence it read and the entities it used.
curl -X POST https://api.adapter.com/v1/knowledge/ask \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who handles the Kapoor account'"'"'s tax filings?"}'

# citations: [{ "type": "document", "entity": { "urn": "l1_01hx4k2q8r7m9n3p5t6v8w0y2z", "title": "Onboarding call notes", ... } },
#             { "type": "person",   "entity": { "urn": "l2_01hx4k5d2f8g1h4j7k9m2n5p8r", "name": "Rhea Kapoor", ... } }]

# 2. Assert what the ask found, citing the same evidence and the subject's urn.
curl -X POST https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "kind": "fact",
      "payload": {
        "fact_id": "kapoor-tax-preparer",
        "statement": "Priya Menon prepares the Kapoor account'"'"'s tax filings",
        "subject": { "name": "Rhea Kapoor", "urn": "l2_01hx4k5d2f8g1h4j7k9m2n5p8r" },
        "predicate": "tax_preparer",
        "object": { "name": "Priya Menon" },
        "reason": "Answered by an ask over the onboarding call notes; confirmed by the account owner.",
        "evidence": [{ "ref": "l1_01hx4k2q8r7m9n3p5t6v8w0y2z" }],
        "asserted_by": "ops@yourcompany.com",
        "asserted_at": "2026-03-02T16:30:00Z"
      }
    }]
  }'

After the fact is processed, Priya Menon exists as an asserted person citing the call notes, the relation is on both entities, and the next ask about the Kapoor account finds her directly. Facts are only accepted through this API-key route. Agent write-back over MCP stays a note, since a model’s guess is not an assertion.

Typed event shapes

The payload you send to /ingest/typed is validated against the corresponding type schema. Fields like source, user_id, container_id, and event_type are filled in automatically from the connector — you only supply the fields below. external_id is optional everywhere; Adapter generates one if you omit it. timestamp (ISO 8601) is also optional and defaults to ingest time.

`email`

Field	Type	Required	Notes
`sender`	string	✓	Display name or address.
`subject`	string	✓
`body_snippet`	string		First few hundred chars of the body. Larger content goes through enrichment if attached as a binary.

`page`

For documents — Notion pages, Confluence pages, internal wikis, PDFs uploaded as kind=page.

Field	Type	Required	Notes
`title`	string	✓
`content_snippet`	string
`url`	string		Canonical link back to the source.
`parent_id`	string		Parent page/folder identifier.
`parent_type`	string		e.g. `"folder"`, `"page"`.
`created_by`	string
`last_edited_by`	string
`last_edited_at`	datetime		ISO 8601.

`message`

For chat / Slack-like messages.

Field	Type	Required	Notes
`channel_id`	string	✓
`sender`	string	✓
`text`	string	✓
`is_direct`	boolean	✓	`true` for DMs, `false` for channels.
`thread_ts`	string		Thread parent timestamp, if replying.

`calendar`

Field	Type	Required	Notes
`title`	string	✓
`start_time`	datetime		Use for timed events.
`end_time`	datetime
`start_date`	date		Use for all-day events.
`end_date`	date

Provide either the _time pair (timed) or the _date pair (all-day), not both.

`issue`

For tickets — Linear, Jira, GitHub issues, internal tracker rows.

Field	Type	Required	Notes
`title`	string	✓
`number`	integer		Display number (e.g. `ENG-1234` → `1234`).
`description`	string
`status`	string		Free-form (e.g. `"open"`, `"in-progress"`).
`assignee`	string
`priority`	integer
`labels`	array		List of label strings.
`url`	string
`action`	string		One of `"create"`, `"update"`, `"remove"`.

`custom`

Escape hatch for data that doesn’t fit any typed shape. The whole data payload is stored verbatim.

Field	Type	Required	Notes
`data`	object		Any JSON.

You can also send custom via the simpler /ingest endpoint (no kind field required) — see Generic events above.

Event metadata

Every event carries a metadata field — a flat string-to-string key/value map. Set it in two places; the two get merged at ingest time.

Connector-level metadata

Set metadata on the connector to apply it to every event the connector emits. Useful for source-environment markers (env, region, tenant), data lineage (pipeline, version), or anything that’s constant for the connector’s lifetime.

curl -X POST "https://api.adapter.com/v1/custom-connectors" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme CRM",
    "source_name": "acme-crm",
    "accepted_kinds": ["page"],
    "metadata": { "env": "staging", "pipeline": "acme-crm@v2" }
  }'

Update later with PATCH /v1/custom-connectors/{connector_id} — changes apply to events ingested after the patch lands. Previously ingested events keep the metadata they had at the time.

Per-item metadata

Set metadata on an individual ingest item to apply it to that event only. Useful for per-batch markers, request-correlation IDs, or anything that varies between calls.

curl -X POST "https://api.adapter.com/v1/custom-connectors/$CONNECTOR_ID/ingest/typed" \
  -H "Authorization: Bearer $PK_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "kind": "page",
        "external_id": "doc-001",
        "payload": { "title": "Q2 plan" },
        "metadata": { "batch": "backfill-2026-06-01", "src": "legacy-export" }
      }
    ]
  }'

Supported on both /ingest and /ingest/typed.

Shape

Keys and values are strings. Non-string values are rejected at the API boundary. If you want to express a label-like marker without a meaningful value, use the key as the label and "true" as the value (e.g. { "urgent": "true" }). This shape keeps the field cleanly queryable once retrieval-side filtering ships.

Merge rules

When both are present, per-item metadata overrides connector metadata on key conflict. Disjoint keys merge.

Connector `metadata`	Item `metadata`	Resulting `event.metadata`
`{ "env": "staging" }`	`{ "batch": "b1" }`	`{ "env": "staging", "batch": "b1" }`
`{ "env": "staging", "team": "growth" }`	`{ "env": "prod" }`	`{ "env": "prod", "team": "growth" }`
absent	absent	absent (no `metadata` field)

Where metadata is visible

The merged map lands on event.metadata — a top-level field on every event. That matters because the event’s raw blob is stripped before delivery to subscribers and trigger routing, but metadata is not. Practically:

Trigger rules and webhook subscribers see metadata on the payload they receive.
Stored canonical documents (in object storage) carry the full metadata.
Retrieval via /v1/knowledge/search and /v1/knowledge/ask — pass a metadata object to restrict results to evidence carrying ALL the given key/value pairs (AND-of-exact-match). Max 20 keys, string values only. The same filter applies to /ask: it scopes every search the agent runs and rejects out-of-scope document reads, so the answer can only be grounded in matching evidence.

POST /v1/knowledge/search
{
  "q": "pricing",
  "metadata": { "env": "staging", "team": "growth" }
}

Looking at ingested data

Each connector card in the console has a View Data button that expands to show document counts per resource. Counts update as data lands; if they ever drift, the recovery path is to re-ingest or contact support.

Querying your records with SQL

Every record you push through the generic /ingest endpoint becomes a row of one table per connector in POST /v1/knowledge/query (experimental). The table is named custom_<source slug>, with - written as _, so acme-crm becomes custom_acme_crm. The connector’s table_name field gives the exact name. The table appears after the next knowledge build.

Each top-level field of data becomes a column, typed from its values: integer, number, boolean, date, timestamp, or text. Nested objects and arrays become JSON columns, so flatten records you want to compare field by field.
source_document_id joins the row to its document, and invalid_fields lists any column whose value on that row didn’t match the column’s type (that value is null).
Re-posting the same external_id replaces the row.
Records pushed through /ingest/typed don’t land here: they become their evidence type’s own records.

SELECT severity, count(*) FROM custom_acme_crm GROUP BY severity

Tips

external_id is optional — Adapter generates one if you omit it. Provide your own when you want idempotent re-ingest (re-posting the same external_id overwrites the document).
API key scope: pk_live_… keys are tenant-scoped — one key works against any connector in your container. Rotate by creating a new key and revoking the old.
Deactivation stops new ingest but retains existing data.

Getting Started

Core Concepts

Triggers

Custom Connectors

When to use one

Creating a connector

Pushing data

Typed events (recommended)

Generic events

Realtime vs bulk

Binary uploads

Delivering a file

Evidence types

Asserting facts

Closing the loop from an ask

Typed event shapes

`email`

`page`

`message`

`calendar`

`issue`

`custom`

Event metadata

Connector-level metadata

Per-item metadata

Shape

Merge rules

Where metadata is visible

Looking at ingested data

Querying your records with SQL

Tips

What’s next

API reference

Evidence types

​When to use one

​Creating a connector

​Pushing data

​Typed events (recommended)

​Generic events

​Realtime vs bulk

​Binary uploads

​Delivering a file

​Evidence types

​Asserting facts

​Closing the loop from an ask

​Typed event shapes

​email

​page

​message

​calendar

​issue

​custom

​Event metadata

​Connector-level metadata

​Per-item metadata

​Shape

​Merge rules

​Where metadata is visible

​Looking at ingested data

​Querying your records with SQL

​Tips

​What’s next

API reference

Evidence types

When to use one

Creating a connector

Pushing data

Typed events (recommended)

Generic events

Realtime vs bulk

Binary uploads

Delivering a file

Evidence types

Asserting facts

Closing the loop from an ask

Typed event shapes

`email`

`page`

`message`

`calendar`

`issue`

`custom`

Event metadata

Connector-level metadata

Per-item metadata

Shape

Merge rules

Where metadata is visible

Looking at ingested data

Querying your records with SQL

Tips

What’s next