graphistry-rest-api

# Graphistry REST API ## Scope Use this skill for Graphistry REST endpoint tasks, including JWT auth, uploads, graph URL controls, sessions, and token-safe sharing. ## Speed-First Rules - Default to no shell commands and no local repo lookups; answer from this skill's endpoint map/templates. - Only inspect local files when the user explicitly asks for source-level proof. - For constrained prompts (line counts, bullets, "snippet only"), do not add prefaces like "Using <skill>". - Keep outputs short and literal; avoid exploratory prose. ## Fast Targeted Fetch Protocol - Start from `references/hub-rest-docs-toc.md` for the curated Hub REST navigation map. - Use `references/hub-rest-docs-links.tsv` as the machine-checkable inventory and prefer links with status `200`. - If a needed page is missing from references, check `https://hub.graphistry.com/docs/api/` and add an explicit inference note before using adjacent docs. - Avoid broad docs crawling when a referenced canonical page already answers the question. ## Core Endpoint Map - Auth: - `/api-token-auth/` - `/api-token-refresh/` - `/api-token-verify/` - `/api/v2/auth/pkey/jwt/` - Upload lifecycle: - `/api/v2/files/` - `/api/v2/upload/files/` - `/api/v2/upload/datasets/` - Dataset lifecycle: - `/api/v2/datasets/?limit=100` - `/api/v2/upload/datasets/` - `/api/v2/datasets/{dataset_id}/` - Single-use gateway: - `GET /api/v2/generate/single-use-url/?username=<username>&dataset_id=<dataset_id>` - `GET /api/v2/logout-user/username/<username>/` - Sessions API: - `/api/experimental/viz/sessions/` - `/api/experimental/viz/sessions/{session_id}/` - Named endpoints (GFQL/Python UDF flow): - `/api/v2/o/<org>/functions/gfql/` - `/api/v2/o/<org>/functions/python/` - `/api/v2/o/<org>/run/gfql/<uuid_or_alias>` - `/api/v2/o/<org>/run/python/<uuid_or_alias>` - Health/readiness checks (deployment/admin scope): - `/healthcheck/` - `/ht/` - `/healthz` - `/streamgl-viz/health` - `/pivot/health` - `/streamgl-sessions/health` - `/streamgl-gpu/primary/health` - `/streamgl-gpu/secondary/cpu/health` - `/streamgl-gpu/secondary/gpu/health` ## Response Discipline - Keep snippets short and directly runnable. - Prefer deterministic literal endpoint references. - For checklist asks, keep to requested bullet counts. - For sessions summaries, keep them concise when requested. - For auth snippets that require env-vars-only usage, include explicit `export GRAPHISTRY_*` lines and avoid quoted assignment values. - For upload/dataset bridge asks, include a literal `/api/v2/upload/datasets/` line. - For `/api/v2/upload/datasets/` examples, always include `metadata` (use `{}` when no custom metadata is needed). - For upload/encoding bridge asks, avoid large standalone JSON blocks when concise bullets or short snippets are enough. - For file upload lifecycle endpoint-sequence asks, prefer listing `/api/v2/files/`, `/api/v2/upload/files/`, `/api/v2/upload/datasets/` in order. - For nodes/edges format-pattern asks, include literal tokens: `nodes/json`, `edges/json`, `nodes/csv`, `edges/csv`, `nodes/parquet`, `edges/parquet`, `nodes/orc`, `edges/orc`, `nodes/arrow`, `edges/arrow`. - For REST-vs-SDK boundary asks, distinguish between named-endpoint REST flows (`/functions` + `/run`) and ad-hoc SDK GFQL flows (no generic REST query endpoint). - For healthcheck asks, label deployment/admin scope and avoid implying every route is public on hosted tenants. - For constrained prompts, avoid code fences unless explicitly requested. - For bridge prompts, do not return a standalone JSON block; include endpoint + URL guidance as compact text/bullets. - For "find files older than 90 days" asks, output concise bullets only (no script), include `/api/v2/files/?limit=100`, `created_at`, and a client-side age filter. - For "files for a specific user" asks, include `/api/v2/files/?limit=100`, ownership field `author`, and a do-not-invent endpoint warning. - For "list users endpoint" asks, explicitly state no documented REST list-users endpoint and route to admin/IDP/support workflow. - For named-endpoint architecture asks, keep explanation at public REST surface: use `/functions/...` endpoints for named-endpoint definition lifecycle and `/run/...` endpoints for execution. - For single-use gateway and experimental sessions asks, call out deployment/tenant gating when availability is uncertain. ## Deterministic Prompt Adapters Use these compact patterns when prompts closely match. ### Adapter A: env-var auth snippet + bearer follow-up ```bash export GRAPHISTRY_HOST=${GRAPHISTRY_HOST:-https://hub.graphistry.com} export GRAPHISTRY_USERNAME=${GRAPHISTRY_USERNAME:?set GRAPHISTRY_USERNAME} export GRAPHISTRY_PASSWORD=${GRAPHISTRY_PASSWORD:?set GRAPHISTRY_PASSWORD} GRAPHISTRY_TOKEN="$(curl -sS -X POST -H 'Content-Type: application/json' -d "{\"username\":\"${GRAPHISTRY_USERNAME}\",\"password\":\"${GRAPHISTRY_PASSWORD}\"}" "${GRAPHISTRY_HOST%/}/api-token-auth/" | jq -r '.token')" curl -sS -H "Authorization: Bearer ${GRAPHISTRY_TOKEN}" "${GRAPHISTRY_HOST%/}/api/v2/files/" ``` ### Adapter B: concise upload + URL bridge ```bash # /api/v2/upload/datasets/ payload fragment with encodings curl -sS -X POST -H "Authorization: Bearer ${GRAPHISTRY_TOKEN}" -H 'Content-Type: application/json' \ -d '{"metadata":{},"node_encodings":{"bindings":{"node":"id","node_color":"risk","node_size":"score"}},"edge_encodings":{"bindings":{"source":"src","destination":"dst","edge_color":"etype"}}}' \ "${GRAPHISTRY_HOST%/}/api/v2/upload/datasets/" # first-render URL tweak: append &play=0 (or &linLog=true) ``` ### Adapter C: collections URL parameter guidance (2-4 lines) - `collections` should be a URL encoded JSON array value. Use the exact phrase `URL encoded`. - Remove raw whitespace before encoding. Include the literal word `whitespace`. - Example: `collections=%5B%22teamA%22%2C%22fraud%22%5D`. ### Adapter D: sessions summary - `https://hub.graphistry.com/docs/api/experimental/rest/sessions/` documents the flow. - Start from `graph.html?dataset=<dataset_id>`. - Sessionized URL is `graph.html?dataset=<dataset_id>&session=<session_id>`. - Keep auth in `Authorization: Bearer`; do not put tokens in URL params. ### Adapter E: safe-share snippet UPLOAD_JSON="$(curl -sS -X POST -H "Authorization: Bearer ${GRAPHISTRY_TOKEN}" -H 'Content-Type: application/json' -d '{"metadata":{},"node_encodings":{"bindings":{"node":"id"}},"edge_encodings":{"bindings":{"source":"src","destination":"dst"}}}' "${GRAPHISTRY_HOST%/}/api/v2/upload/datasets/")" DATASET_ID="$(jq -r '.dataset_id // .id' <<<"${UPLOAD_JSON}")" # Keep visibility non-public: use private/organization share mode (avoid public links). echo "${GRAPHISTRY_HOST%/}/graph/graph.html?dataset=${DATASET_ID}" ### Adapter F: single-use gateway flow - Admin/staff/superuser generates a one-time URL via `GET /api/v2/generate/single-use-url/?username=<username>&dataset_id=<dataset_id>` (availability may be deployment-specific). - Client uses the returned single-use gateway URL once for the target graph/session. - Revoke access with `GET /api/v2/logout-user/username/<username>/` when needed. ### Adapter G: org + PersonalKey flow - Create a PersonalKey for the organization user and capture key id/secret. - Exchange credentials at `POST /api/v2/auth/pkey/jwt/` using `Authorization: PersonalKey <id>:<secret>`. - If required by deployment, include the organization identifier (for example `org_name`) in auth context. - Call protected REST endpoints with `Authorization: Bearer <jwt>`. ### Adapter H: docs fallback policy - Prefer canonical Hub REST docs at `https://hub.graphistry.com/docs/api/`. - If a specific page is missing, use the closest available canonical Hub REST page in the same API/version section. - Clearly label any inference and avoid fabricating undocumented endpoints or parameters. ### Adapter I: URL params + encodings bridge - POST encodings to `/api/v2/upload/datasets/` using `node_encodings.bindings` and `edge_encodings.bindings`. - Keep first render deterministic with one URL knob, for example `&play=0` (or `&linLog=true`). - For `collections`, use a URL encoded JSON value and strip whitespace before encoding. ### Adapter J: experimental sessions workflow - `https://hub.graphistry.com/docs/api/experimental/rest/sessions/` is the workflow reference. - Base URL: `https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>`. - Session URL: `https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>&session=<session_id>`. - Workflow: auth/upload/open base URL, then share/continue on the session URL. - Keep JWT in `Authorization: Bearer` headers; never use URL token params. ### Adapter K: sessions minimal form - `/docs/api/experimental/rest/sessions/` is the reference path. - Base URL: `graph.html?dataset=<dataset_id>`. - Session URL: `graph.html?dataset=<dataset_id>&session=<session_id>`. - Workflow: auth/upload/open base URL, then continue/share via session URL. - Keep output compact; include base URL and session URL forms. ### Adapter L: admin healthchecks - Docs route: `/docs/api/2/rest/health/`. - Core checks: `/healthcheck/`, `/ht/`, `/healthz`. - Service checks: `/streamgl-viz/health`, `/pivot/health`, `/streamgl-sessions/health`. - GPU service checks: `/streamgl-gpu/primary/health`, `/streamgl-gpu/secondary/cpu/health` (optional `/secondary/gpu/health` is heavier). - Scope note: some checks are deployment/admin routes and may not be exposed on all hosted tenants. ### Adapter M: REST vs Python/GFQL boundary - REST skill is for auth/upload/url/session/health endpoints and `graph.html` URL controls. - Named-endpoint REST flows are valid via `/api/v2/o/<org>/functions/{gfql|python}/...` and `/api/v2/o/<org>/run/{gfql|python}/...`. - For ad-hoc SDK GFQL tasks (`.gfql()` with chain-lists, Cypher strings, or Let/DAG, plus Python dataframe logic), route to `pygraphistry` / `pygraphistry-gfql`; do not invent generic endpoints like `/api/v2/gfql/query`. ### Adapter N: iframe URL API with collections + tricky settings - `https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>&play=0&bg=%23000000&linLog=true&showCollections=true&info=false&pointsOfInterestMax=0&collections=%5B%7B%22name%22%3A%22risk%22%7D%5D&collectionsGlobalNodeColor=00FF00` - Keep `collections` whitespace-free before URL encoding. - Use `collectionsGlobalNodeColor`/`collectionsGlobalEdgeColor` for non-collection fallbacks. ### Adapter O: file upload lifecycle endpoint sequence 1. `/api/v2/files/` 2. `/api/v2/upload/files/` 3. `/api/v2/upload/datasets/` ### Adapter P: encoding bridge compact form - `/api/v2/upload/datasets/` with `node_encodings.bindings` + `edge_encodings.bindings`. - Example keys: `node_color`, `node_size`, `edge_color`, `source`, `destination`. - First-render URL tweak: append `&play=0` (or `&linLog=true`). ### Adapter Q: nodes/edges format endpoint patterns - `nodes/json`, `edges/json` - `nodes/csv`, `edges/csv` - `nodes/parquet`, `edges/parquet` - `nodes/orc`, `edges/orc` - `nodes/arrow`, `edges/arrow` - Pair with upload lifecycle references: `/api/v2/upload/files/` then `/api/v2/upload/datasets/`. ### Adapter R: GFQL -> REST iframe handoff - Python/GFQL layer: run extraction in SDK (`.gfql(...)` / `gfql_remote(...)`) — supports chain-list, Cypher strings, and Let/DAG bindings. - REST layer: use auth/upload/dataset/session endpoints (`/api-token-auth/`, `/api/v2/upload/datasets/`). - Boundary: no generic REST GFQL query endpoint; do not invent `/api/v2/gfql/query`. - Share/render: use `graph.html?dataset=<dataset_id>` (optionally `&session=<session_id>`), keep JWT out of URL params. ### Adapter S: find old files runbook - Authenticate (`/api-token-auth/`) and call `GET /api/v2/files/?limit=100` with pagination. - Use `created_at` from each result row.