Knowledge Graph

The Knowledge Graph API constructs entity-relationship graphs from parsed documents, enabling advanced querying and discovery of connections across your knowledge base.

Build Knowledge Graph

Construct a knowledge graph from a parsed document by extracting entities and relationships.

Endpoint

POST /api/knowledge-graph

Request Body

document_id

string

required

The ID of the parsed document to process

entity_types

array

Specific entity types to extract (e.g., ["person", "organization", "location"])

extract_relationships

boolean

default:"true"

Whether to extract relationships between entities

Response

graph_id

string

Unique identifier for the knowledge graph job

document_id

string

Source document identifier

status

string

Processing status: pending, processing, completed, failed

Example

curl -X POST https://api.polyvia.ai/api/knowledge-graph \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_abc123xyz",
    "entity_types": ["person", "organization", "technology"],
    "extract_relationships": true
  }'

{
  "graph_id": "graph_xyz789",
  "document_id": "doc_abc123xyz",
  "status": "processing"
}

Query Knowledge Graph

Search the knowledge graph using natural language queries or structured filters.

Endpoint

POST /api/knowledge-graph/query

Request Body

query

string

required

Natural language query or entity name to search for

entity_types

array

Filter results by entity types

max_depth

integer

default:"2"

Maximum relationship depth to traverse (1-5)

limit

integer

default:"20"

Maximum number of entities to return

Response

entities

array

Array of matching entities

Show Entity object

string

Unique entity identifier

name

string

Entity name

type

string

Entity type (e.g., “person”, “organization”)

properties

object

Additional entity properties

source_documents

array

Document IDs where this entity was mentioned

relationships

array

Array of relationships between entities

Show Relationship object

source_id

string

Source entity ID

target_id

string

Target entity ID

type

string

Relationship type (e.g., “works_for”, “located_in”)

confidence

number

Confidence score (0-1)

Example

curl -X POST https://api.polyvia.ai/api/knowledge-graph/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "companies working on AI",
    "entity_types": ["organization"],
    "max_depth": 2,
    "limit": 10
  }'

{
  "entities": [
    {
      "id": "ent_123",
      "name": "OpenAI",
      "type": "organization",
      "properties": {
        "industry": "Artificial Intelligence",
        "founded": "2015"
      },
      "source_documents": ["doc_abc123xyz", "doc_def456"]
    }
  ],
  "relationships": [
    {
      "source_id": "ent_123",
      "target_id": "ent_456",
      "type": "partners_with",
      "confidence": 0.92
    }
  ]
}

Get Graph Statistics

Retrieve statistics and metadata about the knowledge graph.

Endpoint

GET /api/knowledge-graph/stats

Response

total_entities

integer

Total number of entities in the graph

total_relationships

integer

Total number of relationships

entity_types

object

Count of entities by type

documents_processed

integer

Number of documents contributing to the graph

Example

curl https://api.polyvia.ai/api/knowledge-graph/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "total_entities": 1247,
  "total_relationships": 3891,
  "entity_types": {
    "person": 423,
    "organization": 312,
    "location": 189,
    "technology": 323
  },
  "documents_processed": 45
}

Export Graph Data

Export the knowledge graph in various formats for visualization or analysis.

Endpoint

GET /api/knowledge-graph/export

Query Parameters

format

string

default:"json"

Export format: json, cypher, graphml

filter

string

Filter entities by type or property

Example

curl "https://api.polyvia.ai/api/knowledge-graph/export?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o graph.json

Supported Entity Types

People

Person
Author
Executive

Organizations

Company
Institution
Department

Locations

City
Country
Address

Concepts

Technology
Product
Service

Temporal

Date
Event
Period

Financial

Currency
Amount
Transaction

Relationship Types

Common relationship types extracted by the system:

works_for - Employment relationship
located_in - Geographic relationship
part_of - Hierarchical relationship
related_to - General association
mentions - Document reference
uses - Technology/tool usage

The knowledge graph automatically merges duplicate entities across documents, creating a unified view of your knowledge base.

Introduction

Endpoints

Build Knowledge Graph

Endpoint

Request Body

Response

Example

Query Knowledge Graph

Endpoint

Request Body

Response

Example

Get Graph Statistics

Endpoint

Response

Example

Export Graph Data

Endpoint

Query Parameters

Example

Supported Entity Types

People

Organizations

Locations

Concepts

Temporal

Financial

Relationship Types

Introduction

Endpoints

​Build Knowledge Graph

​Endpoint

​Request Body

​Response

​Example

​Query Knowledge Graph

​Endpoint

​Request Body

​Response

​Example

​Get Graph Statistics

​Endpoint

​Response

​Example

​Export Graph Data

​Endpoint

​Query Parameters

​Example

​Supported Entity Types

People

Organizations

Locations

Concepts

Temporal

Financial

​Relationship Types

Build Knowledge Graph

Endpoint

Request Body

Response

Example

Query Knowledge Graph

Endpoint

Request Body

Response

Example

Get Graph Statistics

Endpoint

Response

Example

Export Graph Data

Endpoint

Query Parameters

Example

Supported Entity Types

Relationship Types