skip to content

Embed your credential — JSON API & README badge

Once you've published your Proof of Work (resume_public), your credential is available as a machine-readable JSON API and an embeddable SVG badge — drop either into a GitHub README, a personal site, or your own tooling. Both read the same cached, already-public data your /r/<handle> page shows; nothing new leaves your machine and there is no GitHub recompute on request.

JSON API

GET https://terminalhire.com/api/contributions/<handle>

Returns a stable, versioned envelope:

{
  "schema": "contributions/v1",
  "handle": "octocat",
  "qualifyingTotal": 12,
  "byDomain": [ { "domain": "typescript", "mergedPRs": 8, "distinctOrgs": 5, "lastMergedAt": "2026-03-01T00:00:00Z" } ],
  "trend": [ … ],
  "traction": { "qualifies": true, "bestRepoName": "flagship", "bestRepoExternalContributors": 8, "bestRepoStars": 220, … },
  "computedAt": "2026-06-01T00:00:00Z",
  "profileUrl": "https://terminalhire.com/r/octocat"
}
  • Pin on "schema": "contributions/v1" — the shape is versioned so it won't shift under you.
  • Only public-safe aggregates are emitted. Links to your individual merged PRs (prs) appear only if you've opted into showing them; they never appear otherwise.
  • A handle that hasn't published a public profile — or doesn't exist — returns the same 404 { "error": "not_found" }. You can't use the endpoint to probe who has an account.

README badge

GET https://terminalhire.com/api/contributions/<handle>/badge.svg

A crisp, scalable SVG (shields.io style). Wrap it in a link to your proof page:

[![terminalhire](https://terminalhire.com/api/contributions/octocat/badge.svg)](https://terminalhire.com/r/octocat)

The badge leads with your third-party-verified merge count when you have one, falls back to your maintainer reach (a project you own that others build on), and shows a neutral no public profile when you haven't published — so it never renders broken, and, like the JSON, reveals nothing about handles that haven't opted in.

Proof of Work card

For a larger terminal-style card with accepted contribution, independent-team, recency, and eligible-repository context, replace octocat with your GitHub login:

[![octocat's terminalhire Proof of Work credential](https://terminalhire.com/api/card/octocat.svg)](https://terminalhire.com/r/octocat)

Keep the outer link in place. The SVG is deliberately an inactive image; the Markdown wrapper is what makes the card a real link to the auditable public proof. The card is available only while your public résumé is published.

On your website

The badge is a plain image — no script, no build step, no API key. Drop this inline <img> anywhere HTML renders (a personal site, an MDX page, a portfolio) and wrap it in a link to your proof page:

<a href="https://terminalhire.com/r/<handle>" target="_blank" rel="noopener">
  <img src="https://terminalhire.com/api/contributions/<handle>/badge.svg"
       alt="terminalhire — verified merges" height="22">
</a>

Because terminalhire serves the SVG — you're not baking a number into your own markup — the count stays live and can't be inflated by hand. That's the difference between a badge that says a thing and one that proves it: the image is served by the verifier and links to the verifier's proof page, the same trust pattern as a compliance seal.

Want a custom, on-brand section instead?

For full control over the look, skip the pre-rendered badge and read the JSON API directly — fetch GET /api/contributions/<handle>, pin on "schema": "contributions/v1", and render your own DOM from the aggregates. That's how a bespoke "Open Source Contributions" section (per-repo cards, skill chips, a verified-by link) is built. It's more work than the one-line <img>, but nothing new leaves your visitor's machine and the data is the same already-public credential.

Contribution dossier

A contribution dossier is a per-repo, per-PR evidence page — the detailed twin of your résumé for one repository. It separates independent human review from automation (the two are never combined into a single count), labels self-review honestly as "diligence, not validation", and demotes vanity metrics like time-to-merge out of the headline. Third-party maintainers are anonymized by default. It lives at:

https://terminalhire.com/r/<handle>/<owner>/<repo>

with a machine-readable JSON twin at GET https://terminalhire.com/api/contributions/<handle>/<owner>/<repo> (pin on "schema": "dossier/v1").

Two consent gates — both off by default, both required. A dossier page is public only when BOTH are on:

  • PR links (resume_show_prs) — the same toggle that shows your merged PRs on your résumé.
  • Dossier opt-in (dossier_opt_in) — a separate opt-in for the detailed per-PR evidence.

Turn either off and every dossier page — and the JSON twin — 404s immediately, exactly like a handle that never opted in. A dossier link appears on your résumé and dashboard only for a repo whose dossier is already public, so a link never reveals anything the page itself wouldn't.

For maintainers. If you merged or reviewed a contributor's PR, you appear only as "a repo maintainer" unless you explicitly opt in to be named. Either way you can remove yourself at any time — sign in with your GitHub and submit the self-serve erasure (POST /api/contributions/removal); your identity is permanently anonymized across every dossier and résumé.