---
title: "Create connector"
method: POST
path: "/v0/connectors"
tags: ["Connectors"]
---

# Create connector

`POST /v0/connectors`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/connectors`
- Auth: HTTP bearer

Create a Connector Instance bound to exactly one authorized Corpus and one Source Namespace. Kind-specific config and credential secret are validated against the kind's JSON Schema (see listConnectorKinds); a failure is 422 invalid_config or invalid_credential with field pointing at the offending member. Replaying the same idempotency key and request returns the same instance (without re-enabling a disabled one); a different request under the same key is 409 idempotency_conflict. Another enabled instance on the same Corpus and Source Namespace is 409 source_namespace_in_use. The interval defaults per kind and is refused below the deployment floor (30 s by default) with 422 invalid_interval. Deposited credentials are write-only and never returned. A deployment without a credential key refuses any request carrying a credential with 503 credentials_unavailable (retryable false) before storing or digesting it; instances without a credential are unaffected. Commits connector.created in the change feed.

## Request body

- ConnectorCreate
  - `idempotency_key` string, required
  - `corpus_id` string, required
  - `source_namespace` string, required
  - `kind` string, required: Connector kind, provided by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind.
  - `push_policy` ConnectorPushPolicy: Engine-owned protection of declared source API routes, separate from plugin config. Missing fields inherit deployment defaults; configure at instance creation.
    - `rate_per_second` number, double: Token refill rate per second (deployment default 10).
    - `burst` integer: Token bucket capacity (deployment default 100).
    - `allowed_cidrs` string[]: Allowed IPv4/IPv6 CIDRs; absent or empty permits every address.
  - `work_queue` 'live' | 'bulk': Workload class for scheduled acquisition and its documents. Push deliveries always use live.
  - `config` object, required: Kind-specific configuration validated by the kind's JSON Schema. Holds no secret.
  - `schedule` ConnectorSchedule
    - `interval_seconds` integer: Polling interval. Defaults to the kind's declared interval (rss 300, m365_mail 60, x_list 120); values below the deployment floor (30 s by default) are 422 invalid_interval.
  - `health_policy` ConnectorHealthPolicy
    - `silent_after_seconds` integer: No new item for this long makes the source silent. Default 86400.
    - `credential_warning_seconds` integer: A credential expiring within this window is credential_expiring. Default 1209600.
  - `credential` CredentialDeposit
    - `secret` object, required: Kind-specific secret, validated by the kind's credential JSON Schema, encrypted at rest with the deployment credential key and never returned or logged. Without a configured credential key the request is refused with 503 credentials_unavailable.
    - `expires_at` string, date-time

## Response `201`

Successful response

- Connector
  - `connector_id` string, required
  - `corpus_id` string, required
  - `source_namespace` string, required
  - `kind` string, required: Connector kind, provided by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind.
  - `push_policy` ConnectorPushPolicy: Engine-owned protection of declared source API routes, separate from plugin config. Missing fields inherit deployment defaults; configure at instance creation.
    - `rate_per_second` number, double: Token refill rate per second (deployment default 10).
    - `burst` integer: Token bucket capacity (deployment default 100).
    - `allowed_cidrs` string[]: Allowed IPv4/IPv6 CIDRs; absent or empty permits every address.
  - `work_queue` 'live' | 'bulk': Workload class for scheduled acquisition; push deliveries stay live.
  - `config` object, required
  - `schedule` object, required
    - `interval_seconds` integer, required
  - `health_policy` object, required
    - `silent_after_seconds` integer, required
    - `credential_warning_seconds` integer, required
  - `enabled` boolean, required
  - `created_at` string, date-time, required
  - `disabled_at` string, date-time
  - `paused_at` string, date-time: Present while scheduled acquisition is paused. Inbound push routes remain available.
  - `credential` CredentialMetadata: Metadata of the current Deposited Credential; the secret itself is never returned.
    - `version` integer, required
    - `deposited_at` string, date-time, required
    - `expires_at` string, date-time
  - `health` ConnectorHealth, required: Last committed Connector Health, evaluated at each acquisition run, credential replacement and disable; evaluated_at shows its age. Precedence disabled, access_error, credential_expiring, silent, active. access_error means the source refused access (distinct from silent, which means no new item within the threshold), including a push channel refused access while polling carries the collection. Other failures appear only as last_error.
    - `state` 'active' | 'silent' | 'access_error' | 'credential_expiring' | 'disabled', required
    - `evaluated_at` string, date-time, required
    - `last_success_at` string, date-time
    - `last_item_at` string, date-time
    - `last_error` ConnectorError
      - `code` string, required
      - `at` string, date-time, required
    - `usage` ConnectorUsage: Per-UTC-day source read counters, present only for kinds that report reads.
      - `day` string, required: Current UTC calendar day (YYYY-MM-DD).
      - `items_read` integer, required: Source resources read during the current UTC day, counted as the source bills them (for x_list, an estimate of billed post reads after X's per-UTC-day deduplication).
      - `previous_day_items_read` integer, required
    - `diagnostics` object: Kind-defined diagnostics from the latest acquisition page, documented on the kind's operator guide page (for x_list, the deletion recheck coverage). Informational; never holds a secret or source content.
    - `push` ConnectorPush: Push delivery health, present once a kind that declares the push mode reports its push channel.
      - `state` 'active' | 'pending' | 'degraded', required: active, deliveries are expected; pending, the kind has not set its push channel up yet; degraded, the setup failed or deliveries fail or miss items, and polling at the instance's interval carries the collection.
      - `error` ConnectorPushError
        - `class` 'access' | 'transient' | 'source', required
        - `code` string, required: For example webhook_invalid (the source invalidated the webhook), plugin_unavailable (a delivery found the plugin down) or missed_deliveries (polling found items no delivery brought).
        - `at` string, date-time, required
      - `last_delivery_at` string, date-time: Last delivery the connector plugin accepted.
      - `poll_interval_seconds` integer: While push is active, polling runs at most this often, as a safety net.
  - `webhook_url` string, uri: Public address of the instance's webhook route, present when its kind declares the push mode and the deployment sets public_url. The kind's plugin registers it with the source.

## Other responses

- `default`: Structured error; see contract HTTP mapping.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)