> ## 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. # Get suggestions > Given a moment of context ("user just opened their dashboard"), returns up to 5 concrete next actions, each grounded in a specific memory — never generic advice (~3–6 s: fetch async, don't block render). - New users with insufficient memory get `[]` — render conditionally. - If the model breaks the JSON contract, the response is `{ suggestions: [], raw: "" }` — treat `raw` as displayable fallback text. - There is no shallow fallback, so an exhausted usage-ledger plan is a hard `402` (legacy quota plans: `429`). ## OpenAPI ````yaml /api/openapi.yaml post /api/v1/suggestions 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/suggestions: post: tags: - Recall summary: Get suggestions description: | Given a moment of context ("user just opened their dashboard"), returns up to 5 concrete next actions, each grounded in a specific memory — never generic advice (~3–6 s: fetch async, don't block render). - New users with insufficient memory get `[]` — render conditionally. - If the model breaks the JSON contract, the response is `{ suggestions: [], raw: "" }` — treat `raw` as displayable fallback text. - There is no shallow fallback, so an exhausted usage-ledger plan is a hard `402` (legacy quota plans: `429`). operationId: suggestions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SuggestionsRequest' examples: default: value: endUserId: u_123 context: user just opened the trip-planning dashboard responses: '200': description: Up to 5 grounded suggestions (possibly empty), or a raw fallback. content: application/json: schema: $ref: '#/components/schemas/SuggestionsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/UsageExhausted' '403': $ref: '#/components/responses/Forbidden' '429': description: Rate limit exceeded, or a legacy deep-synthesis quota exhausted. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SuggestionsRequest: type: object required: - endUserId properties: endUserId: $ref: '#/components/schemas/EndUserId' context: type: string description: | The moment the user is in ("user just opened their portfolio page"). Steers retrieval. Defaults to the user's recent activity/goals. containerTag: allOf: - $ref: '#/components/schemas/ContainerTag' description: | Restrict retrieval to one container before synthesis: suggestions can only be grounded in memories carrying this tag. Use it to fence multi-workspace data. A malformed tag is a `400`, never a silently unscoped read. SuggestionsResponse: type: object properties: suggestions: type: array items: $ref: '#/components/schemas/Suggestion' description: Up to 5 grounded actions; `[]` when memory is insufficient. sources: type: array items: $ref: '#/components/schemas/CitationSource' raw: type: string description: | Present only when the model broke the JSON contract — a displayable text fallback. When present, `suggestions` is `[]`. required: - suggestions 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 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 ContainerTag: type: string minLength: 1 maxLength: 128 description: | Free-form grouping label attached at save time (e.g. `"profile"`, `"workspace:acme"`). 1-128 characters; must not contain `/` or control characters. example: workspace:acme Suggestion: type: object properties: title: type: string description: Short imperative label. reason: type: string description: One sentence citing what in memory motivates this. action: type: string description: What the app or user should do, specific enough to execute. required: - title - action CitationSource: type: object description: A memory cited by the synthesized answer. properties: ref: type: string description: Citation marker as it appears in `answer` (e.g. "M1"). example: M1 id: type: string updatedAt: type: string description: ISO 8601 timestamp, or "unknown". source: type: string description: The memory's container tag. project: type: string description: Optional project label from metadata. required: - ref - updatedAt - source 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' UsageExhausted: description: Included usage allowance and configured overage budget are exhausted. 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' 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. ````