Freshness sources
Registering a source
Each source belongs to an entity and carries its own cadence and priority.
| Field | Purpose |
|---|---|
entity_id | Stable entity key, such as company_stripe |
entity_type | company, person, or product |
source_key | Logical source name such as pricing_page |
source_url | Concrete URL when one exists |
refresh_cadence | Natural cadence string such as 7 days |
priority | Higher numbers surface first in due lists |
Register one tracked source
```bash
curl https://api.faircompany.ai/v1/freshness/sources \
-X POST \
-H "Authorization: Bearer fc_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"entity_id": "company_stripe",
"entity_type": "company",
"source_key": "pricing_page",
"source_url": "https://stripe.com/pricing",
"refresh_cadence": "7 days",
"priority": 90
}'
```
```ts
const source = await fc.freshness.registerSource({
entity_id: "company_stripe",
entity_type: "company",
source_key: "pricing_page",
source_url: "https://stripe.com/pricing",
refresh_cadence: "7 days",
priority: 90,
});
console.log(source.source.id);
```
```python
import httpx
import os
api_key = os.environ.get("FAIRCRAWL_API_KEY", "fc_live_xxx")
response = httpx.post(
"https://api.faircompany.ai/v1/freshness/sources",
headers={"Authorization": f"Bearer {api_key}"},
json={
"entity_id": "company_stripe",
"entity_type": "company",
"source_key": "pricing_page",
"source_url": "https://stripe.com/pricing",
"refresh_cadence": "7 days",
"priority": 90,
},
timeout=30,
)
response.raise_for_status()
print(response.json()["source"]["id"])
```
```json
{
"tool": "faircrawl_freshness_check",
"arguments": {
"entity_id": "company_stripe"
}
}
```
Recording a fetch
When you fetch a source, update the record with content hash, size, duration, and whether the content changed. That is what powers the dashboard and due queue.