---
title: "Create Graph"
method: POST
path: "/graph/create"
tags: ["Graph"]
---

# Create Graph

`POST /graph/create`

Create a new graph based on document contents.

The graph is created asynchronously. A stub graph record is returned with
``status = "processing"`` while a background task extracts entities and
relationships.

Args:
    request: Graph creation parameters including name and optional filters.
    auth: Authentication context authorizing the operation.

Returns:
    The placeholder :class:`Graph` object which clients can poll for status.

## Headers

- `authorization` string

## Request body

- CreateGraphRequest — Request model for creating a graph
  - `name` string, required — Name of the graph to create
  - `filters` object, nullable — Optional metadata filters to determine which documents to include
  - `documents` string[], nullable — Optional list of specific document IDs to include
  - `prompt_overrides` GraphPromptOverrides — 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.
    - `entity_extraction` EntityExtractionPromptOverride — 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): ```
      - `prompt_template` string, nullable — 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.
      - `examples` EntityExtractionExample[], nullable — Examples of entities to extract, used to guide the LLM toward domain-specific entity types and patterns.
        - `label` string, required — The entity label (e.g., 'John Doe', 'Apple Inc.')
        - `type` string, required — The entity type (e.g., 'PERSON', 'ORGANIZATION', 'PRODUCT')
        - `properties` object, nullable — Optional properties of the entity (e.g., {'role': 'CEO', 'age': 42})
    - `entity_resolution` EntityResolutionPromptOverride — 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. ```
      - `prompt_template` string, nullable — 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.
      - `examples` EntityResolutionExample[], nullable — 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.
        - `canonical` string, required — The canonical (standard/preferred) form of the entity
        - `variants` string[], required — List of variant forms that should resolve to the canonical form
  - `folder_name` union — Optional folder scope for the operation. Accepts a single folder name or a list of folder names.
    - string
    - string[]
  - `end_user_id` string, nullable — Optional end-user scope for the operation

## Response `200`

Successful Response

- Graph — Represents a knowledge graph
  - `id` string
  - `name` string, required
  - `entities` Entity[]
    - `id` string
    - `label` string, required
    - `type` string, required
    - `properties` object
    - `document_ids` string[]
    - `chunk_sources` object
  - `relationships` Relationship[]
    - `id` string
    - `source_id` string, required
    - `target_id` string, required
    - `type` string, required
    - `document_ids` string[]
    - `chunk_sources` object
  - `metadata` object
  - `system_metadata` object
  - `document_ids` string[]
  - `filters` object, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `folder_name` string, nullable
  - `end_user_id` string, nullable
  - `app_id` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.dev/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphik-org/fastapi/revisions/9ade02dd7b1d/schema)