5 min read

Graphify Data Ingestion API

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

Graphify visualizes knowledge base (tPrivateKB) 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.

📦 Data storage and flow — tPrivateKB is the "real" store

⚠️ Most common misunderstanding: "I registered an issue but it doesn't show up in the graph" almost always means it was never ingested into tPrivateKB. tBlogGraphNodes/tBlogGraphEdges (the graph tables) hold no data of their own — they are a derived result rebuilt from tPrivateKB every time you call rebuild. There is no way to write to the graph tables directly; you must always go through tPrivateKB → rebuild.

[issue / knowledge source]
   │ ① Ingest: POST /api/giipKb (x-api-key: ak/sk)
   │   → writes 1 row to tPrivateKB (csn, refType, title, content, tags, extRefId)
   │   → refType='ISSUE' (external/own issue) or 'k-layer-daily' (K-Layer daily sync, see below)
   │   → idempotent upsert by extRefId (re-sending the same extRefId UPDATEs the existing row
   │     instead of creating a new one)
   ▼
  tPrivateKB  (the graph's "real" data store — the graph tables themselves are only a derived result)
   │ ② Rebuild: POST /api/giipGraphifyRebuild {csn} (x-api-key)
   │   → SP pApiGraphifyRebuildbyAk DELETEs that csn's tBlogGraphNodes/tBlogGraphEdges
   │     entirely, then regenerates them from tPrivateKB (ingest alone does not change the graph
   │     until rebuild is called)
   │   → DOC nodes (one per tPrivateKB row) + TAG nodes (only tags shared by 2+ documents; overly
   │     common tags are auto-excluded to prevent a hairball) + doc→tag edges
   │   → (new) node labels are auto-translated into the language configured for this csn
   │     (tCorp.cLang) before being saved
   ▼
 tBlogGraphNodes / tBlogGraphEdges  (csn-scoped; the tables the page actually reads)
   │ ③ Query: GET /api/giipGraphifyTenant?csn= (strict isolation, ak-authorized) or the
   │   page /graphify?csn=
   ▼
 3D knowledge graph visualization

Step 1 (ingest) alone shows nothing in the graph. You must also call step 2 (rebuild) for it to appear.
Rebuild always regenerates the entire graph from scratch. It does not incrementally build on the previous graph state — it redraws everything from the current contents of tPrivateKB. So deleting entries from tPrivateKB (or bulk-deleting by refType) removes them from the graph on the next rebuild.
Isolation: every step is scoped by csn (project boundary) and x-api-key (ak/sk authorization). You cannot reach another csn's tPrivateKB or graph.

K-Layer auto-ingest (already running, `refType='k-layer-daily'`)

The engineering know-how (K-Layer) accumulated during giip sessions is already ingested into tPrivateKB automatically every day — this is an existing production feature, not a new one.

Scheduler: giipdb/mgmt/run_klayer_daily_wiki.ps1 runs daily at 00:15 UTC via the Windows Task Scheduler job GIIP_Daily_KLayerWiki.
What it does: for every csn that has giip issues, it collects the previous day's issues and comments, summarizes them with MiniMax, and INSERTs the result into tPrivateKB via giipKb.
Field values: refType='k-layer-daily', tags='k-layer-wiki,daily', title='K-Layer Wiki {csn} - {yyyy-MM-dd}'.
Masking: sensitive information is double-masked by giipdb/mgmt/lib/Mask-SensitiveInfo.ps1 before being stored.
How it appears in the graph: like any other tPrivateKB row, these entries are absorbed as DOC nodes on the next rebuild. The shared tags k-layer-wiki and daily become TAG nodes, so K-Layer documents accumulated over time naturally cluster together by date.
Filter or bulk-delete by refType='k-layer-daily' to scope operations to K-Layer entries (see the refType row in §1).

csn language-based auto-translation (new)

When giipGraphifyRebuild is called, node labels are automatically translated into the language configured for that csn's project (tCorp.cLang, e.g. ko-KR, en-US — an existing value already settable on the project management screen) before being saved.

When it happens: the raw tPrivateKB data (title/content) is stored as-is regardless of language; the cLang value for that csn is read and applied to translate node labels at rebuild time.
User-facing summary: change the csn's language setting (cLang) on the project management screen, and starting from the next giipGraphifyRebuild call, the language of the text shown in the graph changes. You do not need to modify the original tPrivateKB data.
The same tPrivateKB data can show nodes in different languages across csns that have different cLang settings.
Translation is redone on every rebuild (no caching/accumulation) — the original title/content is always the source of truth.

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 tPrivateKB (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)

Response

{ "success": true, "nodes": 838, "edges": 11, "docNodes": 835, "tagNodes": 3, "message": "Graph rebuilt (tag-bipartite)" }

Troubleshooting

Symptom	Cause	Fix
Graph looks empty	Rebuild not called / wrong csn	Call `giipGraphifyRebuild`, check `?csn=`
Many nodes but almost no edges	Tags are unique (DF=1) or generic (too frequent)	Re-ingest with tags shared by 2–50 entries, then rebuild
Same entry duplicated	`extRefId` not used	Include `extRefId` for idempotent ingest
401/403	No key / different csn	Use a valid `x-api-key` and your own `csn`

Metadata

Source file: giipv3/public/help/api-graphify.en.md
raw source path: /help/api-graphify.en.md
Related APIs: giipfaw/giipKb, giipfaw/giipGraphifyRebuild
Related page: /[locale]/graphify

← PreviousSystem Management API Next →KVS (Key-Value Store) API

Learn more about the product →