# Contrie

> Web data infrastructure for AI agents. POST a URL plus a natural-language
> description or a JSON Schema; get back validated JSON with a 0-100 quality
> score, a grounding ratio, the full escalation trace, and the model cost of
> the call. Free during beta.

Contrie runs a pipeline, not a single model call: heuristic extraction
(JSON-LD, microdata, Open Graph) first, then classify, route to the cheapest
capable tier of a 17-model fleet, extract, validate (schema 40 / completeness
40 / sanity+grounding 20, threshold 70), and escalate one tier at a time (max
2 escalations) only if quality falls short. Structure-preserving markdown is
available at zero model cost via `format: "markdown"`.

Scope: single-page extraction and reading. Contrie does not run a browser in
the hosted API — JS-only shells return `RENDER_REQUIRED` — and it does not
crawl sites, search the web, or drive multi-step browser tasks.

## Docs

- Full documentation: https://contrie.com/docs
- Scrape endpoint: https://contrie.com/docs/scrape
- Extract endpoint (HTML in, no fetch): https://contrie.com/docs/extract
- Authentication: https://contrie.com/docs/authentication
- Rate limits: https://contrie.com/docs/rate-limits
- Error codes: https://contrie.com/docs/errors
- Pipeline architecture: https://contrie.com/architecture
- OpenAPI spec: https://contrie.com/openapi.json
- Agent Skill (setup + decision procedure): https://contrie.com/agent-onboarding/SKILL.md

## API

Base URL: `https://contrie.com`. Auth: `Authorization: Bearer ck_live_...`
(create a key at https://contrie.com/dashboard/keys). Sample URLs work
without a key: https://news.ycombinator.com, https://example.com,
https://www.producthunt.com.

```bash
curl -X POST https://contrie.com/api/v1/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CONTRIE_API_KEY" \
  -d '{
    "url": "https://news.ycombinator.com",
    "extract": "Top 5 stories with title, url, and points"
  }'
```

`POST /api/v1/scrape` — body `{ url, extract?, schema?, format?, options? }`.
`POST /api/v1/extract` — same, but body has `{ html, url, extract?, schema?, format? }` and performs no fetch.
`GET /api/health` — `{ status: "ok" }`.

Response shape:

```json
{
  "success": true,
  "data": { "...": "..." },
  "metadata": {
    "url": "https://news.ycombinator.com",
    "extractionMethod": "ai",
    "model": "...",
    "qualityScore": 92,
    "grounding": 0.94,
    "escalations": 0,
    "latencyMs": 2340,
    "costUsd": 0.0004,
    "trace": [ { "stage": "heuristic", "detail": "..." } ],
    "credits": 1
  }
}
```

Errors: `{ "success": false, "error": { "code": "...", "message": "..." } }`.
Codes: `INVALID_REQUEST` 400, `INVALID_URL` 400, `UNAUTHORIZED` 401,
`FETCH_FAILED` 422, `RENDER_REQUIRED` 422, `RATE_LIMITED` 429 (with
`Retry-After`), `PAGE_LIMIT_REACHED` 429, `SERVICE_UNAVAILABLE` 503,
`EXTRACTION_FAILED` 500.

Streaming: send `Accept: application/x-ndjson` on either endpoint for
newline-delimited `{"event":"trace",...}` lines followed by a final
`{"event":"result",...}` line.

## MCP

Hosted, Streamable HTTP: `https://contrie.com/mcp`. Send
`Authorization: Bearer <key>` — without a key only the sample URLs succeed.
Tools: `contrie_extract { url, extract?, schema? }` and
`contrie_read { url }` (markdown).

Local stdio alternative from a clone: `npx -y tsx packages/mcp/src/server.ts`
with env `CONTRIE_API_KEY`.

## Limits

10 requests/min per key. Monthly quota: 1,000 credits on the free plan, charged only
for answers (markdown read 1; passing extraction 1 / 3 / 10 by model tier; failures and
results under 70 cost 0) and returned as metadata.credits. Free during beta. Plans:
https://contrie.com/pricing. SSRF
guard blocks private/internal addresses, including through redirects.

## Optional

Source: https://github.com/DaVinciPicks/contrie_ai