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

# Add messages [OSS + Cloud]

> Append conversation messages to a session's working memory. One call carries 1–500 messages.

The write is asynchronous by default (`async_mode` true): the gateway validates and enqueues it, answering 202 with status "queued". Pass `async_mode: false` to forward synchronously and receive the engine's 200 result instead.

Distillation into long-term memory is always asynchronous — it runs on a session boundary, or when you call /api/v2/memory/flush.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v2/memory/add
openapi: 3.1.0
info:
  title: EverOS Cloud Memory API
  version: 2.0.0
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  contact:
    name: EverMind AI
    email: service@evermind.ai
    url: https://github.com/EverMind-AI/everos-cloud-sdk-python
  description: >-
    Official Python client for the EverOS Cloud Memory API. Add, search,
    retrieve, and manage long-term memory for your AI applications over a typed
    interface (pydantic v2, with full type hints). Install and usage guides:
    https://github.com/EverMind-AI/everos-cloud-sdk-python
servers:
  - url: https://api.evermind.ai
    description: Production
security:
  - BearerAuth: []
paths:
  /api/v2/memory/add:
    post:
      tags:
        - Memory
      summary: Add messages [OSS + Cloud]
      description: >-
        Append conversation messages to a session's working memory. One call
        carries 1–500 messages.


        The write is asynchronous by default (`async_mode` true): the gateway
        validates and enqueues it, answering 202 with status "queued". Pass
        `async_mode: false` to forward synchronously and receive the engine's
        200 result instead.


        Distillation into long-term memory is always asynchronous — it runs on a
        session boundary, or when you call /api/v2/memory/flush.
      operationId: addMemory
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddInput'
        required: true
      responses:
        '200':
          description: Synchronous write result (async_mode=false).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope_AddData_'
        '202':
          description: Accepted for asynchronous processing (async_mode=true, default).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope_AddData_'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
        '403':
          description: >-
            Authenticated but not permitted — either rejected by the auth
            service, or the account's memory API version does not match the
            interface version implied by the path (a v1 account calling an
            /api/v2 route).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit or quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
        '503':
          description: >-
            The gateway could not reach the authentication service. Transient —
            retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
components:
  schemas:
    AddInput:
      properties:
        app_id:
          type: string
          title: App Id
          default: default
          description: >-
            Business-semantic scope for this write, defaulting to "default".
            Reads must use the same app_id / project_id pair to see what was
            written under it. Note this is a partition, not the security
            boundary — that is the tenant resolved from your API key.
        project_id:
          type: string
          title: Project Id
          default: default
          description: >-
            Second half of the business-semantic scope, defaulting to "default".
            See `app_id`.
        session_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Session Id
          description: >-
            The conversation these messages belong to (1–128 characters). It is
            the unit extraction works on: /api/v2/memory/flush takes this id,
            and a session boundary is what triggers extraction on its own.
        messages:
          items:
            $ref: '#/components/schemas/MessageItem'
          type: array
          maxItems: 500
          minItems: 1
          title: Messages
          description: >-
            The turns to append, in order — 1 to 500 per call. Each carries its
            own sender and timestamp, so one call can hold a whole exchange.
        async_mode:
          type: boolean
          default: true
          title: Async Mode
          description: >-
            Selects the write path. true (default): validated and enqueued
            asynchronously → HTTP 202 with status "queued". false: forwarded
            synchronously to the engine, returning its 200 result and surfacing
            write errors directly. Extraction is always asynchronous
            (flush-triggered).
      type: object
      required:
        - session_id
        - messages
      title: AddInput
      example:
        session_id: session-1
        messages:
          - sender_id: user-1
            role: user
            timestamp: 1700000000
            content: I love hiking in the mountains
    SuccessEnvelope_AddData_:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Request trace id (peer to data)
        data:
          $ref: '#/components/schemas/AddData'
          description: Endpoint-defined business result
      type: object
      required:
        - request_id
        - data
      title: SuccessEnvelope[AddData]
    GatewayError:
      type: object
      additionalProperties: true
      description: >-
        Gateway error body. NOTE: shape is not yet uniform across auth/quota/
        rate-limit paths — treat fields as best-effort. Commonly includes a
        `code`/`message` (flat) or an `error` object/string with a `message`.
      title: GatewayError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          description: One entry per field that failed validation.
      type: object
      title: HTTPValidationError
    MessageItem:
      properties:
        sender_id:
          type: string
          title: Sender Id
          description: >-
            Who produced this message — the user id for a user turn, the agent
            id for an assistant turn. This is the identifier /api/v2/memory/get
            and /api/v2/memory/search later scope by (`user_id` / `agent_id`).
        sender_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender Name
          description: Optional display name for the sender; does not affect scoping.
        role:
          type: string
          enum:
            - user
            - assistant
            - tool
          title: Role
          description: >-
            Turn type: "user", "assistant", or "tool" for a tool result. An
            agent trajectory uses the OpenAI shape — an "assistant" message
            carrying `tool_calls`, followed by a "tool" message carrying
            `tool_call_id`.
        timestamp:
          type: integer
          title: Timestamp
          description: >-
            When the message was produced, as a UNIX timestamp in MILLISECONDS.
            A seconds-scale value is rejected with 422 rather than silently
            rescaled, because a window mixing the two would mis-order and
            mis-split.
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ContentItem'
              type: array
          title: Content
          description: >-
            The message body: a plain string (shorthand for a single text item),
            or a list of content items for multimodal input.
        tool_calls:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolCall'
              type: array
            - type: 'null'
          title: Tool Calls
          description: >-
            Tool calls issued by an assistant turn, in the OpenAI tool-calling
            shape. Only meaningful when `role` is "assistant".
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
          description: >-
            The id of the assistant tool call this result answers. Required when
            `role` is "tool".
      type: object
      required:
        - sender_id
        - role
        - timestamp
        - content
      title: MessageItem
      description: >-
        One message in an /add batch (spec §2). ``content`` accepts a plain
        string

        (shorthand for a single text ContentItem) or an explicit ContentItem
        list.
    AddData:
      properties:
        message_count:
          type: integer
          title: Message Count
          description: How many messages this call accepted.
        status:
          type: string
          enum:
            - accumulated
            - extracted
            - queued
          title: Status
          description: >-
            "queued" — async enqueue accepted (HTTP 202).
            "accumulated"/"extracted" — synchronous write outcome (HTTP 200,
            async_mode=false).
      type: object
      required:
        - message_count
        - status
      title: AddData
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
          description: Path to the offending field, from the body root.
        msg:
          type: string
          title: Message
          description: What is wrong with it.
        type:
          type: string
          title: Error Type
          description: Machine-readable validation-error kind.
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ContentItem:
      properties:
        type:
          type: string
          enum:
            - text
            - audio
            - image
            - doc
            - pdf
            - html
            - email
          title: Type
          description: >-
            What this item is: "text", "image", "audio", "doc", "pdf", "html" or
            "email". It selects how the content is parsed, so it must match the
            payload.
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Inline text, used when `type` is "text".
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
          description: >-
            Where the item came from — an origin label carried through to the
            memory.
        base64:
          anyOf:
            - type: string
            - type: 'null'
          title: Base64
          description: >-
            The item's bytes inline, base64-encoded. NOTE: a non-text item that
            carries only `base64` is skipped by the parse step — the parser
            reads bytes from object storage — so use `uri` for anything that
            must actually be understood.
        uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Uri
          description: >-
            Pointer to already-uploaded bytes: the object key returned by POST
            /api/v2/object/sign. This is the only form of a non-text item that
            gets parsed.
        ext:
          anyOf:
            - type: string
            - type: 'null'
          title: Ext
          description: >-
            File extension of the referenced content, e.g. "pdf" — used when the
            uri carries none.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Original file name, kept for display and passed to the parser.
        source_info:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Source Info
          description: >-
            Free-form provenance metadata stored alongside the item; a `size`
            here is passed to the parser.
        extras:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extras
          description: Free-form extra fields, passed through untouched.
      type: object
      required:
        - type
      title: ContentItem
      description: >-
        A single content element (appendix A). Current phase: only
        ``type="text"``.
    ToolCall:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Tool-call id; the matching "tool" message echoes it as
            `tool_call_id`.
        type:
          type: string
          title: Type
          default: function
          description: Tool-call kind. Always "function" today.
        function:
          $ref: '#/components/schemas/ToolCallFunction'
          description: The function invoked, with its arguments.
      type: object
      required:
        - id
        - function
      title: ToolCall
    ToolCallFunction:
      properties:
        name:
          type: string
          title: Name
          description: Name of the function the assistant called.
        arguments:
          type: string
          title: Arguments
          description: >-
            The call's arguments as a JSON-encoded string (OpenAI shape), not an
            object.
      type: object
      required:
        - name
        - arguments
      title: ToolCallFunction
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued by EverOS, sent as `Authorization: Bearer <api_key>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.