> ## 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. # Push data to a declared source route > 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. ## OpenAPI ````yaml /openapi.yaml post /v0/connectors/{connector_id}/api/{path} openapi: 3.1.0 info: title: Quivr HTTP API version: 0.0.0-draft description: >- Every endpoint of the Quivr v0 HTTP API. Send an API key as a bearer token; the key decides the Organization, the actions and the Corpora a request may reach. servers: [] security: - ApiKey: [] paths: /v0/connectors/{connector_id}/api/{path}: parameters: - name: Idempotency-Key in: header required: false description: >- Optional opaque key of 1–256 bytes, scoped to the instance. Authorized requests replay the first completed plugin/ingestion answer within the deployment TTL for quivr_key and instance_token routes (default 24h), without calling the plugin or charging another rate token. Authentication, route/body validation, IP and rate refusals do not reserve keys. Reusing a key on another declared route still replays its original answer. schema: type: string minLength: 1 maxLength: 256 - name: connector_id in: path required: true schema: type: string - name: path in: path required: true description: >- The declared relative route path, including any nested segments and filled template values. schema: type: string maxLength: 8192 post: tags: - Connectors summary: Push data to a declared source route description: >- 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. operationId: pushConnectorAPI requestBody: required: true content: application/json: schema: {} responses: '202': description: >- Items accepted for ingestion; poll each Receipt through the normal API. content: application/json: schema: $ref: '#/components/schemas/ConnectorPushReceipts' '429': description: >- Instance token bucket exhausted; no plugin call or idempotency reservation. headers: Retry-After: schema: type: integer minimum: 1 description: Seconds until the next rate token. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Structured engine error, or the plugin's refusal answer. content: application/json: schema: $ref: '#/components/schemas/Error' headers: Quivr-Response-Origin: description: >- Present with value plugin only for a plugin-defined reply, whose status, content type and body are forwarded unchanged. schema: type: string enum: - plugin security: - ApiKey: [] - InstanceToken: [] - {} components: schemas: ConnectorPushReceipts: type: object additionalProperties: false required: - receipts properties: receipts: type: array items: $ref: '#/components/schemas/Receipt' 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 Receipt: type: object additionalProperties: false properties: receipt_id: type: string minLength: 1 state: type: string enum: - pending - resolved outcome: type: string enum: - created - duplicate - withdrawal_applied - conflict record_id: type: string minLength: 1 version_id: type: string minLength: 1 availability: $ref: '#/components/schemas/Availability' diagnostics: type: array items: $ref: '#/components/schemas/Error' maxItems: 20 source: $ref: '#/components/schemas/SourceIdentity' processing: $ref: '#/components/schemas/ProcessingSummary' required: - receipt_id - state - diagnostics - source - processing description: >- Durable acceptance outcome, not workflow state. Availability is a separate authorized live read view; omitted before a linked version exists. Infrastructure retry never resolves a Receipt as failed. if: properties: state: const: pending then: not: required: - outcome else: required: - outcome Availability: type: object additionalProperties: false properties: state: type: string enum: - materialized - building_baseline - retrieval_ready - quarantined is_current: type: boolean searchable: type: boolean required: - state - is_current - searchable SourceIdentity: type: object additionalProperties: false properties: corpus_id: type: string minLength: 1 namespace: type: string minLength: 1 record_key: type: string minLength: 1 required: - corpus_id - namespace - record_key ProcessingSummary: type: object additionalProperties: false required: - state properties: state: type: string enum: - queued - running - retrying - blocked - idle phase: type: string enum: - materialization - baseline - enrichment message: type: string description: >- 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. 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. InstanceToken: type: http scheme: bearer description: >- Source-scoped token accepted only by its instance's declared instance_token routes. Never grants normal API or token management access. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.