Skip to main content

API Overview

Programmatic access to VendorTruth's verification engine—what's available, what's not, and actual performance characteristics.

Base URL

https://api.vendortruth.org/v1

How it works:

  • RESTful API with JSON request/response
  • HTTPS/TLS encryption for all requests
  • Versioned API (v1 current, backwards compatibility committed for 12 months minimum)

What's not available:

  • No GraphQL endpoint (REST only)
  • No SDK libraries (raw HTTP requests required)
  • No auto-generated client libraries

Authentication

All API requests require Bearer token authentication (API key in Authorization header).

How it works:

  • API keys scoped to your account (can't access other users' data)
  • Keys can be revoked/rotated via dashboard

Limitations:

  • No fine-grained API key permissions (single key has full account access—no read-only keys)
  • No OAuth 2.0 support (only API keys)
  • No forced key expiration (you manage rotation)

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.vendortruth.org/v1/vendors

Security considerations:

  • Store API keys securely (environment variables, secret managers)
  • Keys have full account access—compromise = full account compromise
  • No IP whitelisting or additional security controls

Rate Limits

PlanRequests/minuteRequests/dayReport Generation
Free101,00010/month
Pro10050,000500/month
EnterpriseCustomCustomUnlimited*

How it works:

  • Rate limits enforced with HTTP 429 (Too Many Requests) response
  • X-RateLimit-Remaining header shows remaining quota
  • X-RateLimit-Reset header shows reset time
  • Requests/day is a hard cap (not sliding window)—resets at midnight UTC
  • Report generation quota is separate from API request quota

Limitations:

  • "Unlimited*" for Enterprise has undocumented fair use policy
  • No burst allowance documented

When rate limits are adequate:

  • Batch processing with delays (respect rate limits)
  • Low-frequency monitoring (hourly checks)
  • Small team usage (< 100 reports/month)

When rate limits are a problem:

  • High-frequency polling (sub-minute status checks)
  • Large team concurrent usage (100+ users)
  • Bulk historical analysis (thousands of vendors)

Key Endpoints

Vendors

GET /vendors - List all vendors in knowledge graph

Returns paginated list (100 vendors per page) with vendor slug, name, category. Filterable by category query parameter.

Limitations:

  • No full-text search endpoint (must fetch all and filter client-side)
  • No sorting options (alphabetical by name only)
  • Pagination cursor-based (not offset/limit)—can't jump to arbitrary page

GET /vendors/{slug} - Get vendor details

Returns vendor profile with published truth reports. Includes monitoring alert configuration if you're tracking vendor.

Limitations:

  • No historical report versions (only current report)
  • Report timestamps not included in response

Truth Reports

POST /reports - Generate new truth report

Accepts vendor claim as input, returns job ID for async status tracking. Counts toward monthly report quota.

Limitations:

  • No webhook callback option (must poll for completion)
  • No priority queue (Enterprise pays same 2-5 minute wait as Free)
  • Request payload limited to 1KB (long claims get truncated)

Request example:

curl -X POST https://api.vendortruth.org/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim": "MongoDB has elastic scalability", "vendor": "MongoDB"}'

Response:

{
  "job_id": "rep_abc123",
  "status": "queued",
  "estimated_completion": "2025-03-15T10:23:00Z"
}

GET /reports/{job_id} - Check report status

Returns current status (queued, processing, complete, failed) with streaming progress updates if status is "processing".

Limitations:

  • No WebSocket support (must poll HTTP endpoint)
  • Recommended poll interval not documented
  • Job retention period unclear

GET /reports/{job_id}/results - Get completed report

Returns full truth report JSON (all sections, sources, findings) including verdict, strengths, weaknesses, recommendations.

Limitations:

  • No PDF/Markdown format via API (JSON only—must render yourself)
  • Large reports (> 50KB JSON) not paginated (single response)

Alerts

GET /alerts - List your monitoring alerts

Returns all active alerts for your account with alert configuration and last check timestamp.

POST /alerts - Create new alert

Monitor vendor for pricing, policy, or product changes. Specify check frequency (hourly for Pro, daily for Free).

Limitations:

  • No custom webhook URL (alerts via email only)
  • Can't monitor arbitrary URLs (only supported vendor pages)
  • Alert threshold/sensitivity not configurable (AI judges significance)

PATCH /alerts/{id} - Update alert DELETE /alerts/{id} - Delete alert

Error Handling

HTTP status codes:

  • 200 OK - Success
  • 400 Bad Request - Invalid input (check error message)
  • 401 Unauthorized - Invalid/missing API key
  • 404 Not Found - Resource doesn't exist
  • 429 Too Many Requests - Rate limit exceeded (wait for X-RateLimit-Reset)
  • 500 Internal Server Error - Platform error (retry with exponential backoff)

Error responses include JSON with error field explaining issue. Retry-safe for 5xx errors (idempotent operations).

Limitations:

  • No error codes (only HTTP status + message—can't distinguish error types programmatically)
  • No status page for API availability

API Stability & Versioning

Versioning:

  • Breaking changes versioned (v1 → v2 transition)
  • v1 backwards compatibility committed for 12 months after v2 release
  • Deprecation warnings via HTTP headers (Sunset: 2026-01-01)

Limitations:

  • No published roadmap (can't predict when v2 drops)
  • "12 months" commitment is best-effort (not legally binding)
  • No changelog or release notes for non-breaking changes

Next Steps