PlanetGraph | AI-Native Graph Database

API Documentation

Everything you need to integrate with PlanetGraph.

Quick Start

Start with these prompts in your preferred coding agent, then iterate with follow-up questions.

Sign up to get your API key

Interactive

Explore the live OpenAPI reference, authorize with an API key, and try requests directly against the API.

Open interactive API docs open_in_new

Authentication

Use X-API-Key for API keys. Authorization: Bearer ... is only for Firebase user tokens.

curl -H "X-API-Key: YOUR_API_KEY" \ https://api.planetgraph.ai/api/v1/nodes

Account & API Keys

Inspect your account identity and manage API keys for integrations.

GET /api/v1/api-keys

List Api Keys

POST /api/v1/api-keys

Create Api Key

DELETE /api/v1/api-keys/{key_id}

Revoke Api Key

POST /api/v1/auth/mfa/recovery-code

Use Recovery Code

GET /api/v1/me

Get Me

GET /api/v1/me/security

Get Security Status

GET /api/v1/me/security/recovery-codes

Get Recovery Code Status

POST /api/v1/me/security/recovery-codes

Regenerate Recovery Codes

Nodes

Create, read, update, and delete graph nodes.

GET /api/v1/nodes

List Nodes

POST /api/v1/nodes

Create Node

GET /api/v1/nodes/{node_id}

Get Node

PATCH /api/v1/nodes/{node_id}

Update Node

DELETE /api/v1/nodes/{node_id}

Delete Node

GET /api/v1/nodes/types

List Node Types

Edges

Create and manage relationships between nodes.

GET /api/v1/edges

List Edges

POST /api/v1/edges

Create Edge

GET /api/v1/edges/{edge_id}

Get Edge

PATCH /api/v1/edges/{edge_id}

Update Edge

DELETE /api/v1/edges/{edge_id}

Delete Edge

GET /api/v1/edges/by-node/{node_id}

List Edges For Node

GET /api/v1/edges/types

List Edge Types

Properties

Manage properties on nodes and edges with granular access controls.

POST /api/v1/admin/rotate-keys/{account_id}

Rotate Keys

GET /api/v1/edges/{edge_id}/properties

List Edge Properties

POST /api/v1/edges/{edge_id}/properties

Create or Replace Edge Property

GET /api/v1/nodes/{node_id}/properties

List Node Properties

POST /api/v1/nodes/{node_id}/properties

Create or Replace Node Property

PUT /api/v1/properties/{property_id}

Update Property

DELETE /api/v1/properties/{property_id}

Delete Property

Bulk Imports

Asynchronously create or upsert Nodes, Edges, and Properties in bulk.

Import Format

The current import format is version 1. It supports upsert or create_only mode and uses stable external_id values.

Every import also needs an idempotency_key. This is a key you generate and is unique within your account. If you repeat the same logical import with the same key, PlanetGraph returns the existing job instead of creating a duplicate.

Inline JSON Imports

For small imports (up to 1 MiB, or 1,048,576 bytes, by default), send the complete import document as JSON to POST /api/v1/imports.

{
  "version": 1,
  "mode": "upsert",
  "idempotency_key": "crm-export-2026-07-31",
  "nodes": [
    {
      "external_id": "person:123",
      "type": "Person",
      "visibility": "owner_only"
    }
  ],
  "edges": [],
  "properties": [
    {
      "external_id": "person:123:name",
      "resource_external_id": "person:123",
      "resource_type": "node",
      "resource_entity_type": "Person",
      "name": "name",
      "type": "string",
      "value": "Ada"
    }
  ]
}

The response is 202 Accepted and includes the import job ID.

JSONL File Imports

For larger imports (up to 50 MiB, or 52,428,800 bytes, by default), use the following signed JSONL upload flow.

  1. Calculate the completed JSONL file's exact byte count.
  2. Reserve an upload by sending the following JSON to POST /api/v1/imports/uploads:
{"expected_bytes": 12345}
  1. The response includes an upload_url, an upload_id, and required_headers.
  2. PUT the JSONL file to upload_url. Include every returned required_headers value exactly, including Content-Type and Content-Length. Do NOT send your PlanetGraph API key to the storage URL.
  3. Finalize the uploaded file by sending the job metadata below to POST /api/v1/imports/uploads/{upload_id}/finalize.

Example JSONL File

Each nonblank line is a complete JSON object. The kind field identifies the item type:

{"kind":"node","external_id":"person:123","type":"Person","visibility":"owner_only"}
{"kind":"node","external_id":"company:7","type":"Company","visibility":"public"}
{"kind":"edge","external_id":"works:123:7","type":"WORKS_AT","source_external_id":"person:123","source_type":"Person","target_external_id":"company:7","target_type":"Company","visibility":"owner_only"}
{"kind":"property","external_id":"person:123:name","resource_external_id":"person:123","resource_type":"node","resource_entity_type":"Person","name":"name","type":"string","value":"Ada"}

Finalization Metadata

This finalization request describes the import job. The imported items remain in the uploaded JSONL file and are not repeated here.

{
  "version": 1,
  "mode": "upsert",
  "idempotency_key": "crm-export-2026-07-31"
}

The finalization response is 202 Accepted and includes the import job ID.

Check Progress and Results

Use the import job ID returned by either submission method:

GET /api/v1/imports/{import_id}
GET /api/v1/imports/{import_id}/results?limit=1000&offset=0
GET /api/v1/imports/{import_id}/errors?limit=1000&offset=0

Poll the status endpoint until the job reaches completed, completed_with_errors, failed, or cancelled. Page through results or errors by increasing offset until the response contains fewer records than limit.

Imports preserve normal ownership, billing, encryption, access, search, projection, and embedding behavior.

Endpoint Reference

GET /api/v1/imports

List Imports

POST /api/v1/imports

Create Import

GET /api/v1/imports/{import_id}

Get Import

POST /api/v1/imports/{import_id}/cancel

Cancel Import

GET /api/v1/imports/{import_id}/errors

Get Import Errors

GET /api/v1/imports/{import_id}/results

Get Import Results

POST /api/v1/imports/{import_id}/retry

Retry Import

POST /api/v1/imports/uploads

Create Import Upload

POST /api/v1/imports/uploads/{upload_id}/finalize

Finalize Import Upload

Search

Find searchable properties and semantic matches while preserving visibility and returnability rules.

GET /api/v1/search/properties

Search Properties

GET /api/v1/search/semantic

Semantic Search

POST /api/v1/search/vector

Vector Search

Queries

Execute Cypher queries and access query history.

GET /api/v1/queries/history

Query History

POST /api/v1/query

Run Query

Billing

Manage your token balance and view transaction history.

GET /api/v1/account/balance

Account Balance

POST /api/v1/account/purchase

Purchase Tokens

GET /api/v1/account/transactions

Account Transactions

POST /api/v1/admin/pricing

Create Pricing

GET /api/v1/pricing

Get Pricing

Access Control

Define and manage access policies for your data.

GET /api/v1/access-policies

List Access Policies

POST /api/v1/access-policies

Create Access Policy

PUT /api/v1/access-policies/{policy_id}

Update Access Policy

DELETE /api/v1/access-policies/{policy_id}

Delete Access Policy

PATCH /api/v1/feedback/{feedback_id}

Update Feedback

DELETE /api/v1/feedback/{feedback_id}

Delete Feedback

PATCH /api/v1/properties/{property_id}/access-policy

Assign Access Policy

GET /api/v1/properties/{property_id}/feedback

List Feedback

POST /api/v1/properties/{property_id}/feedback

Create Feedback

POST /api/v1/properties/{property_id}/purchase

Purchase Property Access

GET /api/v1/searchability/property-search-rules

List Property Search Rules

PUT /api/v1/searchability/property-search-rules

Upsert Property Search Rule

DELETE /api/v1/searchability/property-search-rules/{rule_id}

Delete Property Search Rule

Audit Logs

Review account-scoped activity for traceability and compliance workflows.

GET /api/v1/audit-logs

List Audit Logs

PlanetGraph Login+

Login your users through PlanetGraph and gain additional insights

Read the PlanetGraph Login+ guide arrow_forward

Interactive API Reference →