> ## Documentation Index > Fetch the complete documentation index at: https://docs.quivr.thevibecompany.co/llms.txt > Use this file to discover all available pages before exploring further. # Create connector > 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. ## OpenAPI ````yaml /openapi.yaml post /v0/connectors openapi: 3.1.0 info: title: Quivr V2 public text foundation contract version: 0.0.0-draft description: >- THE-543 and THE-547 evaluation contracts; endpoint implementations are separate work. Matching criterion is plugin-owned and deferred. One configured webhook destination, immutable Matches, independent at-least-once Delivery and reference-only notifications. OpenAPI is authoritative for transport shapes. THE-640 adds text search and asynchronous Corpus projection rebuild initiation. servers: [] security: - ApiKey: [] paths: /v0/connectors: post: tags: - Connectors summary: Create connector description: >- 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. operationId: createConnector requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectorCreate' responses: '201': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Connector' default: description: Structured error; see contract HTTP mapping. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ConnectorCreate: type: object additionalProperties: false properties: idempotency_key: type: string minLength: 1 corpus_id: type: string minLength: 1 source_namespace: type: string minLength: 1 maxLength: 200 kind: $ref: '#/components/schemas/ConnectorKind' config: type: object description: >- Kind-specific configuration validated by the kind's JSON Schema. Holds no secret. schedule: $ref: '#/components/schemas/ConnectorSchedule' health_policy: $ref: '#/components/schemas/ConnectorHealthPolicy' credential: $ref: '#/components/schemas/CredentialDeposit' required: - idempotency_key - corpus_id - source_namespace - kind - config Connector: type: object additionalProperties: false properties: connector_id: type: string minLength: 1 corpus_id: type: string minLength: 1 source_namespace: type: string minLength: 1 kind: $ref: '#/components/schemas/ConnectorKind' config: type: object schedule: type: object additionalProperties: false properties: interval_seconds: type: integer minimum: 1 required: - interval_seconds health_policy: type: object additionalProperties: false properties: silent_after_seconds: type: integer minimum: 1 credential_warning_seconds: type: integer minimum: 0 required: - silent_after_seconds - credential_warning_seconds enabled: type: boolean created_at: type: string format: date-time disabled_at: type: string format: date-time credential: $ref: '#/components/schemas/CredentialMetadata' health: $ref: '#/components/schemas/ConnectorHealth' webhook_url: type: string format: uri description: >- 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. required: - connector_id - corpus_id - source_namespace - kind - config - schedule - health_policy - enabled - created_at - health Error: type: object additionalProperties: false properties: code: type: string minLength: 1 message: type: string minLength: 1 retryable: type: boolean field: type: string minLength: 1 description: >- JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands). resync_url: type: string format: uri-reference required: - code - message - retryable ConnectorKind: type: string pattern: ^[a-z][a-z0-9_]{0,31}$ description: >- Connector kind, provided by the engine or by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. Built-in kinds are fixture (a deterministic test connector available only when the deployment enables it). 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. ConnectorSchedule: type: object additionalProperties: false properties: interval_seconds: type: integer minimum: 1 maximum: 86400 description: >- Polling interval. Defaults per kind (fixture/rss 300, m365_mail 60, x_list 120); values below the deployment floor (30 s by default) are 422 invalid_interval. ConnectorHealthPolicy: type: object additionalProperties: false properties: silent_after_seconds: type: integer minimum: 1 maximum: 2592000 description: No new item for this long makes the source silent. Default 86400. credential_warning_seconds: type: integer minimum: 0 maximum: 31536000 description: >- A credential expiring within this window is credential_expiring. Default 1209600. CredentialDeposit: type: object additionalProperties: false properties: secret: type: object writeOnly: true description: >- 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: type: string format: date-time required: - secret CredentialMetadata: type: object additionalProperties: false properties: version: type: integer minimum: 1 deposited_at: type: string format: date-time expires_at: type: string format: date-time required: - version - deposited_at description: >- Metadata of the current Deposited Credential; the secret itself is never returned. ConnectorHealth: type: object additionalProperties: false properties: state: type: string enum: - active - silent - access_error - credential_expiring - disabled evaluated_at: type: string format: date-time last_success_at: type: string format: date-time last_item_at: type: string format: date-time last_error: $ref: '#/components/schemas/ConnectorError' usage: $ref: '#/components/schemas/ConnectorUsage' diagnostics: type: object description: >- 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: $ref: '#/components/schemas/ConnectorPush' required: - state - evaluated_at description: >- 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. ConnectorError: type: object additionalProperties: false properties: code: type: string minLength: 1 at: type: string format: date-time required: - code - at ConnectorUsage: type: object additionalProperties: false properties: day: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: Current UTC calendar day (YYYY-MM-DD). items_read: type: integer minimum: 0 description: >- 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: type: integer minimum: 0 required: - day - items_read - previous_day_items_read description: >- Per-UTC-day source read counters, present only for kinds that report reads. ConnectorPush: type: object additionalProperties: false properties: state: type: string enum: - active - pending - degraded description: >- 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: $ref: '#/components/schemas/ConnectorPushError' last_delivery_at: type: string format: date-time description: Last delivery the connector plugin accepted. poll_interval_seconds: type: integer minimum: 1 description: >- While push is active, polling runs at most this often, as a safety net. required: - state description: >- Push delivery health, present once a kind that declares the push mode reports its push channel. ConnectorPushError: type: object additionalProperties: false properties: class: type: string enum: - access - transient - source code: type: string minLength: 1 description: >- 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: type: string format: date-time required: - class - code - at securitySchemes: ApiKey: type: http scheme: bearer description: >- API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized. ````