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, /api/register, and /api/auth/config) require authentication.

API Key

Use a Bearer token with your API key:

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

JWT (Auth0)

Use a Bearer token with an Auth0 JWT. For multi-org users, specify the organization:

curl -H "Authorization: Bearer <jwt>" \
  -H "X-Organization-Id: <org-uuid>" \
  https://api.intelligence.apart.tech/api/nodes/types

If you belong to a single organization, the X-Organization-Id header is optional.

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.

Auth & User Management

GET /api/auth/config

Returns Auth0 configuration for the CLI device flow. No authentication required.

curl https://api.intelligence.apart.tech/api/auth/config
# → { "domain": "...", "clientId": "...", "audience": "..." }

POST /api/auth/callback

Exchange an Auth0 access token for user info and organization memberships. No authentication required.

curl -X POST https://api.intelligence.apart.tech/api/auth/callback \
  -H "Content-Type: application/json" \
  -d '{"token": "<auth0-access-token>"}'

GET /api/auth/me

Get current user info and memberships. Requires JWT authentication.

POST /api/auth/claim

Claim ownership of an organization. Requires API key authentication and an Auth0 JWT in the X-Auth-Token header.

Members

GET /api/members

List members of the current organization. Requires JWT authentication.

PATCH /api/members/:id

Update a member's role. Requires owner role. Body: { "role": "owner|admin|member" }

DELETE /api/members/:id

Remove a member. Requires owner role. The last owner cannot be removed.

Invites

POST /api/invites

Create an invite. Requires admin or owner role.

curl -X POST https://api.intelligence.apart.tech/api/invites \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Organization-Id: <org-uuid>" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "role": "member"}'

GET /api/invites

List pending invites for the current organization. Requires admin or owner role.

DELETE /api/invites/:id

Revoke a pending invite. Requires admin or owner role.

POST /api/invites/accept

Accept an invite. Requires JWT authentication. Body: { "token": "<invite-token>" }

Note

All endpoints return JSON. Errors return { "error": "message" } with appropriate HTTP status codes (400 for validation, 404 for not found, 500 for server errors).