API Reference

The Apart Intelligence REST API provides programmatic access to all knowledge graph operations. Built on the Hono web framework and deployed on Google Cloud Run.

Base URL: https://api.intelligence.apart.tech

Authentication

All endpoints (except /api/health and /api/register) require authentication:

# Via Authorization header
curl -H "Authorization: Bearer <api-key>" https://api.intelligence.apart.tech/api/nodes/types

# Or via X-API-Key header
curl -H "X-API-Key: <api-key>" https://api.intelligence.apart.tech/api/nodes/types

BYOK (Bring Your Own Key)

Override the embedding provider per-request:

curl -X POST https://api.intelligence.apart.tech/api/nodes \
  -H "Authorization: Bearer <api-key>" \
  -H "X-Embedding-Provider: voyage" \
  -H "X-Embedding-Key: <voyage-key>" \
  -H "X-Embedding-Model: voyage-code-3" \
  -H "Content-Type: application/json" \
  -d '{"type": "note", "title": "...", "content": "..."}'

Nodes

POST /api/nodes

Create a knowledge node. Automatically embeds the content.

{
  "type": "architecture",
  "title": "API Gateway Design",
  "content": "## Overview\n...",
  "metadata": { "team": "platform" },
  "domainId": "uuid",          // optional
  "status": "draft",           // optional, default: draft
  "createdBy": "api"           // optional
}

GET /api/nodes/:id

Retrieve a node with its edges. Supports short ID prefixes.

PATCH /api/nodes/:id

Update a node. Re-embeds automatically if title or content changes.

{
  "title": "Updated Title",    // optional
  "content": "New content",    // optional
  "metadata": {},              // optional
  "type": "note",              // optional
  "domainId": "uuid"           // optional
}

DELETE /api/nodes/:id

Delete a node and all its edges.

PATCH /api/nodes/:id/status

{ "status": "approved" }    // draft | reviewed | approved | archived

GET /api/nodes/:id/neighborhood

Get a node with its neighbors via graph traversal. Query param: ?depth=1 (traversal depth, default 1).

Returns the node, its neighbors, and connecting edges.

GET /api/nodes/drafts

List draft nodes. Query param: ?limit=50

GET /api/nodes/types

List all node types with usage counts.

Search & Context

POST /api/search

Hybrid semantic + keyword search.

{
  "query": "deployment process",
  "limit": 10,                 // optional
  "types": ["process"],        // optional
  "statuses": ["approved"],    // optional
  "includeDrafts": false,      // optional
  "domainIds": ["uuid"],       // optional
  "workspace": "my-workspace"  // optional — resolve workspace filters
}

POST /api/context

Assemble a context package via search + graph traversal.

{
  "query": "incident response",
  "maxDepth": 2,               // optional
  "maxNodes": 50,              // optional
  "types": ["process"],        // optional
  "domainIds": ["uuid"],       // optional
  "workspace": "my-workspace"  // optional — resolve workspace filters
}

Edges

POST /api/edges

{
  "sourceNodeId": "uuid",
  "targetNodeId": "uuid",
  "relationshipType": "depends-on",
  "weight": 1.0,              // optional
  "metadata": {}               // optional
}

GET /api/edges/types

List all relationship types with usage counts.

DELETE /api/edges/:id

Code Mapping

POST /api/map

Upload source code analysis results. Creates module + chunk nodes, import edges, contains edges, and optionally connects to a root node.

{
  "analyses": [...],           // FileAnalysis array from CLI
  "projectName": "my-service",
  "createdBy": "tc-map",       // optional
  "domainId": "uuid",          // optional
  "rootNodeId": "uuid",        // optional — connect to root
  "status": "approved",        // optional
  "skipImportEdges": false,    // optional — for batched uploads
  "skipStaleCleanup": false    // optional — for batched uploads
}

POST /api/map/import-edges

Create import edges after batched uploads.

POST /api/map/cleanup

Remove stale chunks after batched uploads.

Domains

GET /api/domains

List the domain taxonomy tree.

GET /api/domains/:slug

Get a domain by its slug.

POST /api/domains/seed

Populate the default domain taxonomy.

POST /api/domains/resolve

Resolve an array of domain slugs to their IDs.

{ "slugs": ["engineering", "platform"] }

Workspaces

GET /api/workspaces

List all workspaces.

POST /api/workspaces

Create a workspace.

GET /api/workspaces/:slug

Get a workspace by slug.

PATCH /api/workspaces/:id

Update a workspace.

DELETE /api/workspaces/:id

Delete a workspace.

POST /api/workspaces/:slug/resolve

Resolve a workspace slug into its domain/type filters for use with search and context.

GET /api/workspaces/:slug/export

Export a workspace as markdown.

Graph Analysis

GET /api/graph

Graph visualization data. Query param: ?status=approved (comma-separated).

Graph Cleaning

GET /api/cleaning/health

Comprehensive graph health report. Query param: ?staleDays=90

GET /api/cleaning/orphans

Find unconnected nodes.

GET /api/cleaning/duplicates

Find near-duplicate nodes by embedding similarity. Query params: ?threshold=0.95&limit=50

GET /api/cleaning/islands

Find disconnected subgraphs. Query params: ?bridges=true&maxBridges=10 to include bridge suggestions.

GET /api/cleaning/suggest-links

Suggest new edges based on embedding similarity. Query params: ?nodeId=uuid&minSimilarity=0.8&limit=10. Omit nodeId for global suggestions.

GET /api/cleaning/validate

Validate edge integrity (self-loops, duplicates, rare types). Query params: ?lowRelevance=0.3&rareType=1

GET /api/cleaning/normalize

Analyze relationship types for potential normalization. Query param: ?minSimilarity=0.7

POST /api/cleaning/normalize/apply

Rename a relationship type across all edges.

{ "fromType": "depends_on", "toType": "depends-on" }

Embedding Configuration

GET /api/org/embeddings

Get the organization's embedding provider configuration.

POST /api/org/embeddings

Set the embedding provider for the organization.

{
  "provider": "voyage",
  "apiKey": "<api-key>",
  "model": "voyage-code-3",
  "dimensions": 1024
}

POST /api/org/embeddings/test

Test the configured embedding provider. Returns provider, model, dimensions, and latency.

DELETE /api/org/embeddings

Remove the organization's embedding configuration (reverts to default).

Re-embedding

POST /api/re-embed

Re-embed existing nodes (e.g. after changing embedding provider).

{
  "type": "architecture",      // optional — filter by node type
  "limit": 100,                // optional — max nodes to process
  "dryRun": true               // optional — count without re-embedding
}

PII Protection

GET /api/org/pii

Get the organization's PII policy.

POST /api/org/pii

Set PII policy for the organization.

{
  "mode": "encrypt",              // "encrypt" | "detect-warn" | "disabled"
  "allowedPiiTypes": ["email"],   // optional — PII types to allow unencrypted
  "allowBypass": true             // optional — allow per-request bypass
}

DELETE /api/org/pii

Remove PII policy. Warning: encrypted PII becomes permanently unrecoverable.

POST /api/org/pii/test

Scan text for PII without storing anything.

{
  "text": "Contact john@example.com or call (555) 123-4567"
}

GET /api/nodes/:id?decrypt=true

Retrieve a node with encrypted PII fields decrypted. Requires the organization to have a PII encryption key configured.

X-Pii-Bypass Header

Pass X-Pii-Bypass: true on POST /api/nodes or PATCH /api/nodes/:id to skip PII encryption for that request. Requires allowBypass: true in the org PII policy.