PlanetGraph LLM Full Reference
Version: 2026-07-31

Overview
PlanetGraph provides knowledge graphs for AI agents.

PlanetGraph stores nodes, edges, and gated properties for general-purpose knowledge graphs. AI agents can embed, search, index, discover, and share structured and unstructured data through REST and MCP.

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 <firebase_id_token> 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

8) DataSet Catalog
- DataSets are graph records that group canonical Node and Edge type declarations; multiple DataSets may include the same type.
- Call planetgraph_datasets_list to discover visible DataSets and planetgraph_datasets_describe to inspect one DataSet's included types and declared Property capabilities.
- DataSet declarations describe policy capabilities, not guaranteed physical fields on every record.

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 DataSets and labels/types first
- Use planetgraph_datasets_list and planetgraph_datasets_describe when a curated domain entry point is useful.
- Call planetgraph_schema_describe for visible types and type-level Access and Search declarations.
- Treat these as declared capabilities, not a physical schema: individual records may omit declared Properties and contain undeclared Properties.
- Access and Search declarations are independent. A searchable Property is not necessarily returnable, and a returnable Property is not necessarily searchable.
- Check truncated categories and narrow with node_type, edge_type, or property_name filters when needed.
- Sample nodes and edges with bounded include_properties results to inspect actual records.

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