---
title: "Get Sync Tiers"
method: POST
path: "/v1/sync/tiers"
tags: ["v1", "Sync"]
---

# Get Sync Tiers

`POST /v1/sync/tiers`

Return initial Tier 0 (goals/OKRs/use-cases --> tier 0 memories) and Tier 1 (hot memories) for the requesting user/workspace.

This is a minimal initial implementation to enable SDK integration. It uses simple heuristics and will be enhanced with analytics-driven selection.

## Request body

- SyncTiersRequest — Request model for sync tiers endpoint
  - `max_tier0` integer — Max Tier 0 items (goals/OKRs/use-cases)
  - `max_tier1` integer — Max Tier 1 items (hot memories)
  - `workspace_id` string, nullable — Optional workspace id to scope tiers
  - `user_id` string, nullable — Optional internal user ID to filter tiers by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence.
  - `external_user_id` string, nullable — Optional external user ID to filter tiers by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.
  - `organization_id` string, nullable — Optional organization ID for multi-tenant scoping. When provided, tiers are scoped to memories within this organization.
  - `namespace_id` string, nullable — Optional namespace ID for multi-tenant scoping. When provided, tiers are scoped to memories within this namespace.
  - `include_embeddings` boolean — Include embeddings in the response. Format controlled by embedding_format parameter.
  - `embedding_format` 'int8' | 'float32' — Embedding format options for sync tiers
  - `embed_model` string — Embedding model hint: 'sbert' or 'bigbird' or 'Qwen4B'
  - `embed_limit` integer — Max items to embed per tier to control latency

## Response `200`

Tier assignments returned

- SyncTiersResponse — Response model for sync tiers endpoint
  - `code` integer — HTTP status code
  - `status` string — 'success' or 'error'
  - `tier0` Memory[] — Tier 0 items (goals/OKRs/use-cases)
    - `id` string, required
    - `content` string, required
    - `title` string, nullable
    - `type` string, required
    - `metadata` union
      - string
      - object
    - `external_user_id` string, nullable
    - `customMetadata` object, nullable
    - `source_type` string
    - `context` ContextItem[], nullable
      - `role` 'user' | 'assistant', required
      - `content` string, required
    - `location` string, nullable
    - `tags` string[]
    - `hierarchical_structures` string
    - `source_url` string
    - `conversation_id` string
    - `topics` string[]
    - `steps` string[]
    - `current_step` string, nullable
    - `role` string, nullable — Role that generated this memory (user or assistant)
    - `category` string, nullable — Memory category based on role
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable
    - `acl` object, required
    - `user_id` string, required
    - `workspace_id` string, nullable
    - `organization_id` string, nullable — Organization ID that owns this memory
    - `namespace_id` string, nullable — Namespace ID this memory belongs to
    - `source_document_id` string, nullable
    - `source_message_id` string, nullable
    - `page_number` integer, nullable
    - `total_pages` integer, nullable
    - `file_url` string, nullable
    - `filename` string, nullable
    - `page` string, nullable
    - `external_user_read_access` string[], nullable
    - `external_user_write_access` string[], nullable
    - `user_read_access` string[], nullable
    - `user_write_access` string[], nullable
    - `workspace_read_access` string[], nullable
    - `workspace_write_access` string[], nullable
    - `role_read_access` string[], nullable
    - `role_write_access` string[], nullable
    - `namespace_read_access` string[], nullable
    - `namespace_write_access` string[], nullable
    - `organization_read_access` string[], nullable
    - `organization_write_access` string[], nullable
    - `embedding` number[], nullable — Full precision (float32) embedding vector from Qdrant. Typically 2560 dimensions for Qwen4B. Used for CoreML/ANE fp16 models.
    - `embedding_int8` integer[], nullable — Quantized INT8 embedding vector (values -128 to 127). 4x smaller than float32. Default format for efficiency.
    - `similarity_score` number, nullable — Cosine similarity from vector search (0-1). Measures semantic relevance to query.
    - `popularity_score` number, nullable — Popularity signal (0-1): 0.5*cacheConfidenceWeighted30d + 0.5*citationConfidenceWeighted30d. Uses stored EMA fields.
    - `recency_score` number, nullable — Recency signal (0-1): exp(-0.05 * days_since_last_access). Half-life ~14 days.
    - `reranker_score` number, nullable — Reranker relevance (0-1). From cross-encoder (Cohere/Qwen3/BGE) or LLM (GPT-5-nano).
    - `reranker_confidence` number, nullable — Reranker confidence (0-1). Meaningful for LLM reranking; equals reranker_score for cross-encoders.
    - `reranker_type` string, nullable — Reranker type: 'cross_encoder' (Cohere/Qwen3/BGE) or 'llm' (GPT-5-nano/GPT-4o-mini).
    - `relevance_score` number, nullable — Final relevance (0-1). rank_results=False: 0.6*sim + 0.25*pop + 0.15*recency. rank_results=True: RRF-based fusion.
    - `holographic_frequency_scores` object, nullable — Per-frequency-field scores from holographic scoring (e.g. {category: 0.9, topic: 0.7}). Only present when include_frequency_scores=True.
    - `metrics` object, nullable
    - `totalProcessingCost` number, nullable
  - `tier1` Memory[] — Tier 1 items (hot memories)
    - `id` string, required
    - `content` string, required
    - `title` string, nullable
    - `type` string, required
    - `metadata` union
      - string
      - object
    - `external_user_id` string, nullable
    - `customMetadata` object, nullable
    - `source_type` string
    - `context` ContextItem[], nullable
      - `role` 'user' | 'assistant', required
      - `content` string, required
    - `location` string, nullable
    - `tags` string[]
    - `hierarchical_structures` string
    - `source_url` string
    - `conversation_id` string
    - `topics` string[]
    - `steps` string[]
    - `current_step` string, nullable
    - `role` string, nullable — Role that generated this memory (user or assistant)
    - `category` string, nullable — Memory category based on role
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable
    - `acl` object, required
    - `user_id` string, required
    - `workspace_id` string, nullable
    - `organization_id` string, nullable — Organization ID that owns this memory
    - `namespace_id` string, nullable — Namespace ID this memory belongs to
    - `source_document_id` string, nullable
    - `source_message_id` string, nullable
    - `page_number` integer, nullable
    - `total_pages` integer, nullable
    - `file_url` string, nullable
    - `filename` string, nullable
    - `page` string, nullable
    - `external_user_read_access` string[], nullable
    - `external_user_write_access` string[], nullable
    - `user_read_access` string[], nullable
    - `user_write_access` string[], nullable
    - `workspace_read_access` string[], nullable
    - `workspace_write_access` string[], nullable
    - `role_read_access` string[], nullable
    - `role_write_access` string[], nullable
    - `namespace_read_access` string[], nullable
    - `namespace_write_access` string[], nullable
    - `organization_read_access` string[], nullable
    - `organization_write_access` string[], nullable
    - `embedding` number[], nullable — Full precision (float32) embedding vector from Qdrant. Typically 2560 dimensions for Qwen4B. Used for CoreML/ANE fp16 models.
    - `embedding_int8` integer[], nullable — Quantized INT8 embedding vector (values -128 to 127). 4x smaller than float32. Default format for efficiency.
    - `similarity_score` number, nullable — Cosine similarity from vector search (0-1). Measures semantic relevance to query.
    - `popularity_score` number, nullable — Popularity signal (0-1): 0.5*cacheConfidenceWeighted30d + 0.5*citationConfidenceWeighted30d. Uses stored EMA fields.
    - `recency_score` number, nullable — Recency signal (0-1): exp(-0.05 * days_since_last_access). Half-life ~14 days.
    - `reranker_score` number, nullable — Reranker relevance (0-1). From cross-encoder (Cohere/Qwen3/BGE) or LLM (GPT-5-nano).
    - `reranker_confidence` number, nullable — Reranker confidence (0-1). Meaningful for LLM reranking; equals reranker_score for cross-encoders.
    - `reranker_type` string, nullable — Reranker type: 'cross_encoder' (Cohere/Qwen3/BGE) or 'llm' (GPT-5-nano/GPT-4o-mini).
    - `relevance_score` number, nullable — Final relevance (0-1). rank_results=False: 0.6*sim + 0.25*pop + 0.15*recency. rank_results=True: RRF-based fusion.
    - `holographic_frequency_scores` object, nullable — Per-frequency-field scores from holographic scoring (e.g. {category: 0.9, topic: 0.7}). Only present when include_frequency_scores=True.
    - `metrics` object, nullable
    - `totalProcessingCost` number, nullable
  - `transitions` object[] — Transition items between tiers
  - `next_cursor` string, nullable — Cursor for pagination
  - `has_more` boolean — Whether there are more items available
  - `error` string, nullable — Error message if failed
  - `details` unknown

## Other responses

- `401` — Unauthorized
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.net/papr-ai/apis/papr-memory-api.md) · [All operations](https://skmtc.net/papr-ai/apis/papr-memory-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/papr-ai/papr-memory-api/revisions/b553be9aad37/schema)