Skip to main content
POST
Create a custom connector

Body

application/json
name
string
required
source_name
string
required

Immutable slug for this connector: lowercase letters, digits, _ and -, starting with a letter or digit, at most 48 characters. Unique within the workspace, where - and _ count as the same. Records pushed through /ingest become rows of the table custom_<source_name> in POST /v1/knowledge/query, with - written as _.

Pattern: ^[a-z0-9][a-z0-9_-]{0,47}$
Example:

"acme-crm"

accepted_kinds
string[] | null

Kinds this connector may emit: first-party kinds and/or evidence types. Empty/None = all allowed.

metadata
Metadata · object | null

Key/value metadata applied to every event from this connector. String values only.

Example:

Response

Successful Response

Returned on creation. Auth for ingest is via platform API keys (pk_live_…); call /v1/custom-connectors/{connector_id}/ingest… with Authorization: Bearer pk_live_… to push data.

connector_id
string
required

Unique identifier for the connector.

Example:

"c0ffee01-1234-5678-90ab-cdef01234567"

name
string
required

Human display name.

Example:

"Acme CRM"

source_name
string
required

Immutable slug used in the event source (custom:<source_name>).

Example:

"acme-crm"

created_at
string
required

ISO 8601 creation timestamp.

created_by
CreatedBy · object
required

Principal that created a resource. id is a user_id for type="user" and a key_id (UUID) for type="api_key".

is_active
boolean
required

False once the connector has been deactivated.

table_name
string
required

Table in POST /v1/knowledge/query holding one row per record pushed through /ingest, one column per top-level field. It appears after the next knowledge build.

Example:

"custom_acme_crm"

accepted_kinds
string[]

Kinds this connector may emit: first-party kinds and/or evidence types. Empty = all allowed.

Example:
metadata
Metadata · object | null

Key/value metadata applied to every event from this connector. String values only. Per-item metadata on ingest overrides on key conflict.

Example: