Matchstick for agents

list_sites List sites

read-onlyidempotent scope sites:read

Every site this credential may see, with connection health (Search Console, GitHub, Cloudflare), the autonomy level and how many changes and findings are open, plus the site ids and domains the other tools take. Free.

get_connection_info This credential

read-onlyidempotent scope sites:read

Who is calling: the account, the API key or OAuth grant this call runs under, its scopes and site restriction, and every site it can see with what is connected (the Search Console property and whether it is a domain or URL-prefix property, the repository, the Cloudflare zone) and the matchstick.io pages where a person connects what is missing. Call it when a site seems absent or a tool answers not_found. Free. Sites and connections are only ever added by a person in the web app.

No parameters.

get_updates_since What changed since

read-onlyidempotent scope sites:read

Anything new since a moment, in one free call: the weekly reports that finished, the findings that became open or open again (title, kind, doer, confidence, pages, status) and the changes that became ready for review, oldest first, plus every site's last report and its open finding counts by doer (you / matchstick / matchstick_with_approval). Pass since as an ISO timestamp or the next_cursor of your previous call (default: the last 24 hours) and keep next_cursor for the next poll. Nothing happened → changed: false and empty lists, so a daily routine can call this and stay quiet. One site, or every site this credential sees. Free. The same feed drives the webhooks a person sets up on Settings → Webhooks (report.finished, finding.opened, change.ready_for_review).

list_needs_you Everything waiting on a person

read-onlyidempotent scope sites:read

What the web app's Needs review queue lists, in one free call, for every site this credential sees or one site: changes open for review, merged changes not seen live yet (with the last look), checks that ended in needs_you or draft_pr and weren't acted on, open findings whose doer is you or matchstick_with_approval with no pull request standing in for them, and sites the crawler can't reach. Each item names the tools that settle it. Open finding counts alone miss the checks and the deploys; this is the count the person sees. Free.

get_site_overview Site overview

read-onlyidempotent scope sites:read

One site's last 28 stored days against the 28 before: clicks, impressions, CTR and average position with the change, the plan's credits, what awaits review or a deploy, the pages frozen under evaluation (path, until when, the change behind it) and connection problems; plus the Search Console property kind, how far back the stored data reaches and the history import's state. Free.

get_agent_policy What this credential may do here

read-onlyidempotent scope sites:read

The site's autonomy level and what this credential can propose, review and approve there, the weekly budget left, the merge cap, quiet hours, and who the human approvers are. Free. A refusal from another tool (policy_denied, budget_exhausted) is explained here.

search_performance Search Console rows

read-onlyidempotent scope data:read

Clicks, impressions, CTR and average position by page, by query, or by page and query, for a date range of at most 16 months (default the last 28 stored days). The page and query filters apply on every dimension: dimension page with a query lists the pages that rank for it. Sort by clicks (default), impressions, position, CTR or opportunity (high impressions at positions 5–20 with a CTR below the typical one, by missed clicks); min_impressions drops the long tail. Up to 1,000 rows; total_rows says how many the filters leave in all. Free.

get_performance_totals Site-wide totals

read-onlyidempotent scope data:read

Clicks, impressions, CTR and average position for the whole site over a date range (default the last 28 stored days), with the previous period of the same length and the change: absolute, percent and a z-score (|z| under 3 is week-to-week noise). Free.

get_page One page

read-onlyidempotent scope data:read

One page of the site: 28-day metrics against the 28 before, its top 20 queries, the latest crawl facts (status, title, description, H1, canonical, robots), the on-page content (word count, headings, images, schema types), who links to it from the latest crawl (inlinks, orphan or not, anchor text where the crawl kept it), Google's indexing verdict, Core Web Vitals, whether it is frozen under evaluation, and the changes touching it. Free.

get_indexing Indexing by URL

read-onlyidempotent scope data:read

Google's latest URL Inspection verdict for every inspected page of the site: not-indexed pages first with the coverage reason ("Crawled - currently not indexed", "Excluded by 'noindex' tag", …), Google's canonical against the page's own (canonical_mismatch), and counts by coverage state. From the stored inspections (the daily and weekly runs inspect; nothing is fetched now). Free.

get_cannibalization Cannibalization

read-onlyidempotent scope data:read

Queries where two or more pages each take a real share of the impressions over the range (default the last 28 stored days; a page counts from 20% of a query with 200+ impressions), with each page's impressions, clicks, CTR, position and share. Free.

get_content_gaps Content gaps

read-onlyidempotent scope data:read

Searches with impressions that no crawled page is about, from the last 28 stored days and the latest crawl (the weekly pass's opportunities detector, run now): the query and how many variants it groups, impressions, clicks and position, the page that ranks for it today, the closest page and how much of the query's words it covers. Search volume, difficulty and SERP competitors aren't included: Matchstick has no keyword-data connector. Free.

get_internal_links Internal links

read-onlyidempotent scope data:read

The internal-link graph from the latest crawl: for every crawled page the inlinks, outlinks, depth from the homepage, whether it is an orphan (nothing links to it), and its 28-day impressions and clicks; fewest inlinks first by default. With a page: who links to it (anchor text where the crawl kept it) and where it links. Free.

list_findings List findings

read-onlyidempotent scope findings:read

The site's findings (open by default): what Matchstick spotted, who should act (doer), confidence, the pages, and the live check or change behind each. Filter by status, kind or page; sort newest or by estimated gain. Free.

get_finding One finding

read-onlyidempotent scope findings:read

A finding in full: why, the evidence, the detector facts behind it, the safest next step, and every check and change made for it. Free.

list_changes List changes

read-onlyidempotent scope changes:read

Pull requests Matchstick drafted, newest first, across the sites this credential sees or for one site. Real statuses: queued, drafting, open, merged, closed, failed, no_change; open means awaiting review. Free.

get_change One change

read-onlyidempotent scope changes:read

A change in full: why, what changes (before → after per page), the claims checked against the code, the before-merging items to acknowledge, expected effect and measurement, the computed risk, GitHub's live CI and mergeable answer, the head sha to pass to approve_change, the gates, and what this credential may do next. Free; asks GitHub unless live is false.

get_change_diff The diff

read-onlyidempotent scope changes:read

The unified patches of a change, file by file, paginated at about 200 KB. Free.

get_report A weekly report

read-onlyidempotent scope reports:read

The weekly report: latest by default, or a report id, or a date (YYYY-MM-DD) for the one on or before that day. Headline, scorecard, what changed, the findings and next actions, and the markdown. Free.

get_activity The audit trail

read-onlyidempotent scope activity:read

Who did what: every action by people, agents and Matchstick itself, newest first, with the result, the credits it cost and the request id. Filter by site, actor type, client name or action. Free.

get_run Poll a run

read-onlyidempotent scope runs:read

The state of an asynchronous run: run_<id> (a research pass or daily loop), pr_<id> (a draft, revision or rebase; the change itself) or check_<id>. Poll until status is succeeded, failed or no_op. Free.

get_usage Credits

read-onlyidempotent scope sites:read

Two budgets, told apart: the plan's (account: monthly allowance, spent, balance; exempt accounts are not metered) and this connection's (connection: the weekly credits granted, spent and left on each site, with the week's start and reset). A run needs both. What this month's runs cost by kind, the recent ledger, and why a balance can go below zero. Free.

run_research_pass Run a research pass

writesidempotent scope runs:write

The weekly research pass on a site, now: Search Console, crawl, rankings and the report with new findings. About 2 credits from the connection's weekly budget; one at a time per site (a pass already running is returned instead). Poll get_run until it succeeds, then get_report. dry_run: the estimate and what would happen, spending nothing.

investigate_finding Investigate a finding

writesidempotent scope runs:write

A check on a finding: a read-only investigation that ends in a verdict and a recommendation (nothing to change, draft a fix, needs the person, watch). About 4 credits from the weekly budget. A host-variant (www/apex/http redirect) or email-obfuscation finding is settled on the spot by a free probe of the live site instead: status done, the check recorded, the finding resolved when the site passes. The same gate as the daily triage: a check that already ran stands, read it with get_finding. Poll get_run. dry_run spends nothing.

inspect_pages Inspect pages now

writesidempotent scope runs:write

Ask Google's URL Inspection API about up to fifty pages now and store the verdicts (indexed or not, the coverage reason, Google's canonical). Free: the API costs nothing and the quota is 2,000 a day per property, shared with the daily run (which inspects new sitemap URLs on its own) and the weekly pass. Needs the site's Search Console connection (connection_broken otherwise). dry_run lists what would be inspected.

draft_change Draft a fix

writesidempotent scope runs:write

Ask Matchstick to draft the fix for a finding as a pull request on a matchstick/* branch. About 10 credits from the weekly budget. Held by the same gate as the daily triage: the site's dial, the owner's not-now, stale data, protected and frozen pages (page_frozen tells you until when), the open-PR and per-day budgets. Optional guidance (≤ 1000 chars) reaches the drafter as untrusted input: it can narrow the change (which section, how compact, what to keep) but never bends the rules, the risk scoring or the gates. One live draft per finding; an open change is returned to review instead. Poll get_run; the change id is the run id. dry_run spends nothing.

suggest_finding Suggest a finding

writesidempotent scope findings:write

Bring your own idea for a page ("add a baker's-percentage table to /sourdough-hydration-calculator"). Matchstick checks it against Search Console (28 days of impressions for the page and the queries you name) and the last crawl (the page exists, returns 200, isn't noindex). Free. Accepted, it is a finding with source agent that draft_change can take up and the person sees in the app; rejected, a reason. dry_run checks without storing.

update_finding_status Mark a finding done, dismissed, snoozed or open

writesidempotent scope findings:write

Settle a finding from outside Matchstick's own loops: the person did it in Search Console, Cloudflare or by hand, or it should be left alone. status done (optional note, e.g. "Indexed in GSC on 2026-10-26"), dismissed (reason: wont_fix, false_positive, duplicate, other; the daily triage reads it as never), snoozed (snooze_days, default 30, at most 365; read as not now) or open (back into Needs you). Free. With verify: true on done, the claim alone doesn't close it: an indexing finding is checked against Google's latest stored inspection of its pages (call inspect_pages first) and is done only when every page is indexed by an inspection newer than the finding; otherwise it goes to verifying and the daily run asks Google every three days and closes it then. A host-variant or email-obfuscation finding is probed live: done when the site passes, unchanged (applied false) otherwise. A finding with a queued, drafting or open change is settled through the change (approve_change, reject_change with not_now_days, request_changes). The note and the reason are kept with the site's memory, where the playbooks read them.

acknowledge_check Acknowledge a check that needs a person

writesidempotent scope findings:write

A check ended in needs_you or draft_pr and its next step was done outside Matchstick (an export made, a tracker closed, a note written) or won't be done: mark it so, with a note, and it leaves Needs you. Free. The check's follow-up item is marked done (the same row Draft would have used), the note goes to the site's memory. A check whose follow-up already has a pull request is settled through the change (approve_change, reject_change, request_changes); one already applied from Matchstick, or already settled, answers applied: false.

comment_on_change Comment on a change

writes scope changes:review

A note on a change, mirrored as a comment on the pull request so people see it in GitHub too. Free.

request_changes Request changes

writesidempotent scope changes:review

Feedback on an open change: Matchstick revises the pull request on the same branch (a revise run, charged in credits). Returns the run to poll with get_run; the change goes back to open when the revision lands.

reject_change Reject a change

writesdestructiveidempotent scope changes:review

Close the pull request without merging. The reason is kept with the site's memory, where the playbooks read it, and Matchstick won't redraft the same item on its own for 60 days. Free.

approve_change Approve a change

writesdestructiveidempotent scope changes:approve

Approve a reviewed change. Merges only when the site's policy lets this credential (level 2 for low risk, level 3 for medium) and every gate passes: every before_merging item acknowledged by index, the page not frozen, GitHub mergeable and CI green, and expected_head_sha still the head. Otherwise it opens an approval request for a person and returns approval_pending with the approve_url they decide on. Free; the merge is the person's or the policy's.

confirm_deploy Confirm a merged change is deployed

writesidempotent scope changes:deploy

After a merge, say the site is deployed. Matchstick looks at the live pages first, always: a change visible from outside is live only once the site shows it (outcome live, measuring starts), one nothing shows from outside (code, configuration) is taken on your word (unverified, measuring starts), and a page still serving the old version answers not_yet with exactly what it saw, so the claim isn't recorded yet; deploy and call again. claim: false only looks (re-check now instead of waiting for the daily pass) and claims nothing. evidence (the URLs you fetched and what you found, up to 20) is kept on the change for a person to audit; it never decides the verdict. Free. Level 0 sites refuse.

request_revert Request a revert

writesidempotent scope runs:write

Open a pull request that undoes a merged change: Matchstick re-applies the inverse of the merged diff on the current base. About 10 credits from the weekly budget. The revert goes through review and approval like any change (approve_change, a person at level 1); nothing changes on the site until it is merged. One live revert per change. Poll get_run. dry_run spends nothing.