openapi: 3.1.0
info:
  title: Papr Memory API
  description: >-
    API for managing personal memory items with authentication and user-specific
    data.
        
        ## Authentication
        This API supports three authentication methods:
        
        - **API Key**: Include your API key in the `X-API-Key` header
          ```
          X-API-Key: <your-api-key>
          ```
        
        - **Session Token**: Include your session token in the `X-Session-Token` header
          ```
          X-Session-Token: <your-session-token>
          ```
        
        - **Bearer Token**: Include your OAuth2 token from Auth0 in the `Authorization` header
          ```
          Authorization: Bearer <token>
          ```
        
        All endpoints require one of these authentication methods.
  version: 1.0.0
paths:
  /v1/user:
    post:
      tags:
        - v1
        - User
      summary: Create User
      description: Create a new user or link existing user to developer
      operationId: create_user_v1_user_post
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
              bearerToken: process.env['PAPR_MEMORY_BEARER_TOKEN'], // This is the default and can be omitted
            });

            async function main() {
              const userResponse = await client.user.create({ external_id: 'user123' });

              console.log(userResponse.external_id);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
                bearer_token=os.environ.get("PAPR_MEMORY_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            user_response = client.user.create(
                external_id="user123",
            )
            print(user_response.external_id)
    get:
      tags:
        - v1
        - User
      summary: List Users
      description: List users for a developer
      operationId: list_users_v1_user_get
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            title: Page
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 10
            title: Page Size
        - name: external_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: External Id
        - name: email
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Email
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
              bearerToken: process.env['PAPR_MEMORY_BEARER_TOKEN'], // This is the default and can be omitted
            });

            async function main() {
              const users = await client.user.list();

              console.log(users.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
                bearer_token=os.environ.get("PAPR_MEMORY_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            users = client.user.list()
            print(users.code)
  /v1/user/{user_id}:
    get:
      tags:
        - v1
        - User
      summary: Get User
      description: Get user details by user_id (_User.objectId) and developer association
      operationId: get_user_v1_user__user_id__get
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            title: User Id
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
              bearerToken: process.env['PAPR_MEMORY_BEARER_TOKEN'], // This is the default and can be omitted
            });

            async function main() {
              const userResponse = await client.user.get('user_id');

              console.log(userResponse.external_id);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
                bearer_token=os.environ.get("PAPR_MEMORY_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            user_response = client.user.get(
                "user_id",
            )
            print(user_response.external_id)
    put:
      tags:
        - v1
        - User
      summary: Update User
      description: >-
        Update user details by user_id (_User.objectId) and developer
        association
      operationId: update_user_v1_user__user_id__put
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            title: User Id
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
              bearerToken: process.env['PAPR_MEMORY_BEARER_TOKEN'], // This is the default and can be omitted
            });

            async function main() {
              const userResponse = await client.user.update('user_id');

              console.log(userResponse.external_id);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
                bearer_token=os.environ.get("PAPR_MEMORY_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            user_response = client.user.update(
                user_id="user_id",
            )
            print(user_response.external_id)
    delete:
      tags:
        - v1
        - User
      summary: Delete User
      description: >-
        Delete user association with developer and the user itself by user_id
        (_User.objectId)
      operationId: delete_user_v1_user__user_id__delete
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            title: User Id
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
              bearerToken: process.env['PAPR_MEMORY_BEARER_TOKEN'], // This is the default and can be omitted
            });

            async function main() {
              const user = await client.user.delete('user_id');

              console.log(user.user_id);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
                bearer_token=os.environ.get("PAPR_MEMORY_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            user = client.user.delete(
                "user_id",
            )
            print(user.user_id)
  /v1/memory:
    post:
      tags:
        - v1
      summary: Add Memory V1
      description: >-
        Add a new memory item to the system with size validation and background
        processing.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - Content-Type: application/json
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
            
            The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).
      operationId: add_memory
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: skip_background_processing
          in: query
          required: false
          schema:
            type: boolean
            description: If True, skips adding background tasks for processing
            default: false
            title: Skip Background Processing
          description: If True, skips adding background tasks for processing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMemoryRequest'
      responses:
        '200':
          description: Memory successfully added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
              example:
                code: 200
                status: success
                data:
                  - id: mem_123
                    content: Sample memory content.
                    type: text
                    metadata:
                      topics: example, memory
                    createdAt: '2024-06-01T12:00:00Z'
        '207':
          description: Memory added with degraded functionality
          content:
            application/json:
              example:
                code: 207
                status: success
                data:
                  - id: mem_124
                    content: Sample memory content.
                    type: text
                    metadata:
                      topics: example, memory
                    createdAt: '2024-06-01T12:01:00Z'
                details:
                  warning: Neo4j unavailable, stored in Pinecone only.
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              example:
                code: 400
                status: error
                error: Invalid request payload.
                details:
                  field: content
                  reason: Missing required field.
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                code: 401
                status: error
                error: Missing or invalid authentication.
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '403':
          description: Subscription limit reached
          content:
            application/json:
              example:
                code: 403
                status: error
                error: Subscription limit reached. Upgrade required.
                details:
                  limit: memory quota
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '413':
          description: Content too large
          content:
            application/json:
              example:
                code: 413
                status: error
                error: >-
                  Content size (16000 bytes) exceeds maximum limit of 15000
                  bytes.
                details:
                  max_content_length: 15000
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              example:
                code: 415
                status: error
                error: Unsupported media type. Use application/json.
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                code: 500
                status: error
                error: Internal server error.
                details:
                  trace_id: abc123
              schema:
                $ref: '#/components/schemas/AddMemoryResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const addMemoryResponse = await client.memory.add({
                content: 'Meeting notes from the product planning session',
              });

              console.log(addMemoryResponse.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            add_memory_response = client.memory.add(
                content="Meeting notes from the product planning session",
            )
            print(add_memory_response.code)
  /v1/memory/{memory_id}:
    put:
      tags:
        - v1
      summary: Update Memory V1
      description: |-
        Update an existing memory item by ID.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - Content-Type: application/json
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
            
            The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).
      operationId: update_memory
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: memory_id
          in: path
          required: true
          schema:
            type: string
            title: Memory Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemoryRequest'
      responses:
        '200':
          description: Memory successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
        '404':
          description: Memory not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
        '413':
          description: Content too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMemoryResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const memory = await client.memory.update('memory_id');

              console.log(memory.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            memory = client.memory.update(
                memory_id="memory_id",
            )
            print(memory.code)
    delete:
      tags:
        - v1
      summary: Delete Memory V1
      description: |-
        Delete a memory item by ID.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
      operationId: delete_memory
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: memory_id
          in: path
          required: true
          schema:
            type: string
            title: Memory Id
        - name: skip_parse
          in: query
          required: false
          schema:
            type: boolean
            description: Skip Parse Server deletion
            default: false
            title: Skip Parse
          description: Skip Parse Server deletion
      responses:
        '200':
          description: Memory successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
        '207':
          description: Partially successful deletion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
        '404':
          description: Memory not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMemoryResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const memory = await client.memory.delete('memory_id');

              console.log(memory.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            memory = client.memory.delete(
                memory_id="memory_id",
            )
            print(memory.code)
    get:
      tags:
        - v1
      summary: Get Memory V1
      description: |-
        Retrieve a memory item by ID.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
      operationId: get_memory
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: memory_id
          in: path
          required: true
          schema:
            type: string
            title: Memory Id
      responses:
        '200':
          description: Memory successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Memory not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const searchResponse = await client.memory.get('memory_id');

              console.log(searchResponse.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            search_response = client.memory.get(
                "memory_id",
            )
            print(search_response.code)
  /v1/memory/batch:
    post:
      tags:
        - v1
      summary: Add Memory Batch V1
      description: >-
        Add multiple memory items in a batch with size validation and background
        processing.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - Content-Type: application/json
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
            
            The API validates individual memory content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).
      operationId: add_memory_batch
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: skip_background_processing
          in: query
          required: false
          schema:
            type: boolean
            description: If True, skips adding background tasks for processing
            default: false
            title: Skip Background Processing
          description: If True, skips adding background tasks for processing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchMemoryRequest'
      responses:
        '200':
          description: Memories successfully added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '207':
          description: Partial success - some memories failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '403':
          description: Subscription limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '413':
          description: Content too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchMemoryResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const response = await client.memory.addBatch({
                memories: [
                  { content: 'Meeting notes from the product planning session' },
                  { content: 'Follow-up tasks from the planning meeting' },
                ],
              });

              console.log(response.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            response = client.memory.add_batch(
                memories=[{
                    "content": "Meeting notes from the product planning session"
                }, {
                    "content": "Follow-up tasks from the planning meeting"
                }],
            )
            print(response.code)
  /v1/document:
    post:
      tags:
        - v1
      summary: Upload Document V1
      description: |-
        Upload a document (PDF/HTML/TXT) to be processed and added to memory.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Required Headers**:
            - Content-Type: multipart/form-data
            - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
            
            **Form Data**:
            - file: The document file to upload (PDF/HTML/TXT)
            - metadata: (optional) JSON string containing additional metadata
      operationId: upload_document
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: skip_background_processing
          in: query
          required: false
          schema:
            type: boolean
            description: If True, skips adding background tasks for processing
            default: false
            title: Skip Background Processing
          description: If True, skips adding background tasks for processing
        - name: post_objectId
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional Post objectId for updating status
            title: Post Objectid
          description: Optional Post objectId for updating status
      responses:
        '200':
          description: Document upload started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '207':
          description: Document upload started with degraded functionality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '403':
          description: Subscription limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const response = await client.document.upload();

              console.log(response.document_status);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            response = client.document.upload()
            print(response.document_status)
  /v1/memory/search:
    post:
      tags:
        - v1
      summary: Search V1
      description: |-
        Search through memories with authentication required.
            
            **Authentication Required**:
            One of the following authentication methods must be used:
            - Bearer token in `Authorization` header
            - API Key in `X-API-Key` header
            - Session token in `X-Session-Token` header
            
            **Recommended Headers**:
            ```
            Accept-Encoding: gzip
            ```
            
            The API supports response compression for improved performance. Responses larger than 1KB will be automatically compressed when this header is present.
      operationId: search_memory
      security:
        - APIKeyHeader: []
        - Bearer: []
      parameters:
        - name: max_memories
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Maximum number of memories to return
            default: 20
            title: Max Memories
          description: Maximum number of memories to return
        - name: max_nodes
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Maximum number of neo nodes to return
            default: 15
            title: Max Nodes
          description: Maximum number of neo nodes to return
        - name: Accept-Encoding
          in: header
          description: Recommended to use 'gzip' for response compression
          schema:
            type: string
            default: gzip
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successfully retrieved memories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '403':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: No relevant items found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Papr from '@papr/memory';

            const client = new Papr({
              apiKey: process.env['PAPR_MEMORY_API_KEY'], // This is the default and can be omitted
            });

            async function main() {
              const searchResponse = await client.memory.search({
                query:
                  'Find recurring customer complaints about API performance from the last month. Focus on issues where customers specifically mentioned timeout errors or slow response times in their conversations.',
              });

              console.log(searchResponse.code);
            }

            main();
        - lang: Python
          source: |-
            import os
            from papr_memory import Papr

            client = Papr(
                api_key=os.environ.get("PAPR_MEMORY_API_KEY"),  # This is the default and can be omitted
            )
            search_response = client.memory.search(
                query="Find recurring customer complaints about API performance from the last month. Focus on issues where customers specifically mentioned timeout errors or slow response times in their conversations.",
            )
            print(search_response.code)
components:
  schemas:
    AddMemoryItem:
      properties:
        memoryId:
          type: string
          title: Memoryid
        createdAt:
          type: string
          format: date-time
          title: Createdat
        objectId:
          type: string
          title: Objectid
        memoryChunkIds:
          items:
            type: string
          type: array
          title: Memorychunkids
      additionalProperties: false
      type: object
      required:
        - memoryId
        - createdAt
        - objectId
      title: AddMemoryItem
      description: Response model for a single memory item in add_memory response
    AddMemoryRequest:
      properties:
        content:
          type: string
          title: Content
          description: The content of the memory item you want to add to memory
        type:
          $ref: '#/components/schemas/MemoryType'
          description: Content type of the memory item
          default: text
        metadata:
          anyOf:
            - $ref: '#/components/schemas/MemoryMetadata'
            - type: 'null'
          description: Metadata used in Neo4J and Pinecone for a memory item
        context:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextItem'
              type: array
            - type: 'null'
          title: Context
          description: >-
            Context can be conversation history or any relevant context for a
            memory item
        relationships_json:
          anyOf:
            - items:
                $ref: '#/components/schemas/RelationshipItem'
              type: array
            - type: 'null'
          title: Relationships Json
          description: Array of relationships that we can use in Graph DB (neo4J)
      additionalProperties: false
      type: object
      required:
        - content
      title: AddMemoryRequest
      description: Request model for adding a new memory
      example:
        content: Meeting notes from the product planning session
        context:
          - content: Let's discuss the Q2 product roadmap
            role: user
          - content: I'll help you plan the roadmap. What are your key objectives?
            role: assistant
        imageGenerationCategory: business_management
        metadata:
          conversationId: conv-123
          createdAt: '2024-03-21T10:00:00Z'
          emoji tags: 📊,💡,📝
          emotion tags: focused, productive
          hierarchical structures: Business/Planning/Product
          location: Conference Room A
          sourceUrl: https://meeting-notes.example.com/123
          topics: product, planning
        relationships_json:
          - metadata:
              relevance: high
            related_item_id: previous_memory_item_id
            related_item_type: TextMemoryItem
            relation_type: follows
        type: text
    AddMemoryResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
          default: 200
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
          default: success
        data:
          anyOf:
            - items:
                $ref: '#/components/schemas/AddMemoryItem'
              type: array
            - type: 'null'
          title: Data
          description: List of memory items if successful
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
      additionalProperties: false
      type: object
      title: AddMemoryResponse
      description: Unified response model for add_memory API endpoint (success or error).
    BatchMemoryError:
      properties:
        index:
          type: integer
          title: Index
        error:
          type: string
          title: Error
        code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Code
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
      additionalProperties: false
      type: object
      required:
        - index
        - error
      title: BatchMemoryError
    BatchMemoryRequest:
      properties:
        memories:
          items:
            $ref: '#/components/schemas/AddMemoryRequest'
          type: array
          maxItems: 50
          minItems: 1
          title: Memories
          description: List of memory items to add in batch
        batch_size:
          anyOf:
            - type: integer
              maximum: 50
              minimum: 1
            - type: 'null'
          title: Batch Size
          description: Number of items to process in parallel
          default: 10
      type: object
      required:
        - memories
      title: BatchMemoryRequest
      description: Request model for batch adding memories
      example:
        batch_size: 10
        memories:
          - content: Meeting notes from the product planning session
            metadata:
              createdAt: '2024-03-21T10:00:00Z'
              emoji tags: 📊,💡,📝
              emotion tags: focused, productive
              hierarchical structures: Business/Planning/Product
              topics: product, planning
            type: text
          - content: Follow-up tasks from the planning meeting
            metadata:
              createdAt: '2024-03-21T11:00:00Z'
              emoji tags: ✅,📋
              emotion tags: organized
              hierarchical structures: Business/Tasks/Planning
              topics: tasks, planning
            type: text
    BatchMemoryResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code for the batch operation
          default: 200
        status:
          type: string
          title: Status
          description: '''success'', ''partial'', or ''error'''
          default: success
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Human-readable status message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Batch-level error message, if any
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
        successful:
          items:
            $ref: '#/components/schemas/AddMemoryResponse'
          type: array
          title: Successful
          description: List of successful add responses
        errors:
          items:
            $ref: '#/components/schemas/BatchMemoryError'
          type: array
          title: Errors
          description: List of errors for failed items
        total_processed:
          type: integer
          title: Total Processed
          default: 0
        total_successful:
          type: integer
          title: Total Successful
          default: 0
        total_failed:
          type: integer
          title: Total Failed
          default: 0
        total_content_size:
          type: integer
          title: Total Content Size
          default: 0
        total_storage_size:
          type: integer
          title: Total Storage Size
          default: 0
      additionalProperties: false
      type: object
      title: BatchMemoryResponse
    Body_update_memory_update_memory_put:
      properties:
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
      type: object
      title: Body_update_memory_update_memory_put
    CodeNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        language:
          type: string
          title: Language
        author:
          type: string
          title: Author
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - language
        - author
      title: CodeNodeProperties
      description: Code node properties
    CompanyNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - description
      title: CompanyNodeProperties
      description: Company node properties
    ContextItem:
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          title: Role
        content:
          type: string
          title: Content
      additionalProperties: false
      type: object
      required:
        - role
        - content
      title: ContextItem
      description: Context item for memory request
    CreateUserRequest:
      properties:
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
        external_id:
          type: string
          title: External Id
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
        type:
          $ref: '#/components/schemas/UserType'
          default: developerUser
      type: object
      required:
        - external_id
      title: CreateUserRequest
      description: Request model for creating a user
      example:
        email: user@example.com
        external_id: user123
        metadata:
          name: John Doe
          preferences:
            theme: dark
        type: developerUser
    DeleteMemoryResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
          default: 200
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
          default: success
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        memoryId:
          type: string
          title: Memoryid
          default: ''
        objectId:
          type: string
          title: Objectid
          default: ''
        deletion_status:
          anyOf:
            - $ref: '#/components/schemas/DeletionStatus'
            - type: 'null'
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
      additionalProperties: false
      type: object
      title: DeleteMemoryResponse
    DeleteUserResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: ID of the user attempted to delete
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Success or error message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
      type: object
      required:
        - code
        - status
      title: DeleteUserResponse
      example:
        code: 200
        message: User and association deleted successfully
        status: success
        user_id: abc123
    DeletionStatus:
      properties:
        pinecone:
          type: boolean
          title: Pinecone
          default: false
        neo4j:
          type: boolean
          title: Neo4J
          default: false
        parse:
          type: boolean
          title: Parse
          default: false
      type: object
      title: DeletionStatus
    DocumentUploadResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
          default: 200
        status:
          type: string
          title: Status
          description: '''success'', ''processing'', ''error'', etc.'
          default: success
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Human-readable status message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
        document_status:
          $ref: '#/components/schemas/DocumentUploadStatus'
          description: Status and progress of the document upload
        memory_items:
          items:
            $ref: '#/components/schemas/AddMemoryItem'
          type: array
          title: Memory Items
          description: List of memory items created from the document
        memories:
          anyOf:
            - items:
                $ref: '#/components/schemas/AddMemoryItem'
              type: array
            - type: 'null'
          title: Memories
          description: For backward compatibility
      additionalProperties: false
      type: object
      required:
        - document_status
      title: DocumentUploadResponse
    DocumentUploadStatus:
      properties:
        progress:
          type: number
          title: Progress
          description: 0.0 to 1.0 for percentage
        current_page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Current Page
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
        current_filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Filename
        upload_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Upload Id
        status_type:
          anyOf:
            - $ref: '#/components/schemas/DocumentUploadStatusType'
            - type: 'null'
          description: Processing status type
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
      additionalProperties: false
      type: object
      required:
        - progress
      title: DocumentUploadStatus
    DocumentUploadStatusType:
      type: string
      enum:
        - processing
        - completed
        - failed
        - not_found
        - queued
        - cancelled
      title: DocumentUploadStatusType
    ErrorDetail:
      properties:
        code:
          type: integer
          title: Code
        detail:
          type: string
          title: Detail
      additionalProperties: false
      type: object
      required:
        - code
        - detail
      title: ErrorDetail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InsightNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        source:
          type: string
          title: Source
        type:
          type: string
          enum:
            - customer_insight
            - product_insight
            - market_insight
            - competitive_insight
            - technical_insight
            - other
          title: Type
      additionalProperties: false
      type: object
      required:
        - id
        - title
        - description
        - source
        - type
      title: InsightNodeProperties
      description: Insight node properties
    MeetingNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        agenda:
          type: string
          title: Agenda
        type:
          type: string
          title: Type
        participants:
          items:
            type: string
          type: array
          title: Participants
        date:
          type: string
          title: Date
        time:
          type: string
          title: Time
        summary:
          type: string
          title: Summary
        outcome:
          type: string
          title: Outcome
        action_items:
          items:
            type: string
          type: array
          title: Action Items
      additionalProperties: false
      type: object
      required:
        - id
        - title
        - agenda
        - type
        - participants
        - date
        - time
        - summary
        - outcome
        - action_items
      title: MeetingNodeProperties
      description: Meeting node properties
    Memory:
      properties:
        id:
          type: string
          title: Id
        content:
          type: string
          title: Content
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        type:
          type: string
          title: Type
        metadata:
          anyOf:
            - type: string
            - type: object
            - type: 'null'
          title: Metadata
        source_type:
          type: string
          title: Source Type
          default: papr
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
        location:
          anyOf:
            - type: string
            - type: 'null'
          title: Location
        tags:
          items:
            type: string
          type: array
          title: Tags
        hierarchical_structures:
          type: string
          title: Hierarchical Structures
          default: ''
        source_url:
          type: string
          title: Source Url
          default: ''
        conversation_id:
          type: string
          title: Conversation Id
          default: ''
        topics:
          items:
            type: string
          type: array
          title: Topics
        steps:
          items:
            type: string
          type: array
          title: Steps
        current_step:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Step
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        acl:
          additionalProperties:
            additionalProperties:
              type: boolean
            type: object
          type: object
          title: Acl
        user_id:
          type: string
          title: User Id
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        source_document_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Document Id
        source_message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Message Id
        page_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Number
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
        file_url:
          anyOf:
            - type: string
            - type: 'null'
          title: File Url
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
        page:
          anyOf:
            - type: string
            - type: 'null'
          title: Page
      additionalProperties: true
      type: object
      required:
        - id
        - content
        - type
        - acl
        - user_id
      title: Memory
      description: A memory item in the knowledge base
    MemoryMetadata:
      properties:
        topics:
          anyOf:
            - type: string
            - type: 'null'
          title: Topics
        hierarchical_structures:
          anyOf:
            - type: string
            - type: 'null'
          title: Hierarchical Structures
          description: >-
            Hierarchical structures to enable navigation from broad topics to
            specific ones
        createdAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Createdat
          description: ISO datetime when the memory was created
        location:
          anyOf:
            - type: string
            - type: 'null'
          title: Location
        emoji tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Emoji Tags
        emotion tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Emotion Tags
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
      additionalProperties: true
      type: object
      title: MemoryMetadata
      description: Metadata for memory request
    MemoryType:
      type: string
      enum:
        - text
        - code_snippet
        - document
      title: MemoryType
      description: Valid memory types
    Node:
      properties:
        label:
          $ref: '#/components/schemas/NodeLabel'
        properties:
          anyOf:
            - $ref: '#/components/schemas/PaprMemoryNodeProperties'
            - $ref: '#/components/schemas/PersonNodeProperties'
            - $ref: '#/components/schemas/CompanyNodeProperties'
            - $ref: '#/components/schemas/ProjectNodeProperties'
            - $ref: '#/components/schemas/TaskNodeProperties'
            - $ref: '#/components/schemas/InsightNodeProperties'
            - $ref: '#/components/schemas/MeetingNodeProperties'
            - $ref: '#/components/schemas/OpportunityNodeProperties'
            - $ref: '#/components/schemas/CodeNodeProperties'
          title: Properties
      type: object
      required:
        - label
        - properties
      title: Node
      description: Public-facing node structure matching our internal representation
    NodeLabel:
      type: string
      enum:
        - Memory
        - Person
        - Company
        - Project
        - Task
        - Insight
        - Meeting
        - Opportunity
        - Code
      title: NodeLabel
    OpportunityNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        value:
          type: number
          title: Value
        stage:
          type: string
          enum:
            - prospect
            - lead
            - opportunity
            - won
            - lost
          title: Stage
        close_date:
          type: string
          title: Close Date
        probability:
          type: number
          title: Probability
        next_steps:
          items:
            type: string
          type: array
          title: Next Steps
      additionalProperties: false
      type: object
      required:
        - id
        - title
        - description
        - value
        - stage
        - close_date
        - probability
        - next_steps
      title: OpportunityNodeProperties
      description: Opportunity node properties
    PaprMemoryNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        content:
          type: string
          title: Content
        type:
          type: string
          title: Type
        topics:
          items:
            type: string
          type: array
          title: Topics
        emotion_tags:
          items:
            type: string
          type: array
          title: Emotion Tags
        steps:
          items:
            type: string
          type: array
          title: Steps
        current_step:
          type: string
          title: Current Step
          default: ''
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        emoji_tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Emoji Tags
        hierarchical_structures:
          anyOf:
            - type: string
            - type: 'null'
          title: Hierarchical Structures
          default: ''
      additionalProperties: false
      type: object
      required:
        - id
        - content
        - type
        - topics
        - emotion_tags
        - steps
        - current_step
      title: PaprMemoryNodeProperties
      description: Memory node properties
    PersonNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        role:
          type: string
          title: Role
        description:
          type: string
          title: Description
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - role
        - description
      title: PersonNodeProperties
      description: Person node properties
    ProjectNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        description:
          type: string
          title: Description
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - type
        - description
      title: ProjectNodeProperties
      description: Project node properties
    RelationshipItem:
      properties:
        related_item_id:
          type: string
          enum:
            - TextMemoryItem
            - previous_memory_item_id
          title: Related Item Id
        relation_type:
          type: string
          title: Relation Type
        related_item_type:
          type: string
          const: TextMemoryItem
          title: Related Item Type
        metadata:
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      required:
        - related_item_id
        - relation_type
        - related_item_type
      title: RelationshipItem
      description: Relationship item for memory request
    SearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: >-
            Detailed search query describing what you're looking for. For best
            results, write 2-3 sentences that include specific details, context,
            and time frame. For example: 'Find recurring customer complaints
            about API performance from the last month. Focus on issues where
            customers specifically mentioned timeout errors or slow response
            times in their conversations.'
          examples:
            - >-
              Show me the most critical customer pain points from my recent
              conversations. Focus on issues that multiple customers have
              mentioned and any specific feature requests or workflow
              improvements they've suggested.
        rank_results:
          type: boolean
          title: Rank Results
          description: >-
            Whether to enable additional ranking of search results. Default is
            false because results are already ranked when using an LLM for
            search (recommended approach). Only enable this if you're not using
            an LLM in your search pipeline and need additional result ranking.
          default: false
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: >-
            Optional user ID to filter search results by a specific user. If not
            provided, results are not filtered by user.
      type: object
      required:
        - query
      title: SearchRequest
      description: Search request parameters
      example:
        query: >-
          Find recurring customer complaints about API performance from the last
          month. Focus on issues where customers specifically mentioned timeout
          errors or slow response times in their conversations.
        rank_results: true
        user_id: user123
    SearchResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
          default: 200
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
          default: success
        data:
          anyOf:
            - $ref: '#/components/schemas/SearchResult'
            - type: 'null'
          description: Search results if successful
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
      type: object
      title: SearchResponse
      example:
        code: 200
        data:
          memories: []
          nodes: []
        status: success
    SearchResult:
      properties:
        memories:
          items:
            $ref: '#/components/schemas/Memory'
          type: array
          title: Memories
        nodes:
          items:
            $ref: '#/components/schemas/Node'
          type: array
          title: Nodes
      type: object
      required:
        - memories
        - nodes
      title: SearchResult
      description: Return type for SearchResult
    SystemUpdateStatus:
      properties:
        pinecone:
          type: boolean
          title: Pinecone
          default: false
        neo4j:
          type: boolean
          title: Neo4J
          default: false
        parse:
          type: boolean
          title: Parse
          default: false
      type: object
      title: SystemUpdateStatus
      description: Status of update operation for each system
    TaskNodeProperties:
      properties:
        user_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Read Access
        user_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: User Write Access
        workspace_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Read Access
        workspace_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Workspace Write Access
        role_read_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Read Access
        role_write_access:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role Write Access
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        sourceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourcetype
        sourceUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceurl
        pageId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pageid
        conversationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversationid
        createdAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        status:
          type: string
          enum:
            - new
            - in_progress
            - completed
          title: Status
        type:
          type: string
          enum:
            - task
            - subtask
            - bug
            - feature_request
            - epic
            - support_ticket
          title: Type
      additionalProperties: false
      type: object
      required:
        - id
        - title
        - description
        - status
        - type
      title: TaskNodeProperties
      description: Task node properties
    UpdateMemoryItem:
      properties:
        objectId:
          type: string
          title: Objectid
        memoryId:
          type: string
          title: Memoryid
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
          default: ''
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        memoryChunkIds:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Memorychunkids
          default: []
      additionalProperties: false
      type: object
      required:
        - objectId
        - memoryId
        - updatedAt
      title: UpdateMemoryItem
      description: Model for a single updated memory item
    UpdateMemoryRequest:
      properties:
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
          description: The new content of the memory item
        type:
          anyOf:
            - $ref: '#/components/schemas/MemoryType'
            - type: 'null'
          description: Content type of the memory item
        metadata:
          anyOf:
            - $ref: '#/components/schemas/MemoryMetadata'
            - type: 'null'
          description: Updated metadata for Neo4J and Pinecone
        context:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextItem'
              type: array
            - type: 'null'
          title: Context
          description: Updated context for the memory item
        relationships_json:
          anyOf:
            - items:
                $ref: '#/components/schemas/RelationshipItem'
              type: array
            - type: 'null'
          title: Relationships Json
          description: Updated relationships for Graph DB (neo4J)
      additionalProperties: false
      type: object
      title: UpdateMemoryRequest
      description: Request model for updating an existing memory
      example:
        content: Updated meeting notes from the product planning session
        context:
          - content: Let's update the Q2 product roadmap
            role: user
          - content: >-
              I'll help you update the roadmap. What changes would you like to
              make?
            role: assistant
        metadata:
          emoji tags: 📊,💡,📝,✨
          emotion tags: focused, productive, satisfied
          hierarchical structures: Business/Planning/Product/Updates
          topics: product, planning, updates
        relationships_json:
          - metadata:
              relevance: high
            related_item_id: previous_memory_item_id
            related_item_type: TextMemoryItem
            relation_type: updates
        type: text
    UpdateMemoryResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
          default: 200
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
          default: success
        memory_items:
          anyOf:
            - items:
                $ref: '#/components/schemas/UpdateMemoryItem'
              type: array
            - type: 'null'
          title: Memory Items
          description: List of updated memory items if successful
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if failed
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
          description: Additional error details or context
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Status message
        status_obj:
          anyOf:
            - $ref: '#/components/schemas/SystemUpdateStatus'
            - type: 'null'
          description: System update status (pinecone, neo4j, parse)
      additionalProperties: false
      type: object
      title: UpdateMemoryResponse
      description: >-
        Unified response model for update_memory API endpoint (success or
        error).
    UpdateUserRequest:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
        type:
          anyOf:
            - $ref: '#/components/schemas/UserType'
            - type: 'null'
      type: object
      title: UpdateUserRequest
      description: Request model for updating a user
      example:
        email: updated.user@example.com
        external_id: updated_user_123
        metadata:
          name: Updated User
          preferences:
            theme: light
        type: developerUser
    UserListResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
        data:
          anyOf:
            - items:
                $ref: '#/components/schemas/UserResponse'
              type: array
            - type: 'null'
          title: Data
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        page_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Size
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
      type: object
      required:
        - code
        - status
      title: UserListResponse
      example:
        code: 200
        data:
          - created_at: '2024-03-20T10:00:00.000Z'
            email: user1@example.com
            external_id: user123
            metadata:
              name: John Doe
              preferences:
                theme: dark
            updated_at: '2024-03-20T10:00:00.000Z'
            user_id: abc123
        page: 1
        page_size: 10
        status: success
        total: 1
    UserResponse:
      properties:
        code:
          type: integer
          title: Code
          description: HTTP status code
        status:
          type: string
          title: Status
          description: '''success'' or ''error'''
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
      type: object
      required:
        - code
        - status
      title: UserResponse
      description: Response model for user operations
      example:
        code: 200
        created_at: '2024-03-20T10:00:00.000Z'
        email: user@example.com
        external_id: user123
        metadata:
          name: John Doe
          preferences:
            theme: dark
        status: success
        updated_at: '2024-03-20T10:00:00.000Z'
        user_id: abc123
    UserType:
      type: string
      enum:
        - developerUser
        - user
        - agent
      title: UserType
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    Bearer:
      type: http
      scheme: bearer
servers:
  - url: https://memory.papr.ai
    description: Production server
