graphistry-rest-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graphistry REST API

Scope

适用范围

Use this skill for Graphistry REST endpoint tasks, including JWT auth, uploads, graph URL controls, sessions, and token-safe sharing.

本技能适用于Graphistry REST端点相关任务，包括JWT认证、上传、图URL控制、会话以及基于令牌的安全分享。

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.

默认不使用shell命令，不查询本地仓库；仅根据本技能的端点映射/模板作答。
仅当用户明确要求源代码级别的验证时，才检查本地文件。
对于受限制的提示（如行数限制、项目符号、“仅提供代码片段”），不要添加诸如“使用<skill>”之类的前缀。
输出要简短、直白；避免探索性的描述。

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.

从
```
references/hub-rest-docs-toc.md
```
获取经过整理的Hub REST导航映射。
使用
```
references/hub-rest-docs-links.tsv
```
作为可机器校验的清单，优先选择状态为
```
200
```
的链接。
如果参考资料中缺少所需页面，请访问
```
https://hub.graphistry.com/docs/api/
```
，并在使用相邻文档前添加明确的推断说明。
当已有参考的标准页面可以回答问题时，避免广泛爬取文档。

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

认证:

```
/api-token-auth/
```
```
/api-token-refresh/
```
```
/api-token-verify/
```
```
/api/v2/auth/pkey/jwt/
```

上传生命周期:

```
/api/v2/files/
```
```
/api/v2/upload/files/
```
```
/api/v2/upload/datasets/
```

数据集生命周期:

```
/api/v2/datasets/?limit=100
```
```
/api/v2/upload/datasets/
```
```
/api/v2/datasets/{dataset_id}/
```

一次性网关:

GET /api/v2/generate/single-use-url/?username=<username>&dataset_id=<dataset_id>

GET /api/v2/logout-user/username/<username>/

会话API:

```
/api/experimental/viz/sessions/
```

/api/experimental/viz/sessions/{session_id}/

命名端点（GFQL/Python UDF流程）:

```
/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>

健康/就绪检查（部署/管理员范围）:

```
/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.

代码片段要简短且可直接运行。
优先使用确定性的字面端点引用。
对于清单类请求，严格遵循要求的项目符号数量。
对于会话摘要请求，按要求保持简洁。
对于仅需使用环境变量的认证片段，包含明确的
```
export GRAPHISTRY_*
```
行，避免使用带引号的赋值。
对于上传/数据集桥接请求，包含字面的
```
/api/v2/upload/datasets/
```
行。
对于
```
/api/v2/upload/datasets/
```
示例，始终包含
```
metadata
```
（无需自定义元数据时使用
```
{}
```
）。
对于上传/编码桥接请求，当简洁的项目符号或短代码片段足够时，避免使用大型独立JSON块。
对于文件上传生命周期端点序列请求，优先按顺序列出
```
/api/v2/files/
```
、
```
/api/v2/upload/files/
```
、
```
/api/v2/upload/datasets/
```
。

对于节点/边格式模式请求，包含字面令牌：

nodes/json

、

edges/json

、

nodes/csv

、

edges/csv

、

nodes/parquet

、

edges/parquet

、

nodes/orc

、

edges/orc

、

nodes/arrow

、

edges/arrow

。

对于REST与SDK边界请求，区分命名端点REST流程（
```
/functions
```
+
```
/run
```
）和临时SDK GFQL流程（无通用REST查询端点）。
对于健康检查请求，标注部署/管理员范围，避免暗示每个路由在托管租户上都是公开的。
对于受限制的提示，除非明确要求，否则不要使用代码块。
对于桥接提示，不要返回独立的JSON块；以紧凑文本/项目符号形式包含端点和URL指导。
对于“查找90天以上的文件”请求，仅输出简洁的项目符号（无脚本），包含
```
/api/v2/files/?limit=100
```
、
```
created_at
```
以及客户端年龄过滤器。
对于“特定用户的文件”请求，包含
```
/api/v2/files/?limit=100
```
、所有权字段
```
author
```
以及不要自行创建端点的警告。
对于“列出用户端点”请求，明确说明没有文档化的REST列出用户端点，并引导至管理员/IDP/支持流程。
对于命名端点架构请求，仅在公开REST层面进行解释：使用
```
/functions/...
```
端点处理命名端点定义生命周期，使用
```
/run/...
```
端点处理执行。
对于一次性网关和实验性会话请求，当可用性不确定时，标注部署/租户限制。

Deterministic Prompt Adapters

确定性提示适配

Use these compact patterns when prompts closely match.

当提示与以下模式高度匹配时，使用这些紧凑模式。

Adapter A: env-var auth snippet + bearer follow-up

适配A：环境变量认证片段 + Bearer后续请求

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/"

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

适配B：简洁上传 + URL桥接

bash

undefined

bash

undefined

/api/v2/upload/datasets/ payload fragment with encodings

/api/v2/upload/datasets/ 负载片段（含编码）

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)

首次渲染URL调整：追加&play=0（或&linLog=true）

undefined

undefined

Adapter C: collections URL parameter guidance (2-4 lines)

适配C：集合URL参数指导（2-4行）

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

```
collections
```
应为URL编码的JSON数组值，请使用精确表述“URL encoded”。
编码前移除原始空格，请包含字面单词
```
whitespace
```
。

示例：

collections=%5B%22teamA%22%2C%22fraud%22%5D

。

Adapter D: sessions summary

适配D：会话摘要

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.

https://hub.graphistry.com/docs/api/experimental/rest/sessions/

记录了相关流程。

从
```
graph.html?dataset=<dataset_id>
```
开始。

会话化URL为

graph.html?dataset=<dataset_id>&session=<session_id>

。

认证信息放在
```
Authorization: Bearer
```
中；不要将令牌放在URL参数中。

Adapter E: safe-share snippet

适配E：安全分享片段

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

适配F：一次性网关流程

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.

管理员/员工/超级用户通过
```
GET /api/v2/generate/single-use-url/?username=<username>&dataset_id=<dataset_id>
```
生成一次性URL（可用性可能因部署而异）。
客户端使用返回的一次性网关URL访问目标图/会话一次。

需要时通过

GET /api/v2/logout-user/username/<username>/

撤销访问权限。

Adapter G: org + PersonalKey flow

适配G：组织 + PersonalKey流程

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>
```
.

为组织用户创建PersonalKey并记录密钥ID/密钥。

使用

Authorization: PersonalKey <id>:<secret>

在

POST /api/v2/auth/pkey/jwt/

交换凭证。

如果部署要求，在认证上下文中包含组织标识符（例如
```
org_name
```
）。
使用
```
Authorization: Bearer <jwt>
```
调用受保护的REST端点。

Adapter H: docs fallback policy

适配H：文档回退策略

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.

优先使用
```
https://hub.graphistry.com/docs/api/
```
上的官方Hub REST文档。
如果特定页面缺失，使用同一API/版本部分中最接近的可用官方Hub REST页面。
明确标注任何推断内容，避免编造未文档化的端点或参数。

Adapter I: URL params + encodings bridge

适配I：URL参数 + 编码桥接

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.

使用

node_encodings.bindings

和

edge_encodings.bindings

将编码POST到

/api/v2/upload/datasets/

。

使用一个URL参数确保首次渲染的确定性，例如
```
&play=0
```
（或
```
&linLog=true
```
）。
对于
```
collections
```
，使用URL编码的JSON值，并在编码前去除空格。

Adapter J: experimental sessions workflow

适配J：实验性会话工作流

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.

https://hub.graphistry.com/docs/api/experimental/rest/sessions/

是工作流参考文档。

基础URL：

https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>

。

会话URL：

https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>&session=<session_id>

。

工作流：认证/上传/打开基础URL，然后在会话URL上进行分享/继续操作。
将JWT放在
```
Authorization: Bearer
```
头中；切勿使用URL令牌参数。

Adapter K: sessions minimal form

适配K：会话最简形式

```
/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.

参考路径：
```
/docs/api/experimental/rest/sessions/
```
。
基础URL：
```
graph.html?dataset=<dataset_id>
```
。

会话URL：

graph.html?dataset=<dataset_id>&session=<session_id>

。

工作流：认证/上传/打开基础URL，然后通过会话URL继续/分享。
保持输出紧凑；包含基础URL和会话URL格式。

Adapter L: admin healthchecks

适配L：管理员健康检查

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.

文档路径：
```
/docs/api/2/rest/health/
```
。
核心检查：
```
/healthcheck/
```
、
```
/ht/
```
、
```
/healthz
```
。

服务检查：

/streamgl-viz/health

、

/pivot/health

、

/streamgl-sessions/health

。

GPU服务检查：

/streamgl-gpu/primary/health

、

/streamgl-gpu/secondary/cpu/health

（可选的

/secondary/gpu/health

开销较大）。

范围说明：部分检查属于部署/管理员路由，可能不会在所有托管租户上暴露。

Adapter M: REST vs Python/GFQL boundary

适配M：REST与Python/GFQL边界

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
```
.

REST技能适用于认证/上传/URL/会话/健康端点以及
```
graph.html
```
URL控制。

命名端点REST流程可通过

/api/v2/o/<org>/functions/{gfql|python}/...

和

/api/v2/o/<org>/run/{gfql|python}/...

实现。

对于临时SDK GFQL任务（
```
.gfql()
```
配合链式列表、Cypher字符串或Let/DAG，以及Python数据框逻辑），请引导至
```
pygraphistry
```
/
```
pygraphistry-gfql
```
；不要编造诸如
```
/api/v2/gfql/query
```
之类的通用端点。

Adapter N: iframe URL API with collections + tricky settings

适配N：带集合和复杂设置的iframe URL API

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.

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

```
collections
```
在URL编码前不要包含空格。

使用

collectionsGlobalNodeColor

collectionsGlobalEdgeColor

作为非集合的回退设置。

Adapter O: file upload lifecycle endpoint sequence

适配O：文件上传生命周期端点序列

```
/api/v2/files/
```
```
/api/v2/upload/files/
```
```
/api/v2/upload/datasets/
```

```
/api/v2/files/
```
```
/api/v2/upload/files/
```
```
/api/v2/upload/datasets/
```

Adapter P: encoding bridge compact form

适配P：编码桥接紧凑形式

/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
```
).

/api/v2/upload/datasets/

配合

node_encodings.bindings

edge_encodings.bindings

。

示例键：

node_color

、

node_size

、

edge_color

、

source

、

destination

。

首次渲染URL调整：追加
```
&play=0
```
（或
```
&linLog=true
```
）。

Adapter Q: nodes/edges format endpoint patterns

适配Q：节点/边格式端点模式

```
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/

```
nodes/json
```
、
```
edges/json
```
```
nodes/csv
```
、
```
edges/csv
```
```
nodes/parquet
```
、
```
edges/parquet
```
```
nodes/orc
```
、
```
edges/orc
```
```
nodes/arrow
```
、
```
edges/arrow
```

配合上传生命周期参考：

/api/v2/upload/files/

然后

/api/v2/upload/datasets/

。

Adapter R: GFQL -> REST iframe handoff

适配R：GFQL -> REST iframe 转交

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.

Python/GFQL层：在SDK中运行提取（
```
.gfql(...)
```
/
```
gfql_remote(...)
```
）——支持链式列表、Cypher字符串和Let/DAG绑定。
REST层：使用认证/上传/数据集/会话端点（
```
/api-token-auth/
```
、
```
/api/v2/upload/datasets/
```
）。
边界：没有通用的REST GFQL查询端点；不要编造
```
/api/v2/gfql/query
```
。
分享/渲染：使用
```
graph.html?dataset=<dataset_id>
```
（可选
```
&session=<session_id>
```
），不要将JWT放在URL参数中。

Adapter S: find old files runbook

适配S：查找旧文件手册

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.

认证（

/api-token-auth/

）并调用

GET /api/v2/files/?limit=100

进行分页。

使用每个结果行中的
```
created_at
```
字段。
在客户端过滤/排序
```
created_at <= now-90d
```
的文件。
导出匹配的
```
file_id
```
、
```
name
```
、
```
created_at
```
以供审核。
可选的清理操作应属于管理员范围，并遵循明确的审批流程。

Adapter T: files for specific user

适配T：特定用户的文件

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.

通过
```
GET /api/v2/files/?limit=100
```
列出文件（分页）。
根据所有权元数据过滤，首先使用
```
author
```
（以及可用的部署特定用户名映射）。
如果需要，通过
```
GET /api/v2/datasets/?limit=100
```
交叉检查数据集所有权上下文。
不要创建用户列表端点；使用文档化的API，并将映射差距上报给管理员/支持人员。

Adapter U: list users boundary

适配U：列出用户边界

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.

官方Hub文档中没有公开的REST端点用于列出用户。
在没有私有管理员API协议的情况下，不要声称存在
```
GET /api/v2/users/
```
之类的具体路由。
使用管理员/IDP目录工作流（SSO/IdP导出或部署所有者流程）进行用户枚举。
根据
```
https://hub.graphistry.com/docs/api/
```
进行验证，如有需要请上报给支持人员/部署所有者。

Adapter V: privacy via share-link API

适配V：通过分享链接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.

首先通过

/api/v2/upload/datasets/

创建数据集，包含必填的

metadata

、

node_encodings

和

edge_encodings

。

通过

POST /api/v2/share/link/

请求体设置可见性：

{"obj_pk":"<dataset_id>","obj_type":"dataset","mode":"private","notify":false,"message":"","invited_users":[]}

。

如果邀请用户，包含类似
```
{"email":"user@example.com","action":"10"}
```
的条目（
```
10
```
表示查看，
```
20
```
表示编辑）。
部署/文档说明：该路由是部署暴露的，可能没有专门的官方文档页面；请在目标租户上验证可用性。
方案说明：当分享权限不可用时，私有/组织请求可能会降级为
```
public
```
。

Adapter W: named-endpoint architecture boundary

适配W：命名端点架构边界

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.

通过

/api/v2/o/<org>/functions/{gfql|python}/...

管理命名端点定义。

通过
```
/api/v2/o/<org>/run/{gfql|python}/...
```
执行命名端点。
仅针对文档化的外部REST路由提供指导；避免内部/后端路由细节。

Minimal Auth Snippet

最小化认证片段

Use Adapter A.

使用适配A。

Auth Troubleshooting Template (4 bullets)

认证故障排查模板（4个项目符号）

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.

通过
```
/api-token-auth/
```
（或PersonalKey流程的
```
/api/v2/auth/pkey/jwt/
```
）验证令牌创建。
在访问令牌过期前，通过
```
/api-token-refresh/
```
验证刷新行为。
通过
```
/api-token-verify/
```
验证令牌完整性和过期时间，并检查时钟偏差。
在受保护的调用中确认使用
```
Authorization: Bearer <token>
```
，并记录HTTP状态/响应体。

Upload + URL Bridge Template

上传 + URL桥接模板

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

代码片段形式使用适配B，紧凑项目符号形式使用适配I。

URL and Sharing Safety

URL与分享安全

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

安全查看器URL格式：

https://hub.graphistry.com/graph/graph.html?dataset=<dataset_id>

。

切勿在URL查询参数中包含JWT（例如，不要添加
```
token=
```
）。
仅在头中发送令牌，例如
```
Authorization: Bearer <token>
```
。

实用的URL参数：

play

、

linLog

、

scalingRatio

、

pointsOfInterestMax

、

pointSize

、

showCollections

、

info

、

collectionsGlobalNodeColor

、

collectionsGlobalEdgeColor

。

Collections URL Guidance

集合URL指导

```
collections
```
should be a URL encoded JSON value.
Remove raw whitespace before encoding.

Example:

collections=%5B%22teamA%22%2C%22fraud%22%5D

```
collections
```
应为URL编码的JSON值。
编码前移除原始空格。

示例：

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>

文档：

https://hub.graphistry.com/docs/api/experimental/rest/sessions/

。

起始URL：
```
graph.html?dataset=<dataset_id>
```
。

会话URL格式：

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.

仅使用文档化的端点；避免编造诸如
```
/api/v2/query
```
、
```
/api/v2/graph/query
```
、
```
/api/v2/render
```
、
```
/api/v2/graphql
```
之类的端点。
不要将SDK/GFQL行为表述为通用REST端点（例如，避免声称存在
```
/api/v2/gfql/query
```
）。
命名端点指导仅针对外部REST层面：
```
/functions/...
```
用于定义生命周期，
```
/run/...
```
用于执行。
对于没有专门文档页面的部署暴露路由（例如
```
/api/v2/share/link/
```
），明确标注不确定性并建议租户验证。
将凭证保存在环境变量中；切勿硬编码字面量。

Canonical Docs

官方文档

Auth: https://hub.graphistry.com/docs/api/1/rest/auth/
Upload: https://hub.graphistry.com/docs/api/2/rest/upload/
URL controls: https://hub.graphistry.com/docs/api/1/rest/url/
Sessions: https://hub.graphistry.com/docs/api/experimental/rest/sessions/
Health: https://hub.graphistry.com/docs/api/2/rest/health/
SSO + single-use gateway: https://hub.graphistry.com/docs/api/2/rest/sso/
GFQL UDF endpoints: https://hub.graphistry.com/docs/UDF/gfql-udf-api/
Python UDF endpoints: https://hub.graphistry.com/docs/UDF/py-udf-api/

认证：https://hub.graphistry.com/docs/api/1/rest/auth/
上传：https://hub.graphistry.com/docs/api/2/rest/upload/
URL控制：https://hub.graphistry.com/docs/api/1/rest/url/
会话：https://hub.graphistry.com/docs/api/experimental/rest/sessions/
健康检查：https://hub.graphistry.com/docs/api/2/rest/health/
SSO + 一次性网关：https://hub.graphistry.com/docs/api/2/rest/sso/
GFQL UDF端点：https://hub.graphistry.com/docs/UDF/gfql-udf-api/
Python UDF端点：https://hub.graphistry.com/docs/UDF/py-udf-api/