Engram API

openapi: 3.1.0
info:
  title: Engram API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 8 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Engram has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 6
    pages-with-code: 1
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://getengram.app/docs/api-reference
  - https://getengram.app/docs/architecture
servers:
- url: https://mcp.getengram.app
paths:
  /api/v1/conversations:
    get:
      operationId: get_api_v1_conversations
      tags:
      - Api
      summary: List conversations.
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Max conversations to return (1–100)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Offset for pagination
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
        description: Filter by agent ID
      - name: tags
        in: query
        required: false
        schema:
          type: array
        description: Filter by tags
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: 'Sort by: created_at, updated_at, message_count'
      - name: order
        in: query
        required: false
        schema:
          type: string
        description: 'Sort order: asc or desc'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ConversationsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_conversations
      tags:
      - Api
      summary: Create a conversation.
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: title
        in: query
        required: false
        schema:
          type: string
        description: Title for the conversation
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
        description: Identifier for the agent that owns this conversation
      - name: tags
        in: query
        required: false
        schema:
          type: array
        description: Tags for filtering and organization
      - name: metadata
        in: query
        required: false
        schema:
          type: object
        description: Arbitrary key‑value metadata
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ConversationsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1ConversationsResponse'
      x-evidence:
        kind: documentation
  /api/v1/conversations/{id}:
    delete:
      operationId: delete_api_v1_conversations_id
      tags:
      - Api
      summary: Delete a conversation, its messages, and embeddings.
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiV1ConversationsIdResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_v1_conversations_id
      tags:
      - Api
      summary: Fetch a conversation with messages.
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: message_limit
        in: query
        required: false
        schema:
          type: integer
        description: Max messages to return (1–500)
      - name: message_offset
        in: query
        required: false
        schema:
          type: integer
        description: Offset for pagination
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ConversationsIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/conversations/{id}/messages/{messageid}:
    patch:
      operationId: patch_api_v1_conversations_id_messages_messageid
      tags:
      - Api
      summary: Update a message’s content in place.
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: messageid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchApiV1ConversationsIdMessagesMessageidRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchApiV1ConversationsIdMessagesMessageidResponse'
      x-evidence:
        kind: documentation
  /api/v1/messages:
    post:
      operationId: post_api_v1_messages
      tags:
      - Api
      summary: POST /api/v1/messages
      x-source: https://getengram.app/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MessagesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://mcp.getengram.app/api/v1/messages  -H "Authorization: Bearer engram_sk_live_..."  -H "Content-Type: application/json"  -d
          ''{"messages":[{"role":"user","content":"We chose Postgres over DynamoDB for the billing service."}]}'' '
  /api/v1/search:
    get:
      operationId: get_api_v1_search
      tags:
      - Api
      summary: GET /api/v1/search
      x-source: https://getengram.app/docs/api-reference
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://mcp.getengram.app/api/v1/search?q=billing+database+choice\"  -H \"Authorization: Bearer engram_sk_live_...\"\
          \ \n REST error responses use conventional status codes: 400 invalid body/query, 401 bad key, 403 missing scope, 402 storage or plan\
          \ limit, 404 not found, 429 monthly velocity limit. Last updated on November 10, 2026 Core Concepts TypeScript SDK © 2026 Engram. All\
          \ rights reserved. W"
  /mcp:
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: MCP endpoint for JSON-RPC calls
      description: 'The MCP client sends a POST request with a JSON‑RPC body (e.g., {"method": "tools/call", "params": {"name": "append_messages",
        ...}}). The server authenticates via the Bearer token, processes the request, and streams the response as Server‑Sent Events.'
      x-source: https://getengram.app/docs/architecture
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer token for API key authentication
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Accept
        in: header
        required: false
        schema:
          type: string
        description: application/json, text/event-stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMcpRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMcpResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1ConversationsResponse:
      type: object
      properties:
        conversations:
          type: array
          description: List of conversation summary objects
        total:
          type: integer
          description: Total number of matching conversations
    PostApiV1ConversationsRequest:
      type: object
      properties:
        title:
          type: string
        agent_id:
          type: string
        tags:
          type: array
        metadata:
          type: object
    PostApiV1ConversationsResponse:
      type: object
      properties:
        conversation_id:
          type: string
    DeleteApiV1ConversationsIdResponse:
      type: object
      properties:
        deleted:
          type: boolean
    GetApiV1ConversationsIdResponse:
      type: object
      properties:
        conversation:
          type: object
        messages:
          type: array
    PatchApiV1ConversationsIdMessagesMessageidRequest:
      type: object
      properties:
        content:
          type: string
      required:
      - content
    PatchApiV1ConversationsIdMessagesMessageidResponse:
      type: object
      properties:
        updated:
          type: boolean
        message:
          type: object
    PostApiV1MessagesRequest:
      type: object
      properties:
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
              content:
                type: string
    PostMcpRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON-RPC version, e.g., "2.0"
        id:
          type: integer
          description: Request identifier
        method:
          type: string
          description: JSON-RPC method, e.g., "tools/call"
        params:
          type: object
          description: Parameters for the method
      required:
      - jsonrpc
      - id
      - method
      - params
    PostMcpResponse:
      type: object
      properties:
        event:
          type: string
          description: SSE event name, e.g., "message"
        data:
          type: object
          description: JSON-RPC response payload containing result or error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Mcp