---
title: "Ingest Preference"
method: POST
path: "/ingestion/preference"
tags: ["Ingestion Pipeline"]
---

# Ingest Preference

`POST /ingestion/preference`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/ingestion/preference`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/ingestion/preference/post.ts> (a function with typed inputs; its response is checked against the schema)

Ingest explicit user preferences via the ingestion pipeline.

Optional `scope` ("<kind>:<value>") is pre-checked against the caller's
visible scopes (403 with explanatory body otherwise) and forwarded to the
pipeline as ``write_scope``. The ingestion service stamps it on the
engine write end to end: PreferenceIngestRequest.write_scope ->
_process_preference_pipeline -> ingest_knowledge_graph(write_scope=...)
-> the ``X-Scope-Id`` header of /etl/ingest-kg. Omitted: the default
personal stamp (``user:<user_id>``).

## Request body

- PreferenceIngestRequest: Preference ingestion request.
  - `org_id` string, required: Organization identifier
  - `user_id` string, required: User identifier
  - `preferences` PreferenceItem[], required: Preferences
    - `category` string, required: Preference category
    - `entity` string, required: Entity name
    - `entity_type` string, required: Entity type
    - `preference_type` string, required: PREFERS or DISLIKES
    - `context` string, nullable: Preference context
    - `confidence` string: Confidence level
    - `source` string, nullable: Preference source
    - `timestamp` string, date-time, nullable: Preference timestamp
  - `session_id` string, nullable: Session identifier
  - `scope` string, nullable: Optional explicit write scope "<kind>:<value>" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:<user_id>.

## Response `200`

Successful Response

- PreferenceIngestResponse: Preference ingestion response.
  - `job_id` string, required: Job identifier
  - `status` string, required: Job status
  - `preferences_count` integer, required: Number of preferences
  - `estimated_time` integer, nullable: Estimated time in seconds
  - `message` string, nullable: Status message

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)