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

# Create or retrieve an entity

> Idempotent endpoint: inserts a new entity into the registry if one with the same name and type does not already exist.  Returns the entity_id and a ``created`` flag indicating whether a new row was inserted.  When ``source`` is provided the endpoint also creates a source node and a :MENTIONED_IN edge in FalkorDB (T11).  The FalkorDB node label is derived from ``source.source_type`` (e.g. ``'knowledge_document'`` → ``KnowledgeDocument``).



## OpenAPI

````yaml /api-reference/memory-api.json post /v1/memory/entities
openapi: 3.1.0
info:
  title: Strattum Memory API
  description: >-
    REST API that serves entity context — profile, timeline, graph, sources and
    formatted context — for agents and UIs. (PRD-003, Workstream 1.3)
  version: 1.0.0
servers: []
security: []
paths:
  /v1/memory/entities:
    post:
      tags:
        - memory
      summary: Create or retrieve an entity
      description: >-
        Idempotent endpoint: inserts a new entity into the registry if one with
        the same name and type does not already exist.  Returns the entity_id
        and a ``created`` flag indicating whether a new row was inserted.  When
        ``source`` is provided the endpoint also creates a source node and a
        :MENTIONED_IN edge in FalkorDB (T11).  The FalkorDB node label is
        derived from ``source.source_type`` (e.g. ``'knowledge_document'`` →
        ``KnowledgeDocument``).
      operationId: create_entity_v1_memory_entities_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEntityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateEntityRequest:
      properties:
        name:
          type: string
          maxLength: 512
          minLength: 1
          title: Name
          description: Entity display name.
        type:
          type: string
          maxLength: 100
          minLength: 1
          title: Type
          description: Entity type (e.g. 'company', 'person'). Stored title-cased.
        source:
          anyOf:
            - $ref: '#/components/schemas/EntitySourceInput'
            - type: 'null'
          description: >-
            Optional source reference.  When provided, a source node is
            created/merged in FalkorDB and a :MENTIONED_IN edge is added from
            the entity to the source.  The FalkorDB node label is derived from
            ``source_type`` (e.g. ``'knowledge_document'`` →
            ``KnowledgeDocument``).
      type: object
      required:
        - name
        - type
      title: CreateEntityRequest
      description: Request body for POST /entities.
    CreateEntityResponse:
      properties:
        entity_id:
          type: string
          title: Entity Id
        entity_type:
          type: string
          title: Entity Type
        name:
          type: string
          title: Name
        created:
          type: boolean
          title: Created
          description: True if a new entity was inserted; False if it already existed.
      type: object
      required:
        - entity_id
        - entity_type
        - name
        - created
      title: CreateEntityResponse
      description: Response for POST /entities.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EntitySourceInput:
      properties:
        source_type:
          type: string
          title: Source Type
          description: >-
            Source system type.  Examples: ``'knowledge_document'``,
            ``'crm_deal'``, ``'email_thread'``.
        source_id:
          type: string
          title: Source Id
          description: Identifier of the record in the source system.
        source_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Title
          description: Human-readable label stored on the source node in FalkorDB.
      type: object
      required:
        - source_type
        - source_id
      title: EntitySourceInput
      description: Generic source reference — connector-agnostic.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````