API and MCP reference

Endpoints

Base URL https://collectsea.com. All responses are JSON unless noted; CORS is open.

POST/api/analyze

Match a planned design or existing app to real failures. Returns the behavior profile, ranked records, safeguards and coverage.

Request fields

proposal: string (up to 25,000 characters)
max_results: 1–25 (optional)
mode: "design" or "existing_app" (optional)
files: [{ name, content }] (optional)

Existing-app files can replace the description.

POST/mcp

Model Context Protocol endpoint (JSON-RPC 2.0, Streamable HTTP, stateless). Also served at /api/mcp.

POST/api/app-context

Read selected text from a public GitHub repository at one revision. Returns files, revision and import notices. No code is executed.

Request fields

{ "repository_url": "https://github.com/owner/app" }

GET/api/incidents

All served records with full detail. Add ?view=summary for a compact list (id, title, summary, tier, date, organization, patterns).

GET/api/incidents/{id}

One record by ID, e.g. /api/incidents/SEA-POST-005.

GET/api/patterns

The failure-pattern taxonomy with definitions, triggers, warning signs and principles.

GET/api/frameworks

Framework crosswalk: OWASP, NIST, CISA and CWE items mapped to patterns.

GET/api/stats

Corpus counts and headline usage counters.

GET/api/impact

Privacy-preserving usage report for the last 30 days. /api/impact.csv returns the daily series.

GET/api/benchmark

Runs the internal retrieval benchmark on the served corpus (lexical and hybrid).

GET/api/health

Deployment contract, corpus version and feed health (alias: /api/verify).

POST/api/feedback

Send feedback or report a record problem. Body: { "type", "message", "email"?, "incident_id"? }.

GET/data/collectsea-incidents.json

Dataset download (also .csv and .jsonl), CC BY 4.0.

GET/openapi.json

OpenAPI 3.1 schema for the public API.

Analyze a design or existing app

curl -s https://collectsea.com/api/analyze \
  -H 'Content-Type: application/json' \
  -H 'X-CollectSEA-Client: my-tool' \
  -d '{"proposal": "Nightly job that deletes unused cloud databases", "max_results": 5}'

The legacy field name idea is still accepted for proposal. Pass exclude_incident_ids (up to 10) to ask for further precedents.

Existing apps

Set mode to existing_app. Submit observed behavior in proposal, relevant text in files, or both. Up to 10 files are accepted within the combined 25,000-character and 32 KB request limits. Remove credentials and personal data. This is a review of selected context: code is not executed and running apps are not scanned.

{
  "mode": "existing_app",
  "proposal": "Our production support app reads customer emails and issues refunds via Stripe.",
  "files": [
    {
      "name": "architecture.md",
      "content": "Refund requests are queued and retried by a background worker."
    }
  ],
  "max_results": 5
}

For a public repository, first call /api/app-context and submit its files and repository metadata to /api/analyze. For MCP, use analyze_existing_app with a repository_url, or the same proposal, files and max_results fields. Ask your coding assistant to inspect the repository and submit a behavior summary with relevant excerpts. Use get_safeguards with mode: "existing_app" to export rules from an app description.

Response fields

input_context

Analysis mode, submitted source names and sizes, and limits of the available evidence.

analysis_id

Identifier for this run (not stored server-side).

profile.capabilities[]

Behavior signals detected in submitted text (id, label, category, evidence).

profile.action_authority_level

READ_ONLY, INTERNAL_STATE_ONLY, REVERSIBLE_EXTERNAL or IRREVERSIBLE_EXTERNAL.

profile.unknowns[]

Questions the submitted context leaves open.

matches[].incident

The matched record (full IncidentRecord, including source_url and safeguards).

matches[].composite_score

0–1 relevance after evidence-tier weighting.

matches[].breakdown

Score components, including embedding_similarity when semantic retrieval ran.

matches[].why_analogous

Plain-language explanation built from shared behaviors, the record's facts and its pattern.

matches[].lessons[]

Safeguards for the record's failure patterns.

top_lessons[]

One lesson per pattern across all matches, ordered by supporting evidence.

coverage

strong | partial | none, with an honest message and the evidence mix.

metadata

Methodology, scoring and corpus versions, retrieval algorithm and timestamp.

Record fields (source, provenance, review status, safeguards) are described on the dataset page.

MCP server

Stateless Streamable HTTP at https://collectsea.com/mcp (protocol versions 2024-11-05 to 2025-11-25). Six read-only tools, each returning text and structuredContent:

analyze_design

Profile a planned system and return matching incidents, patterns and safeguards.

analyze_existing_app

The same for a running app: a public GitHub URL, observed behavior or text files.

search_incidents

Keyword search by company, technology, CVE or failure mode.

get_incident

One full record, with its source, facts and safeguards.

list_failure_patterns

The 14 failure patterns with warning signs and principles.

get_safeguards

Ready-to-commit AGENTS.md or CLAUDE.md rules for a design.

Earlier tool names (analyze_architecture_proposal, search_failure_corpus, get_failure_mechanisms) still work. Notifications receive 202.

curl -s https://collectsea.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"analyze_design",
                 "arguments":{"proposal":"Agent that runs SQL migrations in production","max_results":3}}}'

Client setup for Claude, Cursor, VS Code, Windsurf, Gemini CLI and Codex

Limits and errors

Versioning and reproducibility

Every analysis reports its methodology version, scoring-weights version, capability-vocabulary version and corpus snapshot. Breaking API changes will get a new path; additive fields can appear at any time. See the changelog.