> ## Documentation Index > Fetch the complete documentation index at: https://docs.conare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch upsert by external ID > Apply up to 100 versioned source upserts in one call — the bulk path for mirroring a system of record. - Each item is the single-item `PUT /api/v1/memories/{externalId}` shape with the same semantics: identical retries replay the same receipt, and version conflicts return per-item `409`s. - `success: true` means the batch was processed — never that every item succeeded. Check the ordered per-item results. - Resume after a crash by re-sending: mark items done on per-item success or per-item `409` (both mean the version is durable). A `400` or `413` means nothing was applied. ## OpenAPI ````yaml /api/openapi.yaml post /api/v1/memories/lifecycle-batch openapi: 3.1.0 info: title: Conare API version: 1.2.0 summary: Per-end-user memory for AI applications. description: > The Conare API gives your application a persistent, personalized memory layer. Production applications authenticate as an organization-owned Integration. Every request names an `endUserId`, and that end user's memory lives in its own isolated ConareDB namespace. The physical tenant is an opaque HMAC derived from the Integration and end-user ID; clients cannot select namespaces or address another tenant. On top of storage the API provides hybrid retrieval (vector + BM25, fused and reranked, sub-second), LLM-synthesized **deep recall**, and **proactive suggestions** grounded in a user's memory. Authentication uses a scoped server-side Integration Bearer key (`cint_...`). The secret is shown once and persisted by Conare only as a SHA-256 digest. Keep it in a server-side secret manager; never ship it to the browser. Legacy personal `cmem_...` keys remain accepted during migration. Every response includes `X-Request-Id`. Send a caller-generated safe value (1–128 characters; first alphanumeric, then `A-Za-z0-9._:-`) to correlate one request through the Conare edge and memory plane; otherwise Conare generates one. Errors use a stable `{ statusCode, code, message, requestId, details? }` envelope and never include internal tenant IDs or backend error text. contact: name: Conare url: https://conare.ai email: artem@conare.ai servers: - url: https://api.conare.ai description: Production (dedicated partner-API host) - url: https://conare.ai description: Production (alias — same API, on the main host) security: - bearerAuth: [] tags: - name: Integration description: Credential, configuration, and backend readiness. - name: Memories description: Write and search a single end user's memory. - name: Recall description: LLM-synthesized personalization primitives. - name: Embeddings description: Embed text with Conare's own retrieval embedding model. - name: Connectors description: >- Let end users connect any of ~200 data sources that flow into their memory. - name: Users description: End-user lifecycle (GDPR). paths: /api/v1/memories/lifecycle-batch: post: tags: - Memories summary: Batch upsert by external ID description: | Apply up to 100 versioned source upserts in one call — the bulk path for mirroring a system of record. - Each item is the single-item `PUT /api/v1/memories/{externalId}` shape with the same semantics: identical retries replay the same receipt, and version conflicts return per-item `409`s. - `success: true` means the batch was processed — never that every item succeeded. Check the ordered per-item results. - Resume after a crash by re-sending: mark items done on per-item success or per-item `409` (both mean the version is durable). A `400` or `413` means nothing was applied. operationId: upsertSourceMemoriesBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LifecycleBatchRequest' examples: bootstrap: value: endUserId: u_123 items: - source: caeros-profile externalId: profile_123 version: 1752662400000 occurredAt: '2026-07-16T10:00:00Z' content: User prefers smaller islands and quiet anchorages. metadata: field: trip_preferences responses: '200': description: Batch processed; inspect each ordered per-item result. content: application/json: schema: $ref: '#/components/schemas/LifecycleBatchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' components: schemas: LifecycleBatchRequest: type: object required: - endUserId - items properties: endUserId: $ref: '#/components/schemas/EndUserId' items: type: array minItems: 1 maxItems: 100 description: Aggregate content is capped at 1 MiB per request. items: type: object required: - source - externalId - version - occurredAt - content properties: source: $ref: '#/components/schemas/SourceId' externalId: $ref: '#/components/schemas/ExternalId' version: type: integer minimum: 1 description: | Monotonic per (source, externalId). Without a version counter, use the row's updated_at as epoch milliseconds. occurredAt: type: string format: date-time content: type: string minLength: 1 metadata: type: object additionalProperties: true LifecycleBatchResponse: type: object required: - success - applied - failed - items properties: success: type: boolean description: | "The batch was processed" — NOT "every item succeeded". Per-item outcomes are in items[]. applied: type: integer failed: type: integer items: type: array description: One result per input item, in input order. items: type: object required: - success - status properties: success: type: boolean status: type: integer description: Per-item HTTP-equivalent status (200, 409, 429, ...). code: type: string description: >- Machine error code (stale_source_version, source_version_conflict, quota_exceeded, ...). message: type: string record: $ref: '#/components/schemas/SourceRecord' receipt: $ref: '#/components/schemas/SourceReceipt' EndUserId: type: string pattern: ^[A-Za-z0-9@._-]{1,128}$ minLength: 1 maxLength: 128 description: Your stable internal user ID. No colon allowed. example: u_123 SourceId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ description: Stable source-system name, such as `caeros-profile` or `conversation`. example: caeros-profile ExternalId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$ description: Stable record ID inside the named source. example: profile_123 SourceRecord: type: object properties: source: $ref: '#/components/schemas/SourceId' externalId: $ref: '#/components/schemas/ExternalId' documentId: type: string version: type: integer status: type: string enum: - active - deleted contentHash: type: string occurredAt: type: string format: date-time updatedAt: type: string format: date-time required: - source - externalId - version - status - occurredAt - updatedAt SourceReceipt: description: | The durable receipt of the record's LAST applied mutation — a projection of the record row (there is no per-version receipt history; persist receipts client-side if you need an audit trail). type: object properties: source: $ref: '#/components/schemas/SourceId' externalId: $ref: '#/components/schemas/ExternalId' version: type: integer operation: type: string enum: - upsert - delete requestHash: type: string outcome: type: string enum: - created - updated - deleted - already_deleted documentId: type: string contentHash: type: string occurredAt: type: string format: date-time appliedAt: type: string format: date-time required: - source - externalId - version - operation - requestHash - outcome - occurredAt - appliedAt Error: type: object properties: statusCode: type: integer code: type: string description: Stable snake_case machine error code. message: type: string requestId: type: string description: Correlates this response through Conare services and logs. details: type: object additionalProperties: true required: - statusCode - code - message - requestId responses: BadRequest: description: Missing or invalid fields (e.g. bad `endUserId`, empty `query`). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid Bearer key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The Integration credential does not include the required operation scope. content: application/json: schema: $ref: '#/components/schemas/Error' PayloadTooLarge: description: | `content` exceeds the 65536-byte (64 KB) cap. Save distilled observations, not raw documents. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: > Rate limit exceeded (reads 300/min, writes 100/min on the current plan), enforced atomically per (account, end user). Rate-window exhaustion carries a `Retry-After` header (seconds); `details` also has `retryAfterSeconds`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: description: The per-minute request cap for this operation. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer X-RateLimit-Reset: description: Unix-seconds timestamp when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' headers: RequestId: description: Caller-provided or generated request correlation identifier. schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: cint_ description: | A scoped Integration key, prefixed `cint_`. Send as `Authorization: Bearer cint_...` on every request. Server-side only. Legacy personal `cmem_...` keys remain accepted during migration; team/org-scoped `cmem_...` keys are not valid on this API. ````