Authors
Package authors is a royalty for open-source work: your repo runs, you get paid.
| Base URL | https://api.hanzo.ai |
| Operations | 5 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
authors
GET /v1/authors/basis
Returns the AUDIT TRAIL behind the caller's own royalty: every ledger row with the spend it was computed from, the share applied at the time, the platform's matching half, whether each row satisfies the formula, and the attribution edges that already existed when the row was written.
It answers ONE OF TWO SHAPES. An org that has never connected gets {"isAuthor": false, "defaultShareBps"} — never a 404, which would answer "is this org an author?" for anyone who asked. An enrolled org gets the basis: isAuthor, id, status, asOf, shareBps, platformShareBps, defaultShareBps, shareSource, settlesTo, method (the formula, the rate card and the sizing), ledger, reconciliation, window, and period when one was requested.
This read NEVER sweeps, and that is the point of it being a separate address from the dashboard: an audit must not move the money it is auditing, so calling it N times leaves the balances and the ledger byte-identical.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
period | query | string | — | Period is the UTC accrual month, YYYY-MM. Empty means every period; any other shape is refused with 400, because the… |
POST /v1/authors/connect
Enrols the caller's org in the author program at status "connected" and returns its enrolment, including the verify code the file method needs. It is IDEMPOTENT: a second call returns the same enrolment rather than a conflict.
The forge login is taken from IAM's LINKED account for the provider when there is one — that is identity proof, not a claim — and only otherwise from the login in the body, which then has to be proven per repository. Connecting does not admit an org to earning: a platform reviewer approves that separately.
Answers 201 when it enrolled the org and 200 when it found an existing enrolment.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
githubLogin | string | — | GithubLogin is the account to link. Used only when IAM holds no linked account for the provider — a linked account is… |
login | string | — | Login is the provider-neutral alias for GithubLogin, preferred when both are sent. |
provider | string | — | Provider is the forge to enrol with: github (the default) or gitlab. |
POST /v1/authors/deploys/record
Records that the caller's org deployed a project built from a source repository, which is the edge that makes an author's work earn royalty.
It is deliberately NOT an error for a deploy to attribute to nobody: a project built from no repository, or from one no author has verified, answers {"recorded": false, "reason"} so a deploy pipeline can fire this on every deploy without branching. Attribution resolves per-repository first, then owner-wide, so a repository with its own claim always earns for its own author.
A deploy of a Hanzo-maintained template attributes to the platform treasury, and a self-deploy (the author's own org deploying its own repository) is recorded for provenance but excluded from accrual. The edge is idempotent per repository+project+org.
Answers 201 when it recorded a new edge and 200 otherwise.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
project | string | — | Project is the deployed project's id. |
repoUrl | string | — | RepoURL is the source repository the project was built from. |
POST /v1/authors/repos/verify
Proves that the caller owns a repository — or a whole OWNER — and records the claim, which is what makes deploys of that code earn royalty.
Ownership is proven the SAME two ways in both cases, tried in order: an IAM-linked forge token with admin or push permission, or a hanzo.json on the default branch carrying the author's verify code. Claiming an OWNER proves it against that owner's ".github" control repository, and is exactly as strong as a per-repository claim — an owner the caller cannot prove is refused with 422, never assumed.
A per-repository claim wins over an owner-wide one, so a specifically-claimed repository always earns for its own author. A repository another author has already verified is a 409. The org must have connected first.
Answers 201 when it recorded a new claim and 200 when the claim already existed.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
repoUrl | string | — | RepoURL is what to claim: a repository (github.com/owner/name) or a whole OWNER (github.com/owner, no repository… |
GET /v1/authors
Returns the caller's author-program dashboard: enrolment status, linked forge login, verified repositories and owner-wide claims, recorded deploys, accrued / pending / paid royalty, and the payout history.
It answers ONE OF TWO SHAPES from this address. An org that has never connected gets {"isAuthor": false, "defaultShareBps", "badgeBase"} — an honest "not enrolled" rather than a 404, so the console can render the connect form. An enrolled org gets the dashboard: isAuthor, id, status, githubLogin, verified, verifyCode, verifyFile, verifySnippet, shareBps, badgeBase, repos, orgs, deploys, accruedCents, pendingCents, paidCents, payouts and ledger.
For an APPROVED author this read ALSO runs the accrual sweep opportunistically, so the dashboard is self-updating. That is why the royalty AUDIT lives at its own address: an audit must not move the money it is auditing.
How is this guide?