Cortexa

Appearance

HTTP API Reference ​

Cortexa serves a local HTTP API on 127.0.0.1:7373 (port configurable). All endpoints require bearer auth except /api/health.

Authentication ​

bash
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:7373/api/health

Get your token from Settings → External in the app. Per-integration tokens can be issued in Settings → Tokens.

Endpoints ​

GET /api/health ​

Health check. Open even when the vault is locked.

json
{ "ok": true, "version": "0.13.1" }

POST /api/ingest ​

Capture text. Supports /trigger: prefix for templates.

bash
curl -X POST http://127.0.0.1:7373/api/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "/idea: persistent memory for agents"}'

POST /api/capture ​

Structured capture with metadata. Same fields as the cortexa_capture MCP tool.

For a project continuation record, send thought_type: "handoff", project, session_id, and a handoff object with completed and blockers text arrays, verification records (check, status: passed|failed|not_run, details), and next_action. These are bounded caller reports, not independent verification. Traceable project session context includes the newest eligible valid handoff within the existing output budget, even without a keyword match; it does not import another project's handoff.

GET /api/items ​

List items. Query params: limit, tag (repeatable), pinned, source, include_archived, session_id.

GET /api/items/:id ​

Full decrypted content + metadata for a single item.

Hybrid search. Query params: q (required), limit.

bash
curl "http://127.0.0.1:7373/api/search?q=auth+middleware&limit=5" \
  -H "Authorization: Bearer $TOKEN"

GET /api/context ​

Ambient context brief. Query params: context (required), project, file_paths (comma-separated), limit, max_chars. With Traceable context for agents enabled in Search settings, project is a strict project name, slug, or ID. The response retains brief, items, and count and adds context_packet with full source IDs, dates, review states, evidence, and retrieval warnings. Disputed and superseded memories are excluded. Unknown projects fail rather than widening the search. limit accepts 1–20; max_chars accepts 256–24000 and defaults to 6000, including metadata and warnings. Explicit include_derived=true is rejected in this mode. Context sync uses the same project-scoped retrieval, up to 15 entries and 12000 characters.

Packet entries also retain optional thought_type, agent, and session_id capture labels. These help distinguish TODOs, questions, and recorded decisions without asserting completion or verification. Older receipts without these labels remain readable.

The setting defaults to off. With it off, the legacy project value is a ranking boost; it does not restrict results to that project.

bash
curl "http://127.0.0.1:7373/api/context?context=fixing+the+parser&project=Cortexa&limit=10&max_chars=4000" \
  -H "Authorization: Bearer $TOKEN"

POST /api/context/packet ​

Build a bounded, traceable context packet for an agent. Enable Traceable context for agents in Search settings before calling it. The feature defaults to off.

bash
curl -X POST http://127.0.0.1:7373/api/context/packet \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fix the parser mutex order",
    "scope": {"kind": "project", "project_id": "<PROJECT_ID>"},
    "file_paths": ["src/parser.rs"],
    "include_principles": true,
    "max_items": 8,
    "max_chars": 6000
  }'

scope must be either {"kind":"vault"} or a project scope with an exact project ID. Project scope is a hard boundary. The request accepts at most 8,000 Unicode characters in query, 30 paths of at most 512 characters each, max_items from 1 through 20, and max_chars from 256 through 24,000. Unknown and missing fields are rejected.

The response contains the structured packet and its rendered_context. Each entry includes its item ID, revision hash, timestamps, match signals, review state, and evidence references. status is complete, empty, or degraded; warnings explain degraded retrieval or budget exclusions.

Packet-specific failures are 400 invalid_input, 404 project_missing, 409 context_packets_disabled, 423 vault_locked, and 500 context_packet_unavailable. Invalid JSON and invalid request structure both return 400 invalid_input.

POST /api/sync-context ​

Generate .cortexa-context.md in a project directory.

bash
curl -X POST http://127.0.0.1:7373/api/sync-context \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": "MyProject", "dir": "/path/to/project"}'

Returns: { "path": "/path/to/project/.cortexa-context.md", "brief": "...", "items": 15 }

POST /api/think/:id ​

Trigger Deep Think pipeline on an item.

GET /api/brief/:id ​

Get the structured brief after Deep Think completes.

POST /mcp ​

In-process MCP endpoint (JSON-RPC 2.0, Streamable HTTP). Same bearer auth. Serves the same tool set as the stdio bridge.

Error Codes ​

StatusMeaning
200Success
401Missing or invalid bearer token
409Requested feature is disabled
423Vault is locked (idle lock active)
500Internal server error

While Locked ​

When idle lock is active, most endpoints return 423 Locked. Exceptions: /api/health stays open, and read-only MCP tools are whitelisted to work when locked: health, list_projects, list_tools, peer_profiles, tool_metrics, learned_procedures, publications, confidence_history.

GET /api/confidence-history/ ​

Retrieve the confidence score audit trail for an item.

bash
curl http://127.0.0.1:7373/api/confidence-history/abc123 -H "Authorization: Bearer $TOKEN"

Returns JSON array of { old_score, new_score, reason, source, created_at } entries.

GET /api/peer-profiles ​

List all Hive peer profiles from social memory.

bash
curl http://127.0.0.1:7373/api/peer-profiles -H "Authorization: Bearer $TOKEN"

Returns JSON array of peer profiles with contribution stats, thesis quality, and trust scores.

GET /api/learned-procedures ​

Query learned orchestration patterns. Optional ?thought_type=decision filter.

bash
curl "http://127.0.0.1:7373/api/learned-procedures?thought_type=architecture" -H "Authorization: Bearer $TOKEN"

Returns JSON array of { thought_type, tool_sequence, execution_count, success_count, confidence }.

GET /api/tool-metrics ​

Get per-tool observability metrics.

bash
curl http://127.0.0.1:7373/api/tool-metrics -H "Authorization: Bearer $TOKEN"

Returns JSON array of { tool_name, total_calls, successful_calls, error_rate, avg_duration_ms, total_tokens }.

POST /api/reflection ​

Trigger a background reflection pass.

bash
curl -X POST http://127.0.0.1:7373/api/reflection -H "Authorization: Bearer $TOKEN"

Returns { "status": "enqueued" }. The reflection analyzes recent thoughts for themes, contradictions, and patterns.

Built with Rust, Tauri, and a lot of captured thoughts.