---
title: "Push data to a declared source route"
method: POST
path: "/v0/connectors/{connector_id}/api/{path}"
tags: ["Connectors"]
---

# Push data to a declared source route

`POST /v0/connectors/{connector_id}/api/{path}`

## 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/{connector_id}/api/{path}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - none

Resolve a named POST route from the instance kind's manifest (Plugin API 0.11; instance tokens and signatures since 0.12). For auth quivr_key, requires a Quivr bearer key with connector:push on the instance's Corpus and Organization, checked before any plugin call. For auth instance_token, requires this instance’s bearer token; Quivr keys and other instances’ tokens are refused with 401 invalid_instance_token. Missing or invalid key is 401; missing action 403; out-of-scope, disabled or unknown instance and undeclared path 404; undeclared method 405 with Allow. JSON body is bounded to 1 MiB and the query to 8192 bytes. Malformed JSON is 400; a request_schema mismatch is 422. Up to 64 bounded headers are relayed without Authorization, Cookie or hop-by-hop headers. The plugin and ingestion stage is bounded to 9 seconds; audit persistence adds at most 2 seconds. Accepted items use normal ingestion idempotency and return 202 with receipts in item order, including withdrawals; the accepted plugin answer is replaced. An empty delivery returns an empty receipts array. A rejected item returns 422 item_rejected; other items may already be accepted, so retrying their stable revisions replays the same receipts. Transient failures return 503 with Retry-After. Engine-generated failures return the JSON Error envelope with the engine's error code and no Quivr-Response-Origin header. A refused plugin verdict returns the plugin's 4xx status, content type and body unchanged, marked with Quivr-Response-Origin: plugin. That header selects the plugin-defined response variant (x-quivr-plugin-response), even when its status overlaps an engine response; the engine response schemas below apply to responses without that header. Per-instance token buckets use the deployment default unless push_policy overrides it. Excess requests return 429 with Retry-After (integer seconds) before plugin invocation; callers outside push_policy.allowed_cidrs return 403 ip_not_allowed. Only explicitly trusted proxy networks may supply X-Forwarded-For addresses. Every attempt for an existing instance commits connector.push.received (2xx) or connector.push.refused and per-instance admin counters before the response is sent. Audit storage failure returns 503. Legacy routes without declared signature ingress keep their existing behavior. For auth signature, the plugin verifies the provider signature; the engine checks one nonempty signature header and optional signed Unix-seconds timestamp within the declared window (401 invalid_signature). PostgreSQL reserves signature and Idempotency-Key fingerprints per instance for window_seconds before the plugin call; duplicate keys return 409 push_replayed. Signature routes bypass the response cache: once replay reservations expire, the plugin verifies every new admitted request, including one reusing an old Idempotency-Key. Signature storage failures return JSON Error 503. GET challenges bypass POST signature guards. X declares receive at api/receive with a 300-second signature cache and no timestamp. Its legacy connector-webhooks address shares the same guard, push policy, audit counters and receipts until engine 1.0.0.

## Request body

- unknown

## Response `202`

Items accepted for ingestion; poll each Receipt through the normal API.

- ConnectorPushReceipts
  - `receipts` Receipt[], required
    - `receipt_id` string, required
    - `state` 'pending' | 'resolved', required
    - `outcome` 'created' | 'duplicate' | 'withdrawal_applied' | 'conflict'
    - `record_id` string
    - `version_id` string
    - `availability` Availability
      - `state` 'materialized' | 'building_baseline' | 'retrieval_ready' | 'quarantined', required
      - `is_current` boolean, required
      - `searchable` boolean, required
    - `diagnostics` Error[], required
      - `request_id` string: Bounded caller X-Request-ID, or an engine-generated correlation ID.
      - `trace_id` string: W3C trace ID when a trace context is present.
      - `span_id` string: W3C span ID of the API handler when a trace context is present.
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
      - `field` string: 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` string, uri-reference
    - `source` SourceIdentity, required
      - `corpus_id` string, required
      - `namespace` string, required
      - `record_key` string, required
    - `processing` ProcessingSummary, required: Live read view, not a Receipt lifecycle or public workflow identifier. blocked means an outstanding contribution needs intervention; diagnostics describe why. idle means no work currently pending, not a promise of final enrichment. Phase is omitted when idle; required and optional progress do not override Version Availability.
      - `state` 'queued' | 'running' | 'retrying' | 'blocked' | 'idle', required
      - `phase` 'materialization' | 'baseline' | 'enrichment'
      - `message` string

## Other responses

- `429`: Instance token bucket exhausted; no plugin call or idempotency reservation.
- `default`: Structured engine error, or the plugin's refusal answer.

---

[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)