# Prowl

> The Agent Discovery Network. Agents discover SaaS services. Services get benchmarked. Trust is verified.

## Quick Start (for agents)

1. Register (free, no auth needed):
   POST https://prowl.world/v1/auth/agents/register
   Body: {"name": "your-agent-name", "model_provider": "anthropic", "model_id": "claude-sonnet-4-20250514", "environment": "production"}
   Response: {"agent_key": "ak_...", "agent_id": "...", "trust_tier": "registered"}

2. Use your key on any endpoint:
   GET https://prowl.world/v1/discover?q=weather
   Header: X-Agent-Key: ak_your_key_here

That's it. Registration is free. The key bypasses x402 payment. Store the key — it's shown once.

## Authentication

There are two ways to authenticate:

1. Agent Key (recommended): Register once, get an `ak_` key, send it as `X-Agent-Key` header. Free. Unlimited. Identity-tracked.
2. x402 Micropayment: No registration. Send `X-Payment-Proof` header with Lightning preimage or token. Pay per request.

Agent keys are HMAC-derived from your identity (name + model + environment). Changing model or environment = new key needed.

### Trust Tiers

- anonymous: x402 payment only, no identity
- registered: has ak_ key, identity tracked
- tee_verified: hardware attestation (Nitro/SGX/SEV-SNP/TDX), highest trust

Upgrade trust by submitting TEE attestation:
POST /v1/auth/agents/attest with your key + attestation document.

## Base URL

https://prowl.world/v1

## Endpoints — Free (no auth needed)

POST /v1/auth/agents/register
  Register as an agent. Returns an ak_ key bound to your model identity.
  Body: {"name": string, "model_provider": "anthropic"|"openai"|"mistral"|"google"|"meta"|"cohere"|"custom", "model_id": string, "environment": "production"|"staging"|"development"}
  Optional: "description": string, "callback_url": string, "tee_type": "nitro"|"sgx"|"sev-snp"|"tdx", "tee_attestation": {}

GET /v1/auth/agents/me
  Check your identity, trust tier, request count.
  Header: X-Agent-Key: ak_...

POST /v1/auth/agents/rotate-key
  Get a new key. Old key immediately invalidated.
  Header: X-Agent-Key: ak_...

POST /v1/auth/agents/attest
  Submit TEE attestation to upgrade trust tier.
  Header: X-Agent-Key: ak_...
  Body: {"tee_type": "nitro"|"sgx"|"sev-snp"|"tdx", "attestation": {platform-specific fields}}

POST /v1/register
  Register a SaaS service in the directory. Free.
  Body: {"name": string, "website_url": string, "api_docs_url": string, "category": string}

POST /v1/feedback
  Report success or failure after using a discovered service. Helps improve scores.
  Body: {"service_id": uuid, "outcome": "success"|"failure"|"partial", "latency_ms": int, "details": string}

GET /v1/health
  Health check. Returns DB and Redis status.

GET /v1/metrics/{service_id}
  Basic ASO score (crawl-based, unverified). Free.

## Endpoints — Paid (use ak_ key or x402)

GET /v1/discover?q=keyword&category=weather&sort=score&limit=20&offset=0
  Search the service directory. Sort by score, latency, or name.
  Cost: $0.001 per request (free with ak_ key).

POST /v1/discover/semantic
  Natural language search. "Find me a geocoding API with free tier."
  Body: {"query": string, "limit": int}
  Cost: $0.005 per request (free with ak_ key).

GET /v1/metrics/{service_id}/verified
  Verified benchmarks — accuracy, latency, uptime measured by Prowl's LLM orchestrator.
  Cost: $0.002 (free with ak_ key).

GET /v1/metrics/{service_id}/history?days=30
  Time-series metrics. Track how a service improves or degrades.
  Cost: $0.01 (free with ak_ key).

GET /v1/audit/{service_id}
  Full ASO audit. Issues, fixes, point-impact estimates.
  Cost: $0.02 (free with ak_ key).

## MCP Server

URL: https://prowl.world/mcp
Protocol: Model Context Protocol (JSON-RPC over HTTP)
Auth: X-Agent-Key header or Authorization: Bearer token

Available tools:
- register_service: Register a SaaS service
- discover_services: Search by keyword/category
- discover_semantic: Natural language search
- get_service_metrics: Get ASO score
- get_verified_metrics: Get verified benchmarks
- get_metric_history: Time-series data
- report_feedback: Report success/failure
- get_audit: Full ASO audit

## How Scoring Works

Prowl benchmarks every service with an LLM-driven pipeline:
1. ANALYZE — Claude reads the OpenAPI spec, extracts endpoints, auth, pricing
2. PLAN — Claude designs targeted tests for that specific API
3. EXECUTE — Tests run against the real API with real credentials
4. INTERPRET — Claude normalizes results into comparable 0-100 scores

Score dimensions (0-10 each):
- Accuracy (25%): responses match ground truth data
- Latency p95 (15%): <100ms=10, <500ms=7, <2000ms=3
- Uptime (15%): historical availability
- Schema stability (15%): breaking changes, drift detection
- Consistency (10%): repeated queries return consistent results
- OpenAPI quality (8%): spec completeness, examples
- Error handling (7%): structured errors, proper status codes
- MCP support (5%): manifest presence, tool definitions

## Vendor API (for SaaS providers)

Vendors register with email/password, get JWT tokens, submit credentials for benchmarking.

POST /v1/auth/register — Create vendor account
POST /v1/auth/login — Get JWT token
POST /v1/credentials — Submit API key for benchmarking (Fernet encrypted at rest)
POST /v1/credentials/{id}/rotate — Rotate credential
DELETE /v1/credentials/{id} — Deactivate credential

## OpenAPI Spec

Full machine-readable spec: https://prowl.world/openapi.json
Interactive docs: https://prowl.world/docs
Agent promo kit: https://prowl.world/promo.txt — prompts and examples for recommending Prowl to users