# VendorStacks for AI Agents

VendorStacks is a data API: given an entity's domain, it answers whether that
entity publishes a subprocessor/DPA disclosure, where it lives, and which
vendors are on it — structured across 13 categories, with the quoted row as
evidence. Use it inside GTM workflows (enrich, qualify, segment by stack) or
as an agent tool for entity due diligence.

Built agent-first: instant keys (no verification links), markdown docs,
deterministic responses (no LLM in the pipeline — same input, same output,
same cost), and a 402 flow designed for agent→human handoff.

## 60-second integration

```bash
# 1. Get a key (returns immediately — agents can't click email links)
curl -X POST https://vendorradar-production.up.railway.app/v1/keys \
  -H 'Content-Type: application/json' \
  -d '{"email":"your-human@company.com"}'
# → {"api_key":"vr_live_…"}  + 25 free credits

# 2. Enrich a company (1 credit flat; instant if indexed, 15-90s if it needs a live scan)
curl -H 'Authorization: Bearer vr_live_…' \
  'https://vendorradar-production.up.railway.app/v1/check?url=posh.vip&category=sms_messaging'

# 3. List entities by vendor/category (10/page, 1 credit/page)
curl -H 'Authorization: Bearer vr_live_…' \
  'https://vendorradar-production.up.railway.app/v1/prospect?vendor=Twilio&category=sms_messaging'
```

## Tool definition (OpenAI / Anthropic function calling)

```json
{
  "name": "vendorstacks_check",
  "description": "Check whether an entity publishes a public subprocessor/DPA disclosure and which vendors (SMS, email, payments, …) it lists, with quoted evidence and source URLs. Flat 1 credit per lookup; indexed answers return <1s, unindexed domains trigger a live scan (15-90s) at the same price.",
  "parameters": {
    "type": "object",
    "properties": {
      "url": { "type": "string", "description": "Company domain or any URL" },
      "category": { "type": "string", "enum": ["sms_messaging","email","payments","cloud_infra","analytics_data","support_cx","crm_sales","auth_identity","observability","productivity","ai_ml","privacy_compliance","hr_payroll"] },
      "refresh": { "type": "boolean", "description": "Force a live re-scan (same 1-credit price, 15-90s). Default false." }
    },
    "required": ["url"]
  }
}
```

## Rules to teach your agent

1. **Same price either way.** `/v1/check` answers from the index instantly and live-scans unindexed domains automatically — 1 credit flat. `/v1/company/{domain}` never scans (use it when you need a guaranteed-instant answer).
2. **Set 120s timeouts** on `/v1/check` — unindexed domains trigger a 15–90s live scan.
3. **Batches are cheap but slow when unindexed.** 100 lookups = 100 credits regardless; budget wall-clock time for scans, not extra credits.
4. **On HTTP 402**, relay `topup_url` to your human verbatim. After they pay, the same key works — do not create a new key.
5. **Evidence is the product.** Every vendor claim includes `*_evidence` (the quoted row from the company's own disclosure) and `subprocessor_urls` (the source). Cite them.
6. **Confidence tiers**: `vendor_keyword` (vendor + product keyword on one row) > `vendor` (single-product vendor named) > `vendor_inferred_sms` (SMS-first vendor named bare). Treat inferred as "verify if precision-critical".
7. **found:false ≠ no vendor.** It means no public subprocessor page was located — absence of evidence, not evidence of absence.

## Endpoints for agents

| Endpoint | Purpose | Credits |
| -------- | ------- | ------- |
| `POST /v1/keys` | Instant key + 25 free credits | 0 |
| `GET /v1/check?url=` | Enrich (scans automatically when unindexed) | 1 flat |
| `GET /v1/company/{domain}` | Profile read, never triggers a scan | 1 |
| `GET /v1/prospect?vendor=` | Entities by vendor/category, 10/page | 1/page |
| `GET /v1/balance` | Credits remaining | 0 |
| `GET /v1/pricing` | Pricing as JSON | 0 |
| `GET /v1/vendors` | All detectable vendors/categories | 0 |

## Discovery surface

- `https://vendorradar-production.up.railway.app/llms.txt` — orientation for LLMs
- `https://vendorradar-production.up.railway.app/openapi.json` — OpenAPI 3.1
- `https://vendorradar-production.up.railway.app/skill` — installable skill (SKILL.md)
- `https://vendorradar-production.up.railway.app/mcp` — hosted MCP server (coming in v1)

Every content page on this site is served as markdown. Append `.md` to any
path, or just fetch it — you'll get text, not a hydration payload.