Graphify Data Ingestion API

🔌 Go to Graphify →](/en/graphify)

Graphify visualizes knowledge base (tKB) entries as a 3D knowledge graph. This document explains how to add data via API and how to call it so the information displays well.

The data flow has 2 steps: ① ingest entries (giipKb) → ② rebuild the graph (giipGraphifyRebuild). You must call rebuild for new entries to appear in the graph.

Quick start (3 steps)

# 1) Ingest an entry — giipKb POST (host: giipfaw.azurewebsites.net)
curl -X POST "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47,"title":"OAuth callback 500","content":"## Cause\ntoken exchange timeout","tags":"auth,oauth,timeout","refType":"ISSUE","extRefId":"ISSUE-1001"}'

# 2) Rebuild the graph — giipGraphifyRebuild POST
curl -X POST "https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47}'

# 3) Verify — open https://<host>/en/graphify?csn=47 in a browser

The auth key (x-api-key) is a logged-in user's AK or a project-scoped SK. A key can only add/rebuild data within its own csn.

⭐ How to make the information display well (key)

Graphify is a tag-bipartite graph: documents are connected through "shared tags" (tags are first-class nodes). So how you tag entries determines graph quality.

Good tags (create connections)

Use meaningful tags shared by 2–50 entries, e.g. auth, billing, timeout, payment, login.
Entries on the same topic cluster around shared tag nodes.

Tags to avoid

Bad pattern	Why	Result
Unique-per-entry tags (e.g. a filename `report_2026_01.md`)	No entry shares it (DF=1)	Connects nothing → isolated node
Generic tags on almost every entry (e.g. `doc`, `sync`, `general`)	Document frequency too high	Auto-filtered out of edges (prevents hairball)

Rule of thumb: tags that are neither too common nor too unique create good connections. By default, only tags with document frequency (DF) between 2 and 50 within a csn become tag nodes.

Other display tips

title becomes the node label — keep it short and clear.
content is rendered as the detail popup body (markdown) on node click.
extRefId is the external system's entry ID — re-syncing updates instead of duplicating (idempotent).
Rebuild is required: adding entries without rebuilding leaves the graph unchanged. Call giipGraphifyRebuild once after a batch ingest.

Details · API reference

1) Ingest — `giipKb`

POST https://giipfaw.azurewebsites.net/api/giipKb · header x-api-key: <ak/sk>

Field	Type	Req	Description
`csn`	int	✅	Project number; must match key scope (example: 47)
`title`	string(200)	✅	Node label
`content`	string		Node detail body (markdown allowed)
`tags`	string(500)		Comma-separated tags. Core of connectivity (see "Good tags")
`refType`	string(50)	✅	Entry type, e.g. `ISSUE`, `GENERAL`, `GUIDE`
`extRefId`	string(100)		External entry ID (idempotent upsert key); updates on re-sync

Response

{ "success": true, "kbSn": 844, "message": "KB entry created successfully" }

Sending the same extRefId again:

{ "success": true, "kbSn": 844, "message": "KB entry updated (idempotent)" }

PowerShell example

$headers = @{ "x-api-key"="<ak/sk>"; "Content-Type"="application/json; charset=utf-8" }
$body = @{ csn=47; title="Payment delay"; content="## Symptom`n5s approval delay"; tags="payment,timeout"; refType="ISSUE"; extRefId="ISSUE-1002" } | ConvertTo-Json
Invoke-RestMethod -Uri "https://giipfaw.azurewebsites.net/api/giipKb" -Method POST -Headers $headers -Body ([Text.Encoding]::UTF8.GetBytes($body))

2) Rebuild — `giipGraphifyRebuild`

POST https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild · header x-api-key: <ak/sk>

Rebuilds the graph for a csn from tKB (DOC nodes + distinctive TAG nodes + doc→tag edges).

Field	Type	Req	Description
`csn`	int	✅	Project to rebuild
`maxTagDF`	int		Generic-tag cut (max document frequency, default 50); tags more common than this are excluded
`maxNodes`	int		DOC node safety cap (default 20000)