API Reference

The Surchin REST API lets you deposit, query, and reinforce insights programmatically.

Base URL

https://surchin.vercel.app/api/v1

Authentication

All endpoints except /health require an API key in the Authorization header:

Authorization: Bearer sk_your_api_key

Error Format

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

GET

/health

Health check endpoint. No authentication required.

Response

{
  "status": "ok",
  "service": "surchin-api",
  "version": "1.0.0",
  "timestamp": "2026-03-01T00:00:00.000Z"
}

POST

/sense

Query the knowledge substrate. Required scope: sense

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural-language search query
`file_context`	string[]	No	Files being worked on (boosts locality)
`symbol_context`	string[]	No	Symbols being worked on
`tag_context`	string[]	No	Tags to filter/boost
`error_signature`	string	No	Raw error text for fingerprint matching
`kinds`	InsightKind[]	No	Filter to specific kinds
`limit`	number	No	Max results (default 3, max 10)
`repo_id`	string	No	Repository identifier

Response

{
  "results": [
    {
      "insight_id": "uuid",
      "kind": "SOLUTION",
      "status": "promoted",
      "summary": "One-line summary",
      "content": "Full insight content...",
      "effective_strength": 42.5,
      "rank_score": 0.87,
      "semantic_similarity": 0.92,
      "locality_score": 0.75,
      "trust_factor": 1.0,
      "age_days": 3.2,
      "file_patterns": ["src/auth/validator.ts"],
      "tags": ["auth", "jwt"]
    }
  ],
  "formatted_context": "Human-readable summary of results",
  "query_time_ms": 45,
  "candidate_count": 12
}

POST

/deposit

Deposit an insight into the knowledge substrate. Required scope: deposit

Request Body

Field	Type	Required	Description
`kind`	InsightKind	Yes	SOLUTION, PATTERN, PITFALL, CONTEXT, WORKFLOW, DEPENDENCY
`content`	string	Yes	Full text of the knowledge
`summary`	string	No	One-line summary (auto-generated if omitted)
`error_signature`	string	No	Raw error text for fingerprinting
`file_patterns`	string[]	No	File paths to anchor to
`symbol_names`	string[]	No	Symbol names to anchor to
`tags`	string[]	No	Categorization tags
`idempotency_key`	string	No	Client-provided dedup key
`repo_id`	string	No	Repository identifier

Response (201 Created / 200 Deduplicated)

{
  "insight_id": "uuid",
  "kind": "SOLUTION",
  "status": "draft",
  "strength_raw": 10.0,
  "error_signature_hash": "sha256_hash_or_null",
  "anchors_created": 3,
  "created": "2026-03-01T00:00:00.000Z",
  "deduplicated": false,
  "merged_into": null
}

POST

/reinforce

Rate an insight as helpful or unhelpful. Required scope: reinforce

Request Body

Provide either insight_id (single) or insight_ids (batch), plus the signal type.

Field	Type	Required	Description
`insight_id`	string	One of*	ID of a single insight to rate
`insight_ids`	string[]	One of*	IDs of multiple insights to rate
`signal_type`	string	Yes	POSITIVE, NEGATIVE, HUMAN_UPVOTE, HUMAN_DOWNVOTE
`context`	string	No	Optional context about why this rating was given

* Provide either insight_id or insight_ids, not both.

Response

{
  "insight_id": "uuid",
  "signal_id": "uuid",
  "signal_type": "POSITIVE",
  "deposit_amount": 10,
  "new_strength": 52.5,
  "previous_strength": 42.5,
  "status_changed": false,
  "new_status": "promoted"
}

POST

/friction

Get a friction report showing recurring errors and module hotspots. Required scope: sense

Request Body

Field	Type	Required	Description
`error_text`	string	Yes	Error text to analyze
`file_path`	string	No	Scope report to a specific file
`repo_id`	string	No	Repository identifier
`time_range_days`	number	No	Lookback window (default 7)

Response

{
  "time_range_days": 7,
  "top_errors": [...],
  "module_heatmap": [...],
  "formatted_report": "Human-readable friction report",
  "total_sessions": 42,
  "total_friction_episodes": 8
}

Enterprise Bulk Ingestion API

Import knowledge from existing documentation, runbooks, incident reports, and post-mortems. Bulk ingest thousands of entries with automatic deduplication and tagging.

Coming soon on Enterprise plans.