API Documentation

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}

3. The response includes an upload_url, an upload_id, and required_headers.
4. 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.
5. 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.