API

Skapa nycklar för programmatisk åtkomst och anropa sedan /v1/public/traces med x-api-key-headern.

API-nycklar

Nycklar börjar med vk_. Den fullständiga hemligheten visas endast vid skapande. Användning mäts per nyckel (standard 1 000 anrop/månad).

Laddar API-nycklar…

API-referens

Programmatisk åtkomst till leveranskedjespårningar. Alla publika endpoints ligger under https://vein-api-production.up.railway.app/v1/public/traces och kräver en API-nyckel. Interaktiv Swagger-dokumentation finns på /docs.

Bas-URL och headers

Fält	Typ	Obligatorisk	Beskrivning
`Base URL`	string	Ja	https://vein-api-production.up.railway.app/v1 — all paths below are relative to this prefix.
`Content-Type`	header	Ja	application/json on POST requests.
`x-api-key`	header	Ja	Your secret key (vk_…). Also accepted as Authorization: Bearer vk_…

POST/public/traces

Skapa en spårning

Kör en rot-uppdelning av leveranskedjan för en produkt, komponent eller tjänst.

Request body

Fält	Typ	Obligatorisk	Beskrivning
`query`	string	Ja	What to trace, e.g. "Electric Vehicle" or "NVDA GPU".
`workspaceId`	string	Nej	Optional workspace to assign the trace to. Ignored if the API key is workspace-scoped.

Exempel

curl -X POST "https://vein-api-production.up.railway.app/v1/public/traces" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_YOUR_KEY" \
  -d '{"query": "Electric Vehicle"}'

Svar — 201 / 200

Returns a full trace object (same shape as GET). Root expansion can take several seconds.

{
  "id": "clx…",
  "publicId": "a1b2c3d4",
  "query": "Electric Vehicle",
  "rootId": "n_1",
  "nodes": {
    "n_1": {
      "id": "n_1",
      "name": "Electric Vehicle",
      "depth": 0,
      "parent": null,
      "children": ["n_2", "n_3"],
      "expanded": true,
      "category": "Product",
      "summary": "Battery-electric road vehicle…",
      "is_tradeable": false,
      "tickers": [],
      "criticality": "",
      "is_chokepoint": false,
      "chokepoint_reason": "",
      "sources": ["https://…"]
    },
    "n_2": {
      "id": "n_2",
      "name": "Lithium-ion battery pack",
      "depth": 1,
      "parent": "n_1",
      "children": [],
      "expanded": false,
      "category": "Component",
      "summary": "High-voltage traction battery",
      "is_tradeable": true,
      "tickers": [
        {
          "symbol": "TSLA",
          "name": "Tesla Inc",
          "type": "stock",
          "trend": "Vertically integrated pack production",
          "market_position": "Leading EV OEM"
        }
      ],
      "criticality": "high",
      "is_chokepoint": false,
      "chokepoint_reason": "",
      "sources": []
    }
  },
  "userId": "usr_…",
  "workspaceId": null,
  "createdAt": "2026-06-25T12:00:00.000Z",
  "updatedAt": "2026-06-25T12:00:00.000Z"
}

GET/public/traces/:id

Hämta en spårning

Hämta en spårning du äger (eller i en arbetsyta din nyckel har åtkomst till). :id accepterar internt id eller delningsbart publicId.

Exempel

curl "https://vein-api-production.up.railway.app/v1/public/traces/a1b2c3d4" \
  -H "x-api-key: vk_YOUR_KEY"

Svar — 200

Same trace object as create. Returns 404 if not found or not accessible.

POST/public/traces/:id/expand

Expandera en nod

Dela upp en oexpanderad nod ett steg djupare. Välj nodeId från nodes[nodeId] där expanded är false.

Request body

Fält	Typ	Obligatorisk	Beskrivning
`nodeId`	string	Ja	Key from the trace nodes map, e.g. "n_2".

Exempel

curl -X POST "https://vein-api-production.up.railway.app/v1/public/traces/clx…/expand" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_YOUR_KEY" \
  -d '{"nodeId": "n_2"}'

Svar — 200

Uppdaterad spårning med noden markerad expanded: true och nya barnnoder tillagda. Att expandera samma nod igen returnerar oförändrad spårning.

Nodfält

Fält	Typ	Obligatorisk	Beskrivning
`id`	string	Nej	Stable node id within the trace graph.
`name`	string	Nej	Supply-chain node label.
`depth`	number	Nej	0 = root; increases downstream.
`parent`	string \| null	Nej	Parent node id.
`children`	string[]	Nej	Child node ids (may be unexpanded stubs).
`expanded`	boolean	Nej	Whether this node has been expanded.
`category`	string	Nej	e.g. Component, Raw Material, Commodity.
`summary`	string	Nej	One-sentence description.
`is_tradeable`	boolean	Nej	Whether public tickers are relevant.
`tickers`	Ticker[]	Nej	Up to 4 symbols with trend and market_position.
`criticality`	high \| medium \| low \| ""	Nej	How irreplaceable to parent.
`is_chokepoint`	boolean	Nej	Hidden high-impact dependency flag.
`chokepoint_reason`	string	Nej	Set when is_chokepoint is true.
`sources`	string[]	Nej	Optional https URLs used for grounding.

Fel och gränser

Fält	Typ	Obligatorisk	Beskrivning
`401 Unauthorized`	—	Nej	Missing, invalid, or revoked API key.
`403 Forbidden`	—	Nej	Monthly key limit exceeded, plan depth limit, or unavailable plan feature.
`404 Not Found`	—	Nej	Trace or node does not exist, or you lack access.
`429 Too Many Requests`	—	Nej	Rate limit on unauthenticated web endpoints (not API-key routes).

Varje API-anrop ökar nyckelns månadsanvändning (standard 1 000 anrop/månad). Arbetsyta-kopplade nycklar tilldelar automatiskt nya spårningar till den arbetsytan.

Typiskt arbetsflöde

# 1. Create root trace
TRACE=$(curl -s -X POST "https://vein-api-production.up.railway.app/v1/public/traces" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_YOUR_KEY" \
  -d '{"query": "Data Center"}')

ID=$(echo "$TRACE" | jq -r '.id')
NODE=$(echo "$TRACE" | jq -r '.nodes | to_entries[] | select(.value.expanded == false) | .key' | head -1)

# 2. Expand first unexpanded child
curl -s -X POST "https://vein-api-production.up.railway.app/v1/public/traces/$ID/expand" \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_YOUR_KEY" \
  -d "{\"nodeId\": \"$NODE\"}" | jq '.nodes | keys | length'