API Reference

Base URL: https://dkeforge.com/v1

Authentication

All API requests (except registration) require a Bearer token:

Authorization: Bearer fga_your_api_key_here

Get your API key by registering for the beta.

Register

POST /v1/register

Create a new account. Returns an API key (shown once). No authentication required.

Field	Type	Description
name	string	Your name required
email	string	Your email (unique) required

curl -X POST https://dkeforge.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com"}'

Response (201):

{
  "id": "a1b2c3d4e5f6a7b8",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tier": "cycle",
  "api_key": "fga_0123456789abcdef...",
  "message": "Welcome to DKE-Forge beta! Save your API key..."
}

Verify Key

POST /v1/auth/verify

Check if your API key is valid and see your account details.

curl -X POST https://dkeforge.com/v1/auth/verify \
  -H "Authorization: Bearer fga_your_key"

Code Oracle (Graph Queries)

Structural queries against your code graph. Available to all tiers.

Graph Stats

GET /v1/graph/stats

Node and edge counts, type breakdown, thermal zone distribution.

curl https://dkeforge.com/v1/graph/stats \
  -H "Authorization: Bearer fga_your_key"

Query Function

GET /v1/graph/function/:name

Look up a function by name. Returns node details including properties, temperature, and confidence.

curl https://dkeforge.com/v1/graph/function/handleRegister \
  -H "Authorization: Bearer fga_your_key"

Callers Of

GET /v1/graph/callers/:name

Functions that call the named function. Optional ?depth=N (default 2).

curl "https://dkeforge.com/v1/graph/callers/authenticate?depth=3" \
  -H "Authorization: Bearer fga_your_key"

Callees Of

GET /v1/graph/callees/:name

Functions called by the named function. Optional ?depth=N (default 2).

curl "https://dkeforge.com/v1/graph/callees/main?depth=2" \
  -H "Authorization: Bearer fga_your_key"

Dependencies

GET /v1/graph/depends/:name

Files and modules that the named entity depends on (DependsOn, Includes, UsesType edges).

curl https://dkeforge.com/v1/graph/depends/graph.cpp \
  -H "Authorization: Bearer fga_your_key"

Impact Analysis

GET /v1/graph/impact/:name

What breaks if you change this function? Returns directly affected, transitively affected, and test cases that need re-running. Optional ?change_type=modify|remove|rename.

curl "https://dkeforge.com/v1/graph/impact/ForgeGraph?change_type=modify" \
  -H "Authorization: Bearer fga_your_key"

Response includes:

{
  "changed": { ... },
  "change_type": "modify",
  "directly_affected": [ ... ],
  "transitively_affected": [ ... ],
  "test_cases_affected": [ ... ],
  "files_to_update": [ "graph.cpp", "store.cpp" ]
}

Rules

GET /v1/graph/rules

List all registered coding rules (naming conventions, complexity limits, etc.).

Check Rules

POST /v1/graph/check

Check a function against all rules. Returns violations.

Field	Type	Description
name	string	Function name required

Patterns

GET /v1/graph/patterns

List learned structural patterns in your graph.

Pattern Detail

GET /v1/graph/pattern/:id

Pattern details including exemplar functions and edge-profile centroid.

Forge Envelopes

The Cartographer assembles a complete context envelope for a function.

POST /v1/envelope

Assemble a Cartographer envelope. Returns both structured JSON and serialized text ready for LLM consumption.

Field	Type	Description
name	string	Target function name required
task	string	Task description required
max_context	int	Max context nodes (optional, default 50)

curl -X POST https://dkeforge.com/v1/envelope \
  -H "Authorization: Bearer fga_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "authenticate",
    "task": "Add rate limiting by IP address"
  }'

Code Generation (Full Forge Cycle)

The complete pipeline: Cartographer → Scribe (your LLM) → Auditor. Requires your own LLM API key.

POST /v1/generate

Run the full Forge Cycle. Assembles context, calls your LLM, audits the result, retries on failure.

Field	Type	Description
name	string	Target function name required
task	string	Task description required
llm_provider	string	`"anthropic"` or `"openai"` required
llm_key	string	Your LLM API key required
model	string	Model override (default: claude-sonnet-4-20250514 / gpt-4o)
retries	int	Max retry attempts (default 3)
build_command	string	Custom build command for compile check

curl -X POST https://dkeforge.com/v1/generate \
  -H "Authorization: Bearer fga_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "handleRegister",
    "task": "Add CAPTCHA verification before registration",
    "llm_provider": "anthropic",
    "llm_key": "sk-ant-api03-your-key-here"
  }'

Response:

{
  "accepted": true,
  "attempts": 1,
  "total_ms": 3200,
  "provider": "anthropic/claude-sonnet-4-20250514",
  "target": "handleRegister",
  "task": "Add CAPTCHA verification...",
  "code": "static void handleRegister(...) { ... }",
  "attempt_details": [ ... ]
}

Scan Repository

POST /v1/scan

Ingest a repository into your code graph. Currently supports C++ files.

Field	Type	Description
path	string	Path to repository on server required
commit	string	Git commit SHA (default: HEAD)

Bring Your Own Key

Forge is model-agnostic. The graph intelligence is deterministic — only the code generation step uses an LLM. You supply your own API key with each generate request.

Supported providers:

Provider	llm_provider value	Default model
Anthropic	`"anthropic"`	claude-sonnet-4-20250514
OpenAI	`"openai"`	gpt-4o

Your LLM key is sent over TLS, used for a single API call, and never stored. It exists only in memory for the duration of the request.

Error Format

All errors return JSON with an error field:

{
  "error": "Missing or invalid Authorization header"
}

Status	Meaning
400	Bad request (missing/invalid parameters)
401	Missing or invalid API key
403	Insufficient tier or admin access required
404	Resource not found (function, pattern, tenant)
409	Conflict (duplicate email)
429	Rate limit exceeded
500	Internal server error

Health Check

GET /health

No authentication required. Returns server status and version.

curl https://dkeforge.com/health

{"status": "ok", "version": "0.1.0"}