Skip to content

SKILL.md

Latest commit

 

History

History
275 lines (237 loc) · 16.7 KB

SKILL.md

File metadata and controls

275 lines (237 loc) · 16.7 KB
name graphistry-rest-api
description Graphistry Hub REST API: auth, upload, URL controls, sessions, and sharing. Use when asked to "call the graphistry API with curl", "get a JWT token from graphistry", "upload a graph via REST", "graph.html URL parameters", "graphistry session API", or "share a graph link safely". Also triggers on "/api/v2/", "Bearer token", "graphistry upload endpoint", or any direct HTTP endpoint question about Graphistry Hub. Prefer this over pygraphistry when the user explicitly uses curl, requests, or raw HTTP rather than the Python SDK.

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 ".
  • 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

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

# /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.
  • Client-side filter/sort for created_at <= now-90d.
  • Export matching file_id, name, created_at for review.
  • Optional cleanup should be admin-scoped and follow explicit approval.

Adapter T: files for specific user

  • List files via GET /api/v2/files/?limit=100 (paginate).
  • Filter by ownership metadata, starting with author (and deployment-specific mappings to username if available).
  • If needed, cross-check with GET /api/v2/datasets/?limit=100 for dataset ownership context.
  • Do not invent user-list endpoints; use documented APIs and escalate mapping gaps to admin/support.

Adapter U: list users boundary

  • No documented public REST endpoint to list users in canonical Hub docs.
  • Do not claim concrete routes like GET /api/v2/users/ without a private admin API contract.
  • Use admin/IDP directory workflow (SSO/IdP export or deployment owner process) for user enumeration.
  • Verify against https://hub.graphistry.com/docs/api/ and escalate to support/deployment owner if needed.

Adapter V: privacy via share-link API

  • Create dataset first via /api/v2/upload/datasets/ with required metadata, node_encodings, and edge_encodings.
  • Set visibility with POST /api/v2/share/link/ body: {"obj_pk":"<dataset_id>","obj_type":"dataset","mode":"private","notify":false,"message":"","invited_users":[]}.
  • If inviting users, include entries like {"email":"user@example.com","action":"10"} (10 view, 20 edit).
  • Deployment/docs caveat: this route is deployment-exposed and may not have a dedicated canonical docs page; verify availability on the target tenant.
  • Plan caveat: private/organization requests can be downgraded to public when sharing entitlements are unavailable.

Adapter W: named-endpoint architecture boundary

  • Manage named endpoint definitions via /api/v2/o/<org>/functions/{gfql|python}/....
  • Execute named endpoints via /api/v2/o/<org>/run/{gfql|python}/....
  • Keep guidance on documented external REST routes; avoid internal/backend route details.

Minimal Auth Snippet

Use Adapter A.

Auth Troubleshooting Template (4 bullets)

  • Verify token creation with /api-token-auth/ (or /api/v2/auth/pkey/jwt/ for PersonalKey flow).
  • Verify refresh behavior via /api-token-refresh/ before access-token expiry.
  • Verify token integrity and expiry with /api-token-verify/ and check clock skew.
  • Confirm Authorization: Bearer <token> on protected calls and log HTTP status/body.

Upload + URL Bridge Template

Use Adapter B for snippet form or Adapter I for compact bullet form.

URL and Sharing Safety

  • Safe viewer URL pattern: https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>.
  • Never include JWTs in URL query params (for example, do not add token=).
  • Send tokens only in headers, for example Authorization: Bearer <token>.
  • Useful URL knobs: play, linLog, scalingRatio, pointsOfInterestMax, pointSize, showCollections, info, collectionsGlobalNodeColor, collectionsGlobalEdgeColor.

Collections URL Guidance

  • collections should be a URL encoded JSON value.
  • Remove raw whitespace before encoding.
  • Example: collections=%5B%22teamA%22%2C%22fraud%22%5D.

Sessions (experimental, concise)

  • Docs: https://hub.graphistry.com/docs/api/experimental/rest/sessions/.
  • Start from: graph.html?dataset=<dataset_id>.
  • Session appears as: graph.html?dataset=<dataset_id>&session=<session_id>.

Policy Guardrails

  • Use documented endpoints only; avoid invented endpoints like /api/v2/query, /api/v2/graph/query, /api/v2/render, /api/v2/graphql.
  • Do not present SDK/GFQL behavior as a generic REST endpoint (for example avoid /api/v2/gfql/query claims).
  • Keep named-endpoint guidance at the external REST layer: /functions/... for definition lifecycle and /run/... for execution.
  • For deployment-exposed routes without dedicated docs pages (for example /api/v2/share/link/), explicitly label the uncertainty and advise tenant verification.
  • Keep credentials in environment variables; never hardcode literals.

Canonical Docs