PlanetGraph LLM Full Reference

Version: 2026-07-31

Overview

PlanetGraph is an AI-native graph database.

PlanetGraph stores nodes, edges, and gated properties for general-purpose graph applications. It is designed so AI agents can discover graph shape, query relationships, and build higher-level workflows on top of graph data.

Example use cases:

• relationship intelligence
• warm introduction discovery
• PlanetGraph Login+ for user sign-up/login and graph-backed app context
• enterprise knowledge graphs
• graph-backed copilots and agent systems

Example dataset:

• people and companies connected by employment and relationship edges

Important framing:

• the people/company graph is an example dataset
• warm intros are an example application pattern
• the platform itself is generic.

Base URLs

• Product site: https://planetgraph.ai
• API base: https://api.planetgraph.ai
• OpenAPI: https://api.planetgraph.ai/openapi.json
• Swagger UI: https://api.planetgraph.ai/docs

Authentication

Supported API auth methods:

• X-API-Key header (recommended for service-to-service and agent usage)
• Authorization: Bearer for Firebase-authenticated user flows

Interactive docs tip:

• Use Authorize in Swagger and populate ApiKeyAuth (X-API-Key).

Core Resources

1. Nodes

   • Create/list/get/update/delete node records.
   • Node has type (for example Person, Company).

2. Edges

   • Create/list/get/update/delete directed relationships between nodes.
   • Edge has type (for example worked_for, knows).
   • Important: GET /api/v1/edges?type filters by edge type, not node type.
   • Node-type filters on edges: source_type and target_type.

3. Properties

   • Properties can belong to nodes or edges.
   • Access can be owned, granted, or locked.
   • Purchase endpoint grants access to locked properties.

4. Queries

   • POST /api/v1/query executes constrained Cypher subset.
   • GET /api/v1/queries/history returns prior executed queries.

5. Access Policies

   • Create pricing and access rules for properties.

6. PlanetGraph Login+

   • Third-party apps can choose Quick Start: Client-Side JavaScript or Quick Start: Hosted Redirect.
   • Client-Side JavaScript uses the hosted widget script at /widgets/login-plus.js to render a PlanetGraph sign-in button and open the hosted login popup.
   • Hosted Redirect sends users directly to /login_with?app_id=YOUR_APP_UUID&state=YOUR_STATE, then PlanetGraph redirects back to the app callback URL configured for redirect flows.
   • Both approaches accept an optional email prefill and mode=signin or mode=signup initial form selection.
   • App definitions are graph nodes with properties such as name, logo_url, auth_methods, permissions, allowed_origins, and callback_url.
   • A successful login creates or updates graph relationships between the user and app.
   • callback_url is optional for app definitions and required only for hosted redirect or callback result mode.
   • Callback results are sent to the app callback URL as HTTP GET query parameters by default.
   • result_mode=web_message can send the signed login result back to the opener window with postMessage for low-risk client-side integrations.
   • Apps should include a state value when starting login and verify the signed login_token before trusting callback or web_message results.

7. Bulk Imports

   • POST /api/v1/imports submits an asynchronous version-1 JSON manifest for small imports.
   • Large imports reserve a signed upload with POST /api/v1/imports/uploads, PUT JSONL using the exact returned headers, then call POST /api/v1/imports/uploads/{upload_id}/finalize.
   • Poll GET /api/v1/imports/{import_id}; page through /results or /errors with limit and offset.
   • Jobs support cancellation and retry of classified retryable failures.
   • Stable external_id values and a per-account idempotency_key make retries safe.
   • Imports preserve normal ownership, billing, encryption, access policies, search, projection, and embedding behavior.
   • Full machine-readable workflow: /llms/bulk-import.txt

Example Workflow: Warm Intro Discovery

This is one example application pattern built on top of PlanetGraph.

Use relationship traversal patterns that do not require hard-coded famous entities:

• Shared employer bridge:

  MATCH (source:Person)-[:worked_for]->(company:Company)<-[:worked_for]-(target:Person)
  RETURN source, company, target
  LIMIT 100
  

Generic Agent Guidance

For non-people/company domains, the same workflow still applies:

1. inspect available node types
2. inspect available edge types
3. sample node and edge records
4. build traversal patterns around the domain-specific labels

Operational Guidance for Agents

1. Discover labels/types first

   • Sample nodes by type.
   • Sample edges by type and source_type/target_type.

2. Build paths iteratively

   • Start with 1-hop and shared-employer patterns.
   • Add constraints only after validating baseline results.

3. Handle pagination

   • List endpoints use limit and offset.
   • Respect X-Total-Count header where available.

4. Handle auth and 401/403 errors

   • 401 usually means missing/invalid auth header.
   • 403 usually indicates ownership/role constraints.

5. Respect query constraints

   • Query endpoint supports a constrained read-only Cypher subset.

Error Handling

• 400: invalid request parameters or unsupported query form.
• 401: authentication failure.
• 403: insufficient permissions/ownership.
• 404: resource not found.
• 409: conflict (for example policy still referenced).
• 413: inline manifest or uploaded object exceeds the configured import limit.
• 429: rate limit exceeded.

Suggested Retrieval Order for Coding Agents

1. /llms.txt
2. /llms/quickstart.txt
3. /llms/api-auth-and-errors.txt
4. /llms/schema-and-query-shapes.txt
5. /llms/recipes-warm-intros.txt
6. /llms/login-plus.txt
7. /llms/bulk-import.txt
8. /openapi.json