API Reference

The Knowledge API is a REST API for managing decisions, invariants, rules, and the compliance workflow. All endpoints require authentication via Bearer token.

Base URL: https://api.asplenz.com/api/v1

Authentication

All requests must include an API key:

Authorization: Bearer kn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Core Entities

Scopes

Decisions

Create request:

{
  "decision": "Use PostgreSQL for transactional data",
  "context": "Evaluated PostgreSQL, DynamoDB, CockroachDB",
  "reasoning": "ACID guarantees without distributed complexity",
  "author": "sarah.chen",
  "author_type": "human",
  "tags": ["database", "infrastructure"],
  "namespace": "payments"
}

Invariants

Create request:

{
  "constraint": "All public endpoints require authentication",
  "rationale": "Security baseline",
  "requires_approval": true,
  "author": "security-team",
  "author_type": "human"
}

Rules

Create request:

{
  "directive": "All PRs must be reviewed before merging",
  "severity": "MANDATORY",
  "author": "tech-lead",
  "author_type": "human"
}

Overrides

Create request:

{
  "target_id": "inv-8a3f1b2c4d5e",
  "override_type": "temporary",
  "justification": "Health endpoint must be public for load balancer",
  "conditions": "Only /health and /ready endpoints",
  "approved_by": "tech-lead",
  "expires_at": "2025-06-01T00:00:00Z"
}

Search and Compliance

Search

POST /search

{
  "query": "PostgreSQL",
  "scope_id": "scp-XXXX",
  "entry_type": "decision",
  "limit": 10
}

Searches across decision, context, reasoning (decisions), constraint, rationale (invariants), and directive (rules).

Compliance Check

POST /check

{
  "scope_id": "scp-XXXX",
  "intended_action": "Deploy on Friday evening without review"
}

Returns:

{
  "conflicts": [
    {
      "entry_id": "inv-8a3f1b2c4d5e",
      "entry_type": "invariant",
      "severity": "blocking",
      "requires_approval": true
    }
  ],
  "overridden": []
}

Resolve Normative State

GET /scopes/{scope_id}/resolve

Returns the complete normative state: all active invariants, rules, and overrides, plus a normative_hash for change detection.

References and Events

References

Create request:

{
  "entry_id": "inv-8a3f1b2c4d5e",
  "context_type": "pull_request",
  "context_ref": "github:acme/api/pull_request#42",
  "status": "followed",
  "author": "claude-agent",
  "author_type": "agent"
}

Status values: cited, followed, verified, diverged (requires reason).

Events

Approval Workflow

Request approval:

{
  "trigger_id": "inv-8a3f1b2c4d5e",
  "trigger_type": "invariant",
  "intended_action": "Add public health endpoint",
  "justification": "Load balancer needs unauthenticated health check",
  "requested_by": "deploy-bot",
  "requested_by_type": "agent"
}

Decide:

{
  "decision": "approved",
  "comment": "Approved for health/ready endpoints only",
  "decided_by": "tech-lead"
}

If approved for an invariant/rule with requires_approval, an override is auto-created.

Webhook notifications

Instead of polling GET /approvals/{id}, subscribers can receive ECDSA-signed webhook POSTs when approvals are requested or resolved.

Create a subscription:

{
  "url": "https://your-service.example.com/webhook",
  "events": ["approval.requested", "approval.resolved"],
  "description": "Notify Slack bot on approvals"
}

Verify by reconstructing the message ({timestamp}.{raw_body}) and checking against the public key from /.well-known/webhook-key.

Links

Create link:

{
  "from_id": "dec-abc123",
  "from_type": "decision",
  "to_id": "inv-def456",
  "to_type": "invariant",
  "relation": "creates"
}

Relation types: depends_on, supersedes, contradicts, in_tension_with, creates.

Tenants and Namespaces

Tenants

Namespaces

Namespaces support hierarchy: payments → payments/stripe → max depth 2 levels below root.

Error Responses

{
  "detail": "Not authorized: missing permission manage_rules"
}

Interactive Documentation

When the API is running, visit https://api.asplenz.com/docs for the auto-generated Swagger UI with try-it-out capability.