> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jeanmemory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Append context

> Stream new context into an existing user without resending the full payload.

Use this when a user **already exists** and you want to enrich them incrementally. The platform extracts against your domain schema, merges into the existing representation, and refreshes embeddings if any soft fields changed.

Typical sources:

* Chat messages between users
* Voice or video call transcripts
* Behavior events (likes, skips, time-on-profile)
* New uploads (additional photos, updated resume)

<CodeGroup>
  ```bash curl theme={"dark"}
  curl https://api.jeantechnologies.com/v1/context \
    -H "Authorization: Bearer $JEAN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": "u_alice",
      "domain": "dating",
      "source": "chat",
      "content": "Just got back from a week of hiking in the Catskills. Loved it. Already planning the next trip."
    }'
  ```

  ```python Python theme={"dark"}
  requests.post(
      "https://api.jeantechnologies.com/v1/context",
      headers={"Authorization": f"Bearer {os.environ['JEAN_API_KEY']}"},
      json={
          "user_id": "u_alice",
          "domain": "dating",
          "source": "chat",
          "content": "Just got back from a week of hiking in the Catskills. Loved it. Already planning the next trip.",
      },
  )
  ```

  ```ts TypeScript theme={"dark"}
  await fetch("https://api.jeantechnologies.com/v1/context", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JEAN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      user_id: "u_alice",
      domain: "dating",
      source: "chat",
      content:
        "Just got back from a week of hiking in the Catskills. Loved it. Already planning the next trip.",
    }),
  });
  ```
</CodeGroup>

## Example response

```json theme={"dark"}
{
  "user_id": "u_alice",
  "domain": "dating",
  "context_id": "ctx_a8c2",
  "fields_updated": ["interests", "values_text"],
  "embeddings_refreshed": true
}
```

`fields_updated` tells you which columns actually changed (so you can avoid downstream cache invalidation when nothing moved). `embeddings_refreshed` is `true` when at least one soft field changed and the dense vector was re-computed.

<Tip>
  Send context as it arrives. The platform deduplicates near-identical content and rate-limits embedding refreshes per user, so high-throughput sources (a chat feed) won't burn your quota.
</Tip>

## When to use which endpoint

| Situation                                    | Use                              |
| -------------------------------------------- | -------------------------------- |
| First time you've ever seen this user        | `POST /users`                    |
| Full re-import or bulk backfill              | `POST /users`                    |
| New chat message / event / transcript chunk  | `POST /context`                  |
| User updated a profile field through your UI | `POST /users` (replaces the row) |
| Periodic behavior batch (e.g. nightly job)   | `POST /context` per row          |


## OpenAPI

````yaml POST /context
openapi: 3.1.0
info:
  title: Jean Technologies API
  version: 1.0.0
  description: >-
    Matching infrastructure for AI-era platforms. Ingest user context, retrieve
    compatible candidates, send outcomes back.
servers:
  - url: https://api.jeantechnologies.com/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /context:
    post:
      tags:
        - Users
      summary: Append context
      description: >-
        Incrementally add new context to a user's representation without
        resending the full payload. Use this for streaming sources: chat
        messages, behavior events, follow-up call transcripts, new uploads. The
        platform runs schema-driven extraction on the new content and merges any
        changes into the existing representation.
      operationId: appendContext
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppendContextRequest'
      responses:
        '200':
          description: Context merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppendContextResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AppendContextRequest:
      type: object
      required:
        - user_id
        - domain
        - content
      properties:
        user_id:
          type: string
          example: u_alice
        domain:
          type: string
          example: dating
        source:
          type: string
          description: >-
            Where this context came from. Free-form tag stored alongside the
            extracted fields for provenance.
          example: chat
          enum:
            - chat
            - voice_transcript
            - behavior
            - upload
            - connector
            - manual
        content:
          type: string
          description: The new piece of context to merge into the user's representation.
          example: >-
            Just got back from a week of hiking in the Catskills. Loved it.
            Already planning the next trip.
        occurred_at:
          type: string
          format: date-time
          description: >-
            Optional timestamp the event actually occurred (defaults to server
            receive time).
    AppendContextResponse:
      type: object
      properties:
        user_id:
          type: string
          example: u_alice
        domain:
          type: string
          example: dating
        context_id:
          type: string
          example: ctx_a8c2
        fields_updated:
          type: array
          items:
            type: string
          example:
            - interests
            - values_text
        embeddings_refreshed:
          type: boolean
          example: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: Field 'domain' is required.
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key issued by Jean Technologies. Contact the team for access.

````