Knowledge & Search API

The knowledge system provides semantic search across project content and knowledge pattern mining from execution history.

Semantic Search

Search across project requirements, knowledge patterns, and execution nodes using vector similarity.

GET /api/v1/projects/{project_id}/search?q=user+authentication
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Default	Description
q	string	required	Search query text
source_type	string	all	Filter by requirement, knowledge_pattern, or execution_node
limit	int	10	Max results (1–50)
threshold	float	0.5	Minimum similarity score (0–1)

Response 200 OK

{
  "query": "user authentication",
  "results": [
    {
      "source_type": "requirement",
      "source_id": "uuid",
      "chunk_index": 0,
      "similarity": 0.87,
      "content_preview": "Implement JWT-based authentication..."
    }
  ],
  "total": 3
}

Find Similar Items

Find items similar to a specific source document.

GET /api/v1/projects/{project_id}/search/similar/requirement/{requirement_id}
Authorization: Bearer <token>

Knowledge Patterns

Knowledge patterns are reusable insights extracted from execution history — bug fixes, successful strategies, anti-patterns, and code patterns.

List Patterns

GET /api/v1/knowledge-patterns?project_id={project_id}
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
project_id	UUID	Filter by project
pattern_type	string	Filter by bug_fix, success, anti_pattern, code_pattern
status_filter	string	Filter by active, draft, deprecated

Create Pattern

POST /api/v1/knowledge-patterns
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "uuid",
  "pattern_type": "bug_fix",
  "title": "Fix N+1 query in user listing",
  "description": "SQLAlchemy lazy loading causes N+1 queries",
  "trigger_conditions": ["user listing endpoint", "pagination"],
  "resolution_steps": ["Use joinedload() for relationships"],
  "applicable_contexts": ["fastapi", "sqlalchemy"],
  "confidence": 0.9
}

Update Pattern

PUT /api/v1/knowledge-patterns/{pattern_id}
Authorization: Bearer <token>

Delete Pattern

Requires admin role.

DELETE /api/v1/knowledge-patterns/{pattern_id}
Authorization: Bearer <token>

Activate / Deprecate

Move a pattern from draft to active, or mark as deprecated.

POST /api/v1/knowledge-patterns/{pattern_id}/activate
POST /api/v1/knowledge-patterns/{pattern_id}/deprecate
Authorization: Bearer <token>

Extract from Execution

Automatically extract knowledge patterns from a completed execution graph.

POST /api/v1/executions/{graph_id}/extract-patterns
Authorization: Bearer <token>

Pattern Recommendations

Get recommended patterns for a project, sorted by usage frequency and confidence.

GET /api/v1/projects/{project_id}/knowledge/recommend?limit=5
Authorization: Bearer <token>

Bugfix Report

Aggregated summary of pattern distribution and most-used patterns.

GET /api/v1/projects/{project_id}/knowledge/bugfix-report
Authorization: Bearer <token>

Response 200 OK

{
  "summary": [
    { "pattern_type": "bug_fix", "count": 12, "avg_confidence": 0.85, "total_usage": 45 }
  ],
  "top_patterns": [
    { "id": "uuid", "title": "Fix N+1 query", "usage_count": 8, "confidence": 0.92 }
  ]
}

Autonomy Configuration

Control the level of automation for AI agent execution.

Get Autonomy Config

GET /api/v1/projects/{project_id}/autonomy
Authorization: Bearer <token>

Update Autonomy Settings

Requires admin role.

PUT /api/v1/projects/{project_id}/autonomy?level=1&auto_approve_threshold=8.0&spot_check_ratio=0.2
Authorization: Bearer <token>

Autonomy Levels

Level	Behavior
L0	All gates require human approval
L1	Auto-approve gates above score threshold
L2	Auto-approve with spot-check sampling