Procurement seed
Procurement briefs API
Create saved sourcing criteria and run deterministic catalog matches for procurement workflows.
Procurement briefs save a narrow, versioned sourcing intent for one account. They are the durable contract for agents, CLI workflows, and later web surfaces that need to ask: what currently matches this buying brief?
The first version deliberately supports only pre-pagination-safe catalog constraints. Unsupported filters are rejected instead of stored as no-ops, and manual matches explain why each returned listing satisfies the saved criteria without ranking the coffee as objectively better.
Endpoint and access
- Anonymous callers receive 401 Authentication required.
- Signed-in viewers and API Green keys receive a structured 403 entitlement error before brief data is read or written.
- API-key requests use the same X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After conventions as other paid API routes.
- Brief records are user-owned; one caller cannot fetch or run another account’s brief.
| Route | Method | Auth | Contract |
|---|---|---|---|
| /v1/procurement/briefs | GET | Member/admin session or API key with API Origin or Enterprise plus catalog:read | Lists active saved briefs owned by the caller. |
| /v1/procurement/briefs | POST | Member/admin session or API key with API Origin or Enterprise plus catalog:read | Creates one active manual brief after validating the versioned criteria contract. |
| /v1/procurement/briefs/{id} | GET | Member/admin session or API key with API Origin or Enterprise plus catalog:read | Returns one active caller-owned brief. |
| /v1/procurement/briefs/{id}/matches | GET | Member/admin session or API key with API Origin or Enterprise plus catalog:read | Applies saved criteria to current catalog rows before pagination and returns match reasons plus limitations. |
Criteria contract
Every stored criteria object is normalized to version: 1. The supported fields are country, region, processing, processing_base_method, max_price_per_lb, stocked_only, wholesale_only, and stocked_days.
At least one supported sourcing constraint is required. Unknown fields, wrong value types, empty strings, invalid versions, and out-of-range stocked_days values return 400 with an issues array and allowedFields.
curl -X POST "https://purveyors.io/v1/procurement/briefs" \
-H "Authorization: Bearer pk_live_origin_or_enterprise_key" \
-H "Content-Type: application/json" \
--data '{
"name": "Washed Colombia under 6.50",
"criteria": {
"country": "Colombia",
"processing_base_method": "Washed",
"max_price_per_lb": 6.5,
"stocked_only": true
}
}'Manual matches
GET /v1/procurement/briefs/{id}/matches accepts page and limit query parameters. limit defaults to 25 and is capped at 100.
The response includes data rows in the catalog resource shape with matchReasons, truthful pagination, generatedAt, the saved brief, the criteria used, and limitations explaining that deterministic matches are not quality rankings.
curl "https://purveyors.io/v1/procurement/briefs/00000000-0000-4000-8000-000000000000/matches?limit=10" \
-H "Authorization: Bearer pk_live_origin_or_enterprise_key"{
"error": "Invalid criteria",
"message": "Sourcing brief criteria contains unsupported or invalid fields",
"details": {
"issues": [
{
"field": "unsupported_filter",
"message": "unsupported_filter is not supported by sourcing brief criteria"
}
],
"allowedFields": ["country", "region", "processing", "processing_base_method", "max_price_per_lb", "stocked_only", "wholesale_only", "stocked_days"]
}
}