{"openapi":"3.1.0","info":{"title":"Auction Opportunity Feed API","version":"1.0.0","description":"Many auction marketplaces → one normalized opportunity feed. Snapshot + incremental feed + signed webhooks over normalized auction/order opportunities. 4.45 USDC per 24h pass via x402 on Base.","contact":{"name":"Active Life Hub LLC","url":"https://auctionopportunityfeed.online"}},"servers":[{"url":"https://auctionopportunityfeed.online"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Customer API key (aof_…) issued by POST /api/v1/passes."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}}},"Money":{"type":["object","null"],"properties":{"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"},"currency":{"type":"string"}}},"Opportunity":{"type":"object","properties":{"id":{"type":"string"},"source_marketplace":{"type":"string"},"external_order_id":{"type":"string"},"source_url":{"type":["string","null"]},"title":{"type":"string"},"title_translations":{"type":"object","additionalProperties":{"type":"string"},"description":"Only translations published by the source itself."},"description":{"type":"string"},"description_policy":{"enum":["FULL","EXCERPT","NONE"]},"original_language":{"type":["string","null"]},"original_categories":{"type":"array","items":{"type":"string"}},"canonical_category":{"type":["string","null"]},"canonical_categories":{"type":"array","items":{"enum":["web_extraction","research","translation","document_processing","coding","api_work","data_analysis","image_processing","verification","writing","other"]}},"text_categories":{"type":"array","items":{"enum":["web_extraction","research","translation","document_processing","coding","api_work","data_analysis","image_processing","verification","writing","other"]}},"customer_max_price":{"type":["string","null"]},"currency":{"type":["string","null"]},"prices":{"type":"object","properties":{"customer_max_price":{"$ref":"#/components/schemas/Money"},"minimum_price":{"$ref":"#/components/schemas/Money"},"current_price":{"$ref":"#/components/schemas/Money"},"starting_price":{"$ref":"#/components/schemas/Money"},"reserve_price":{"$ref":"#/components/schemas/Money"},"estimated_value":{"$ref":"#/components/schemas/Money"},"estimated_value_min":{"$ref":"#/components/schemas/Money"}}},"currency_conversion":{"type":"null","description":"No implicit conversion is performed."},"auction_type":{"enum":["SEALED_REVERSE","OPEN_REVERSE","FIXED_PRICE_REQUEST","QUOTE_REQUEST","NEGOTIATED","OTHER","UNKNOWN"]},"original_auction_type":{"type":["string","null"]},"state":{"enum":["ANNOUNCED","SCHEDULED","OPEN","CLOSING_SOON","CLOSED","AWARDED","CANCELLED","EXPIRED","UNKNOWN"]},"source_state":{"enum":["ANNOUNCED","SCHEDULED","OPEN","CLOSING_SOON","CLOSED","AWARDED","CANCELLED","EXPIRED","UNKNOWN"]},"original_state":{"type":["string","null"]},"announced_at":{"type":["string","null"]},"auction_start":{"type":["string","null"]},"auction_end":{"type":["string","null"]},"execution_deadline":{"type":["string","null"]},"source_timezone":{"type":["string","null"]},"jurisdiction":{"type":["string","null"]},"required_capability":{"type":["string","null"]},"required_output":{"type":["string","null"]},"eligibility":{"type":"object"},"buyer_name":{"type":["string","null"]},"detected_at":{"type":"string"},"last_verified_at":{"type":"string"},"last_changed_at":{"type":"string"},"freshness_seconds":{"type":"integer"},"latency_class":{"enum":["REAL_TIME","NEAR_REAL_TIME","POLLING","BATCH","UNKNOWN"]},"cross_market":{"type":["string","null"],"enum":["POSSIBLE_CROSS_MARKET_DUPLICATE",null]},"possible_cross_market_duplicates":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object","properties":{"source":{"type":"string"},"external_order_id":{"type":"string"},"adapter_version":{"type":"string"},"normalization_version":{"type":"string"},"license":{"type":["string","null"]},"content_policy":{"type":["string","null"]}}}}},"SourceStatus":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["HEALTHY","DEGRADED","UNAVAILABLE","AUTH_REQUIRED","RATE_LIMITED","UNSUPPORTED","UNKNOWN"]},"latency_class":{"enum":["REAL_TIME","NEAR_REAL_TIME","POLLING","BATCH","UNKNOWN"]},"monitor_state":{"type":"string"},"last_success_at":{"type":["string","null"]},"source_freshness_seconds":{"type":["integer","null"]},"stale":{"type":"boolean"}}}}},"paths":{"/api/health":{"get":{"summary":"Liveness/configuration (no database, no sources)","responses":{"200":{"description":"ok"},"503":{"description":"paid path not configured (fail-closed)"}}}},"/api/v1/marketplaces":{"get":{"summary":"Supported and unsupported sources with capability metadata (free, static)","responses":{"200":{"description":"ok"}}}},"/api/v1/categories":{"get":{"summary":"Canonical category taxonomy and source mappings (free)","responses":{"200":{"description":"ok"}}}},"/api/v1/coverage":{"get":{"summary":"Coverage; with live=1 and a key: live source status","security":[{},{"bearer":[]}],"parameters":[{"name":"live","in":"query","schema":{"enum":["1"]}}],"responses":{"200":{"description":"ok"}}}},"/api/v1/pricing":{"get":{"summary":"Price, measured variable cost and what is included (free)","responses":{"200":{"description":"ok"}}}},"/api/v1/sample":{"get":{"summary":"Recorded real records normalized by the production adapters (free, not live)","responses":{"200":{"description":"ok"}}}},"/api/v1/passes":{"post":{"summary":"Buy a 24h feed pass (4.45 USDC, x402)","description":"Without PAYMENT-SIGNATURE: 402 with the x402 requirement (no database). With it: verify → settle → pass. Without Authorization a new API key is returned once; with it the pass extends that customer.","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"}},{"name":"Authorization","in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"pass granted"},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List your passes","security":[{"bearer":[]}],"responses":{"200":{"description":"ok"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/opportunities":{"get":{"summary":"Snapshot (filters, sort, cursor) or incremental feed (since)","security":[{"bearer":[]}],"parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Canonical categories (structured mapping). Comma-separated: web_extraction, research, translation, document_processing, coding, api_work, data_analysis, image_processing, verification, writing, other.","style":"form"},{"name":"capability","in":"query","schema":{"type":"string"},"description":"Canonical categories matched structurally OR by multilingual text aliases. Comma-separated: web_extraction, research, translation, document_processing, coding, api_work, data_analysis, image_processing, verification, writing, other.","style":"form"},{"name":"currency","in":"query","schema":{"type":"string"},"description":"Primary price currency; required for budget filters/sorts."},{"name":"min_budget","in":"query","schema":{"type":"string"}},{"name":"max_budget","in":"query","schema":{"type":"string"}},{"name":"marketplace","in":"query","schema":{"type":"string"},"description":"Source ids. Comma-separated.","style":"form"},{"name":"language","in":"query","schema":{"type":"string"},"description":"ISO 639-1 original languages. Comma-separated.","style":"form"},{"name":"jurisdiction","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2, or NONE. Comma-separated.","style":"form"},{"name":"auction_type","in":"query","schema":{"type":"string"},"description":"Auction types. Comma-separated: SEALED_REVERSE, OPEN_REVERSE, FIXED_PRICE_REQUEST, QUOTE_REQUEST, NEGOTIATED, OTHER, UNKNOWN.","style":"form"},{"name":"state","in":"query","schema":{"type":"string"},"description":"Default: actionable states only. Comma-separated: ANNOUNCED, SCHEDULED, OPEN, CLOSING_SOON, CLOSED, AWARDED, CANCELLED, EXPIRED, UNKNOWN.","style":"form"},{"name":"starts_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"starts_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"closes_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"closes_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"deadline_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"deadline_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","schema":{"enum":["newest","closing_soon","highest_budget","lowest_budget","auction_start"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page (same query)."},{"name":"since","in":"query","schema":{"type":"string"},"description":"Incremental mode: ev_<n> from next_since, or an ISO time."}],"responses":{"200":{"description":"Snapshot {opportunities, next_cursor, coverage_status, unavailable_sources, sources} or incremental {events, next_since, has_more}","content":{"application/json":{"schema":{"type":"object","properties":{"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}},"next_cursor":{"type":["string","null"]},"coverage_status":{"enum":["COMPLETE","PARTIAL"]},"unavailable_sources":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceStatus"}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/opportunities/{id}":{"get":{"summary":"One opportunity with history (include=raw for sources whose terms allow redistribution)","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","schema":{"enum":["raw"]}}],"responses":{"200":{"description":"ok"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"post":{"summary":"Register a signed webhook (≤3)","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS URL"},"filters":{"type":"object","description":"Same parameters as GET /api/v1/opportunities (no since/cursor)"},"event_types":{"type":"array","items":{"enum":["OPPORTUNITY_CREATED","OPPORTUNITY_UPDATED","OPPORTUNITY_CLOSED","SOURCE_STATUS_CHANGED"]}}}}}}},"responses":{"201":{"description":"created; secret shown once"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List webhooks","security":[{"bearer":[]}],"responses":{"200":{"description":"ok"}}}},"/api/v1/webhooks/{id}":{"delete":{"summary":"Delete a webhook","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}/rotate":{"post":{"summary":"Rotate the signing secret (enable=1 re-enables a disabled webhook)","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"enable","in":"query","schema":{"enum":["1"]}}],"responses":{"200":{"description":"new secret"}}}}}}