Create a graph from documents **asynchronously**.

Instead of blocking on the potentially slow entity/relationship extraction, we immediately
create a placeholder graph with `status = "processing"`. A background task then fills in
entities/relationships and marks the graph as completed.

Create Graph

Represents an entity in a knowledge graph

Chunk Sources

Document Ids

Label

Properties

Type

Entity

Example entity for guiding entity extraction.

Used to provide domain-specific examples to the LLM of what entities to extract.
These examples help steer the extraction process toward entities relevant to your domain.

The entity label (e.g., 'John Doe', 'Apple Inc.')

Optional properties of the entity (e.g., {'role': 'CEO', 'age': 42})

The entity type (e.g., 'PERSON', 'ORGANIZATION', 'PRODUCT')

EntityExtractionExample

Configuration for customizing entity extraction prompts.

This allows you to override both the prompt template used for entity extraction
and provide domain-specific examples of entities to be extracted.

If only examples are provided (without a prompt_template), they will be
incorporated into the default prompt. If only prompt_template is provided,
it will be used with default examples (if any).

Required placeholders:
- {content}: Will be replaced with the text to analyze for entity extraction
- {examples}: Will be replaced with formatted examples of entities to extract

Example prompt template:
```
Extract entities from the following text. Look for entities similar to these examples:

{examples}

Text to analyze:
{content}

Extracted entities (in JSON format):
```

Examples of entities to extract, used to guide the LLM toward domain-specific entity types and patterns.

Examples

Custom prompt template, MUST include both {content} and {examples} placeholders. The {content} placeholder will be replaced with the text to analyze, and {examples} will be replaced with formatted examples.

Prompt Template

EntityExtractionPromptOverride

Example for entity resolution, showing how variants should be grouped.

Entity resolution is the process of identifying when different references
(variants) in text refer to the same real-world entity. These examples
help the LLM understand domain-specific patterns for resolving entities.

The canonical (standard/preferred) form of the entity

Canonical

List of variant forms that should resolve to the canonical form

Variants

EntityResolutionExample

Configuration for customizing entity resolution prompts.

Entity resolution identifies and groups variant forms of the same entity.
This override allows you to customize how this process works by providing
a custom prompt template and/or domain-specific examples.

If only examples are provided (without a prompt_template), they will be
incorporated into the default prompt. If only prompt_template is provided,
it will be used with default examples (if any).

Required placeholders:
- {entities_str}: Will be replaced with the extracted entities
- {examples_json}: Will be replaced with JSON-formatted examples of entity resolution groups

Example prompt template:
```
I have extracted the following entities:

{entities_str}

Below are examples of how different entity references can be grouped together:

{examples_json}

Group the above entities by resolving which mentions refer to the same entity.
Return the results in JSON format.
```

Examples of entity resolution groups showing how variants of the same entity should be resolved to their canonical forms. This is particularly useful for domain-specific terminology, abbreviations, and naming conventions.

Custom prompt template that MUST include both {entities_str} and {examples_json} placeholders. The {entities_str} placeholder will be replaced with the extracted entities, and {examples_json} will be replaced with JSON-formatted examples of entity resolution groups.

EntityResolutionPromptOverride

Container for graph-related prompt overrides.

Use this class when customizing prompts for graph operations like
create_graph() and update_graph(), which only support entity extraction
and entity resolution customizations.

This class enforces that only graph-relevant override types are used.

Overrides for entity extraction prompts - controls how entities are identified in text during graph operations

Overrides for entity resolution prompts - controls how variant forms are grouped during graph operations

GraphPromptOverrides

Represents a relationship between entities in a knowledge graph

Source Id

Target Id

Relationship

Location

Message

Error Type

ValidationError

CreateGraphRequest

Graph

HTTPValidationError

Morphik Documentation

What is Morphik?

Getting Started

Get the most out of Morphik by customizing it to your needs

Configure Morphik

An overview of Retrieval Augmented Generation with Vector Similarity Search

Introduction to RAG

Organizing data with user and folder scoping in Morphik

User and Folder Scoping

An overview of rules based ingestion in Morphik

Rules

Using Late-interaction and Contrastive learning to achieve state-of-the-art performance in visual retrieval

Retrieving Images

Leveraging graph-based relationships for improved context and retrieval in RAG systems

Knowledge Graphs and Graph RAG

Learn how to use the Morphik UI interface

Morphik UI

Learn how to use the Morphik command-line interface

Morphik Shell

Enable Claude and other AI assistants to access your Morphik knowledge base

Model Context Protocol (MCP)

Learn how to use the Morphik Python SDK or REST API

Code

Learn how to provision and manage isolated Morphik application environments.

Morphik Management API

Thanking our amazing users for pointing out bugs, requesting features, and being early adopters ❤️

Special Thanks

What I Learnt From Vibe-Coding an Open-Source Alternative to ChatGPT's New Memory Feature

Vibe-Coding Memory

Drowning in Discoveries? How LLMs (and Morphik) Are Learning to Read Science

LLM Science Battle

A technical exploration of why even natively multimodal LLMs struggle with diagram interpretation in documents

When Multimodal Models Go Blind

Morphik’s cache-augmented generation (CAG) gives large language models a memory upgrade, making them 10× faster than traditional RAG by storing long-term context in the transformer key-value cache.

Cache-Augmented Generation – Teaching an AI to Remember for Lightning-Fast Answers

Simple health check endpoint that returns 200 OK.

Ping Health

Ingest a text document.

Args:
    request: IngestTextRequest containing:
        - content: Text content to ingest
        - filename: Optional filename to help determine content type
        - metadata: Optional metadata dictionary
        - rules: Optional list of rules. Each rule should be either:
               - MetadataExtractionRule: {"type": "metadata_extraction", "schema": {...}}
               - NaturalLanguageRule: {"type": "natural_language", "prompt": "..."}
        - folder_name: Optional folder to scope the document to
        - end_user_id: Optional end-user ID to scope the document to
    auth: Authentication context

Returns:
    Document: Metadata of ingested document

Ingest Text

Ingest a file document asynchronously.

Args:
    file: File to ingest
    metadata: JSON string of metadata
    rules: JSON string of rules list. Each rule should be either:
           - MetadataExtractionRule: {"type": "metadata_extraction", "schema": {...}}
           - NaturalLanguageRule: {"type": "natural_language", "prompt": "..."}
    auth: Authentication context
    use_colpali: Whether to use ColPali embedding model
    folder_name: Optional folder to scope the document to
    end_user_id: Optional end-user ID to scope the document to
    redis: Redis connection pool for background tasks

Returns:
    Document with processing status that can be used to check progress

Ingest File

Batch ingest multiple files using the task queue.

Args:
    files: List of files to ingest
    metadata: JSON string of metadata (either a single dict or list of dicts)
    rules: JSON string of rules list. Can be either:
           - A single list of rules to apply to all files
           - A list of rule lists, one per file
    use_colpali: Whether to use ColPali-style embedding
    folder_name: Optional folder to scope the documents to
    end_user_id: Optional end-user ID to scope the documents to
    auth: Authentication context
    redis: Redis connection pool for background tasks

Returns:
    BatchIngestResponse containing:
        - documents: List of created documents with processing status
        - errors: List of errors that occurred during the batch operation

Batch Ingest Files

Retrieve relevant chunks.

Args:
    request: RetrieveRequest containing:
        - query: Search query text
        - filters: Optional metadata filters
        - k: Number of results (default: 4)
        - min_score: Minimum similarity threshold (default: 0.0)
        - use_reranking: Whether to use reranking
        - use_colpali: Whether to use ColPali-style embedding model
        - folder_name: Optional folder to scope the search to
        - end_user_id: Optional end-user ID to scope the search to
    auth: Authentication context

Returns:
    List[ChunkResult]: List of relevant chunks

Retrieve Chunks

Retrieve relevant documents.

Args:
    request: RetrieveRequest containing:
        - query: Search query text
        - filters: Optional metadata filters
        - k: Number of results (default: 4)
        - min_score: Minimum similarity threshold (default: 0.0)
        - use_reranking: Whether to use reranking
        - use_colpali: Whether to use ColPali-style embedding model
        - folder_name: Optional folder to scope the search to
        - end_user_id: Optional end-user ID to scope the search to
    auth: Authentication context

Returns:
    List[DocumentResult]: List of relevant documents

Retrieve Documents

Retrieve multiple documents by their IDs in a single batch operation.

Args:
    request: Dictionary containing:
        - document_ids: List of document IDs to retrieve
        - folder_name: Optional folder to scope the operation to
        - end_user_id: Optional end-user ID to scope the operation to
    auth: Authentication context

Returns:
    List[Document]: List of documents matching the IDs

Batch Get Documents

Retrieve specific chunks by their document ID and chunk number in a single batch operation.

Args:
    request: Dictionary containing:
        - sources: List of ChunkSource objects (with document_id and chunk_number)
        - folder_name: Optional folder to scope the operation to
        - end_user_id: Optional end-user ID to scope the operation to
    auth: Authentication context

Returns:
    List[ChunkResult]: List of chunk results

Batch Get Chunks

Generate completion using relevant chunks as context.

When graph_name is provided, the query will leverage the knowledge graph
to enhance retrieval by finding relevant entities and their connected documents.

Args:
    request: CompletionQueryRequest containing:
        - query: Query text
        - filters: Optional metadata filters
        - k: Number of chunks to use as context (default: 4)
        - min_score: Minimum similarity threshold (default: 0.0)
        - max_tokens: Maximum tokens in completion
        - temperature: Model temperature
        - use_reranking: Whether to use reranking
        - use_colpali: Whether to use ColPali-style embedding model
        - graph_name: Optional name of the graph to use for knowledge graph-enhanced retrieval
        - hop_depth: Number of relationship hops to traverse in the graph (1-3)
        - include_paths: Whether to include relationship paths in the response
        - prompt_overrides: Optional customizations for entity extraction, resolution, and query prompts
        - folder_name: Optional folder to scope the operation to
        - end_user_id: Optional end-user ID to scope the operation to
        - schema: Optional schema for structured output
    auth: Authentication context

Returns:
    CompletionResponse: Generated text completion or structured output

Query Completion

Process a natural language query using the MorphikAgent and return the response.

Agent Query

List accessible documents.

Args:
    auth: Authentication context
    skip: Number of documents to skip
    limit: Maximum number of documents to return
    filters: Optional metadata filters
    folder_name: Optional folder to scope the operation to
    end_user_id: Optional end-user ID to scope the operation to

Returns:
    List[Document]: List of accessible documents

List Documents

Get Document

Delete a document and all associated data.

This endpoint deletes a document and all its associated data, including:
- Document metadata
- Document content in storage
- Document chunks and embeddings in vector store

Args:
    document_id: ID of the document to delete
    auth: Authentication context (must have write access to the document)

Returns:
    Deletion status

Delete Document

Get the processing status of a document.

Args:
    document_id: ID of the document to check
    auth: Authentication context

Returns:
    Dict containing status information for the document

Get Document Status

Get document by filename.

Args:
    filename: Filename of the document to retrieve
    auth: Authentication context
    folder_name: Optional folder to scope the operation to
    end_user_id: Optional end-user ID to scope the operation to

Returns:
    Document: Document metadata if found and accessible

Get Document By Filename

Update a document with new text content using the specified strategy.

Args:
    document_id: ID of the document to update
    request: Text content and metadata for the update
    update_strategy: Strategy for updating the document (default: 'add')

Returns:
    Document: Updated document metadata

Update Document Text

Update a document with content from a file using the specified strategy.

Args:
    document_id: ID of the document to update
    file: File to add to the document
    metadata: JSON string of metadata to merge with existing metadata
    rules: JSON string of rules to apply to the content
    update_strategy: Strategy for updating the document (default: 'add')
    use_colpali: Whether to use multi-vector embedding

Returns:
    Document: Updated document metadata

Update Document File

Update only a document's metadata.

Args:
    document_id: ID of the document to update
    metadata: New metadata to merge with existing metadata

Returns:
    Document: Updated document metadata

Update Document Metadata

Get usage statistics for the authenticated user.

Get Usage Stats

Get Recent Usage

Create a new cache with specified configuration.

Create Cache

Get Cache

Update cache with new documents matching its filter.

Update Cache

Add Docs To Cache

Query Cache

List all folders the user has access to.

Args:
    auth: Authentication context

Returns:
    List[Folder]: List of folders

List Folders

Create a new folder.

Args:
    folder_create: Folder creation request containing name and optional description
    auth: Authentication context

Returns:
    Folder: Created folder

Create Folder

Get a folder by ID.

Args:
    folder_id: ID of the folder
    auth: Authentication context

Returns:
    Folder: Folder if found and accessible

Get Folder

Delete a folder and all associated documents.

Args:
    folder_name: Name of the folder to delete
    auth: Authentication context (must have write access to the folder)

Returns:
    Deletion status

Delete Folder

Add a document to a folder.

Args:
    folder_id: ID of the folder
    document_id: ID of the document
    auth: Authentication context

Returns:
    Success status

Add Document To Folder

Remove a document from a folder.

Args:
    folder_id: ID of the folder
    document_id: ID of the document
    auth: Authentication context

Returns:
    Success status

Remove Document From Folder

Get a graph by name.

This endpoint retrieves a graph by its name if the user has access to it.

Args:
    name: Name of the graph to retrieve
    auth: Authentication context
    folder_name: Optional folder to scope the operation to
    end_user_id: Optional end-user ID to scope the operation to

Returns:
    Graph: The requested graph object

Get Graph

List all graphs the user has access to.

This endpoint retrieves all graphs the user has access to.

Args:
    auth: Authentication context
    folder_name: Optional folder to scope the operation to
    end_user_id: Optional end-user ID to scope the operation to

Returns:
    List[Graph]: List of graph objects

List Graphs

Update an existing graph with new documents.

This endpoint processes additional documents based on the original graph filters
and/or new filters/document IDs, extracts entities and relationships, and
updates the graph with new information.

Args:
    name: Name of the graph to update
    request: UpdateGraphRequest containing:
        - additional_filters: Optional additional metadata filters to determine which new documents to include
        - additional_documents: Optional list of additional document IDs to include
        - prompt_overrides: Optional customizations for entity extraction and resolution prompts
        - folder_name: Optional folder to scope the operation to
        - end_user_id: Optional end-user ID to scope the operation to
    auth: Authentication context

Returns:
    Graph: The updated graph object

Update Graph

Generate a local URI for development. This endpoint is unprotected.

Generate Local Uri

Generate a URI for cloud hosted applications.

Generate Cloud Uri

Set extraction rules for a folder.

Args:
    folder_id: ID of the folder to set rules for
    request: SetFolderRuleRequest containing metadata extraction rules
    auth: Authentication context
    apply_to_existing: Whether to apply rules to existing documents in the folder

Returns:
    Success status with processing results

Set Folder Rule

Delete *all* resources associated with *app_name* for the calling user.

This removes:
• All documents linked to the application's ``app_id`` (includes chunks & S3
  via existing delete_document flow).
• The *apps* table entry.
• The reference in *user_limits.app_ids*.

Delete Cloud App

Generate a cloud URI for *request.app_id* owned by the calling user.

The *user_id* is derived from the bearer token.  The caller can therefore
not create applications for *other* users unless their token carries the
``admin`` permission (mirroring the community behaviour).

Create App

Provision a **brand-new** Neon database for *request.app_name*.

The caller must be authenticated to the dedicated Morphik instance.  The
authenticated user (represented by the JWT's *user_id*) becomes the owner
of the provisioned app.

Create App Route

Destroy the Neon project and metadata associated with *app_name*.

Only the owner of the application (identified via *auth.user_id*) may
perform this destructive action.

Delete App Route

Checks the current authentication status for the given connector type.

Get Auth Status For Connector

Return the provider's *authorization_url* for the given connector.

The method mirrors the logic of the `/auth/initiate` endpoint but sends a
JSON payload instead of a redirect so that browsers can stay on the same
origin until they intentionally navigate away.

Get Initiate Auth Url

Handles the OAuth 2.0 callback from the authentication provider.
Validates state, finalizes authentication, and stores credentials.

Connector Oauth Callback

Lists files and folders from the specified connector.

List Files For Connector

Downloads a file from the connector and ingests it into Morphik via DocumentService.

Ingest File From Connector

Disconnects the user from the specified connector by removing stored credentials.

API Reference

Enterprise

EE - Connectors

Create Graph

Headers

Body

Response