SourceFinch

Docs · Get started

5-minute quickstart

By the end you will have a monitored source: a baseline of structured records with the evidence behind them, a schedule, and a place to see the first change. Pick the path that suits you; they all create the same thing.

In the console

  1. Get access. SourceFinch is onboarding early teams by invitation. Request access; once invited, sign in with that email and name your workspace.
  2. Pick a source. On Overview, start from a Verified source (already tested by our own runner, with its usage rights reviewed), or paste the URL of a public page, feed, API or CSV file.
  3. Check the preview. SourceFinch fetches one sample and shows the repeated records it found, field by field, with how often each field is filled. Rename or drop fields, and choose the field that identifies a record (for example an ID). Nothing is saved yet.
  4. Capture a baseline and choose a schedule. Save the source and run it. The first run retains the raw response, hashes it, timestamps it and extracts validated records: your dated starting point. Choose daily (Free) or hourly (Pro and above); the source page shows the exact time of the next check.
  5. See what changed. Every scheduled run is compared with the last one. Changes lists added, removed and edited records down to the field, each linked to the evidence from both runs. Alerts arrive in your inbox in the console, and by email if you turn it on.

How long until the first change? That depends on the source. A daily source is checked once a day, so the first comparison happens at the next scheduled run after the baseline. Busy sources (notices, listings, registers) usually show changes within a day or two; quiet ones may go weeks without one, which is also worth knowing.

With the REST API

Create a project API key in Console → API & access (a write key, to create sources) and keep it in an environment variable. Every call below is a real operation from the API reference.

export SF=sec_...   # your project API key

1. Check the key and see which project it belongs to:

curl -s https://sourcefinch.com/v1 \
  -H "Authorization: Bearer $SF"

2. Create a source. rights: true records that you have the right to collect and use what it monitors (see rights and acceptable use). The recipe says how to turn the page into records; the recipe reference covers HTML, JSON, XML and CSV.

curl -s https://sourcefinch.com/v1/sources \
  -H "Authorization: Bearer $SF" \
  -H "Content-Type: application/json" \
  -d '{"name":"City permits","url":"https://permits.example.gov/list","recipe":{"format":"html","items":"table.permits tbody tr","fields":{"permit_id":"td:nth-child(1)","status":"td:nth-child(2)","address":"td:nth-child(3)","detail_url":"td:nth-child(1) a@href"},"required":["permit_id","status"]},"rights":true,"schedule":"daily","key_field":"permit_id"}'
The request body, formatted
{
  "name": "City permits",
  "url": "https://permits.example.gov/list",
  "recipe": {
    "format": "html",
    "items": "table.permits tbody tr",
    "fields": {
      "permit_id": "td:nth-child(1)",
      "status": "td:nth-child(2)",
      "address": "td:nth-child(3)",
      "detail_url": "td:nth-child(1) a@href"
    },
    "required": [
      "permit_id",
      "status"
    ]
  },
  "rights": true,
  "schedule": "daily",
  "key_field": "permit_id"
}

3. Start the first run (the baseline). Scheduled runs then start by themselves:

curl -s -X POST https://sourcefinch.com/v1/sources/$SOURCE_ID/runs \
  -H "Authorization: Bearer $SF" \
  -H "Content-Type: application/json" -d '{}'

4. Read the current records, then the changes as later runs arrive:

curl -s "https://sourcefinch.com/v1/sources/$SOURCE_ID/records" \
  -H "Authorization: Bearer $SF"
curl -s "https://sourcefinch.com/v1/changes?source_id=$SOURCE_ID" \
  -H "Authorization: Bearer $SF"

5. Download a run's evidence bundle (records, evidence files, hashes and a manifest):

curl -s -o run.zip https://sourcefinch.com/v1/runs/$RUN_ID/bundle \
  -H "Authorization: Bearer $SF"

To monitor a Verified source exactly as published, pass catalog: { slug, version_id } from GET /v1/catalog/{slug} instead of writing a recipe; a modified or stale definition is rejected.

From an AI assistant

SourceFinch has a remote MCP server, so assistants such as Claude can find Verified sources, create monitors and read records with their evidence. Sign-in uses OAuth in your browser; no key is pasted into the assistant.

claude mcp add --transport http sourcefinch https://sourcefinch.com/mcp

Then ask, for example: “Find a Verified SourceFinch source for state procurement notices and monitor it daily.” See the MCP docs for other clients and tool groups.

Next

The TypeScript SDK and CLI exist but are not yet published to npm. Until they are, use the REST API or MCP.