Skip to Content
PersonaMark docs
Settings

API

Start audits and read their results from outside PersonaMark, with a key for one site.

The API lets something outside PersonaMark start an audit of a site and read its results. For example, a GitHub workflow can audit the site after every deploy and report whether the score went down. It works with a key you make in the site's Settings › API tab.

A key reaches one site and no other. It can read that site's audits, start a new one, check the site's ownership, and audit or run personas on a pull request's preview, and nothing else: it can't change settings, mark issues, run personas on the live site or see other sites.

Make a key

Only an owner can make or revoke keys.

Open the site's Settings › API tab.

Give the key a name that says where it's used, like GitHub Actions, and choose Make a key.

Copy the key, which starts with pm_, and store it as a secret where it's used.

The key is shown once. PersonaMark keeps only a fingerprint of it, so if you lose it, revoke it and make another. The list shows each key's name, its first characters, when it was made and when it was last used. A site can have up to 10 keys.

Revoking a key takes effect at once: anything using it is refused from then on.

Send a request

Send the key in an Authorization header to https://work.personamark.app/api/v1/…:

curl -H "Authorization: Bearer $PERSONAMARK_API_KEY" \
  https://work.personamark.app/api/v1/site

Every response is JSON. A request that fails has an error with our own message. A missing, unknown or revoked key gets a 401, and an audit or job of another site gets the same 404 as one that doesn't exist.

RequestWhat it does
GET /siteThe site's domain, whether it's verified, its verification meta tag's metaName and metaContent, and its latest audit.
POST /site/verifyChecks ownership now, as Check ownership does, and answers with status (verified, not_found or unreachable) and verified.
GET /audits?page=The site's audits, newest first, 20 at a time, with total.
POST /auditsStarts an audit and answers 202 with its jobId.
GET /jobs/{jobId}The audit's progress: status (queued, running, succeeded, failed or cancelled), its stage, and auditId once it's done.
GET /audits/{id}The audit's score, its scores by area, its issues by severity, and its checks in the order of the To do tab.
GET /audits/{id}/compareThe audit against the one before it: the score change, each area's change, and the issues that are new, regressed or fixed, by check.
GET /audits/{id}/issuesEvery issue with its status, 100 at a time. Filter with check, severity and status (new, regressed, recurring, changed or intended).
GET /audits/{id}/pagesOne page, named by ?url=: its issues by check and its title and description rewrites.

compare takes ?vs= with the id of an earlier complete audit to compare with that one instead. It follows the same rules as the audit's Summary:

  • A partial audit's score, or two audits scored by different rules, isn't compared, so change is null.
  • Issues you've marked intended are left out.
  • An issue is fixed only if this audit could read its page.

Each check lists at most 20 of its pages, and pages counts them all. Every check in these responses has an appUrl, which opens that check's issues in PersonaMark.

pages matches url without its fragment or tracking parameters like utm_source, so a campaign link finds the page. A page that redirected is found by either address. It leaves out issues you've marked intended, and answers 404 when the audit has neither issues nor rewrites for the page, and 400 without a url. Each rewrite has title, description, its status on the To do tab, an appUrl, and source set to model_suggestion: a model wrote it, so review it before you use it.

POST /site/verify un-verifies the site when it finds no proof, and changes nothing when it couldn't run the check, as Check ownership does. See Prove you own the site.

Starting audits

POST /audits runs the same audit as Run audit. It's refused:

  • with 409 if the site isn't verified
  • with 409 and the running audit's jobId if an audit is already going, so you can wait on that one instead
  • with 429 if the key has started 24 audits and preview runs in the last 24 hours

An audit takes a few minutes. Poll GET /jobs/{jobId} every 20 seconds or so until status is succeeded, then read GET /audits/{auditId}/compare. When stalled is true, the audit has been waiting for a while and may not start soon.

Audit a preview deployment

A pull request's preview deployment can be audited before it merges and compared with your latest audit. An owner first allows the preview's hosts in Settings › Crawling, and the preview must carry the site's verification meta tag; see Preview deployments.

RequestWhat it does
POST /previewsStarts a preview audit from JSON: url, and optionally ref, sha and pull_request to label it. Answers 202 with previewId.
GET /previews/{id}Its status, stage, and once it's done its score and productionScore.
GET /previews/{id}/compareThe preview against production, in the same shape as compare: the score change and the issues new, back or fixed, by check.

POST /previews is refused with 422 for a URL that isn't https on one of the site's preview hosts, and with 409 and that preview's ids while the same preview is already being audited. It counts towards the key's 24 a day.

A preview audit crawls the preview the way an audit crawls the site, but reads it as if it were production, so its issues line up with your latest audit's, and issues you've marked intended stay that way. Google can't reach a protected preview, so there's no PageSpeed: the preview's score and the production score it's compared with both leave performance out, which is why productionScore can differ from your latest audit's score. Vercel marks every preview noindex with a header, which the audit ignores; a robots meta tag in the page still counts. Preview audits are listed on the Audits tab and never count as one of the site's audits.

Run a persona on a preview

A pull request can break a journey without adding a single SEO issue: the signup button moves, or the checkout form stops submitting. To catch that before it merges, send a persona at a goal on the preview and compare the run with that pair's last scored run on the live site. It works like an end-to-end test, except the check is a goal in plain words rather than a script.

The preview needs the same setup as a preview audit (allowed hosts and the meta tag), and the goal must start on this site.

RequestWhat it does
GET /personasThe project's personas and the goals that start on this site, with their ids. signsIn marks a goal that uses a test account.
POST /preview-runsStarts a run from JSON: url, persona_id, goal_id, and optionally ref, sha and pull_request. Answers 202 with previewRunId.
GET /preview-runs/{id}Its status, and once it's done its run and production, each with outcome, score, areas and friction, and scoreChange.

friction counts the problems the run hit by severity (blocking, moderate, minor) and lists the steps they happened at. production is null when the pair has never been scored on the live site, and scoreChange is null until both runs have a score. production.url opens that run in PersonaMark.

POST /preview-runs is refused with 422 for a URL that isn't https on one of the site's preview hosts, with 404 for a persona and goal that aren't this site's, and with 409 and the run's ids while the same persona is already trying the same goal on that preview. It counts towards the key's 24 a day.

What's the same as any run: the guardrails, the caps of 40 steps, 8 minutes and $2 of model calls, and at most two runs going at once across your organization. What's different:

  • It stays on the preview's host. A goal that needs your app on another subdomain can't get there, and says so as friction.
  • No test-account logins unless an owner allows them. A goal that signs in is refused with 422 until an owner turns on logins in Preview deployments, since the preview runs code nobody has merged yet.
  • It's kept apart from your runs. Preview runs don't appear on the Scores tab, in past runs, deltas, the weekly digest or alerts, and a later preview still compares with the live site. Their cost shows under Preview runs in Model spend.

Each run is several model calls, so pick a few pairs that cover the journeys you'd hate to break, rather than every persona at every goal. The score is a model's judgement, not a measurement: a change of a few points can be noise, and a new blocking problem or an outcome that went from completed to gave_up is the stronger signal.

Run it after a deploy

The PersonaMark audit action does all of this in a GitHub workflow: it starts an audit, waits for it, and writes what changed since the audit before into the job's summary. It also comments the same summary on the pull request the deployed commit came from, or on the commit when no pull request has it, so whoever made the change sees it.

Make a key for the site, as in Make a key. The site must be verified.

In your GitHub repository, open Settings › Secrets and variables › Actions and add the key as a secret named PERSONAMARK_API_KEY.

Add the workflow below as .github/workflows/personamark.yml, so it runs once your production deploy is live.

Deploy to production. When the workflow finishes, the pull request gets a comment, and the run's summary has the same: the score, its change and the issues by check, with a link to the audit.

For a site on Vercel:

name: PersonaMark audit

on:
  deployment_status:

jobs:
  audit:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment == 'Production'
    runs-on: ubuntu-latest
    timeout-minutes: 40
    permissions:
      pull-requests: write # comment on the pull request
      contents: write # or on the commit, when there's no pull request
    steps:
      - uses: function-form/personamark-action@v1
        with:
          api-key: ${{ secrets.PERSONAMARK_API_KEY }}
          fail-on: new-high

Without those permissions, the step can't comment: it says so in a warning and carries on. Set comment: false to keep the result to the run's summary.

fail-on decides when the step fails:

  • none, the default: never, only report
  • new-high: when an issue of high severity is new or back
  • score-drop:<n>: when the score fell by n or more
  • run-failed: when a persona didn't reach its goal on the preview, though it does on the live site (or has never run there)
  • run-score-drop:<n>: when a persona's score on the preview fell by n or more against the live site's

To use several, separate them with commas. If the audit doesn't finish within timeout-minutes (30 by default), the step stops waiting. The audit carries on in PersonaMark, and the step passes unless fail-on asks for something.

This audits the site's own domain, so run it after a production deploy. To audit a pull request's preview before it merges, give the action preview-url, as in the action's README; see Audit a preview deployment for what that needs first.

With preview-url, personas also sends personas at their goals on the preview: one <persona-id>:<goal-id> pair a line, with the ids from GET /personas, at most 5.

- uses: function-form/personamark-action@v1
  with:
    api-key: ${{ secrets.PERSONAMARK_API_KEY }}
    preview-url: ${{ github.event.deployment_status.environment_url }}
    personas: |
      3f2b8c1e-7a4d-4e9b-8c21-5d6f7a8b9c0d:8b0f3c2e-4f0a-4f7e-9f61-0d1d3a8f5b21
    fail-on: new-high, run-failed

The comment then has a table under the preview audit with each run's outcome, score, change and problems, and a link to the live site's run it was compared with. See Run a persona on a preview for what a run there can and can't do. run-failed is the steadier rule: a model's score can move a few points between runs of the same page.

If something goes wrong

What the step saysWhat to do
Could not start an audit: Send a live…The secret is missing, misspelled or revoked. Make a new key and update the secret.
Verify this site…Prove ownership in the site's Settings › General, then deploy again.
…24 audits and runs in the last 24 hoursThe key's daily limit. A workflow that runs on every push can reach it; run it on production deploys only.
…still queued…The audit hasn't started within the timeout. It will still run; its result is on the site's Audits tab.
This is the site's first complete auditNothing to compare yet. The next run reports changes.

Use it from an AI assistant

The same key works with an MCP server at https://work.personamark.app/api/mcp, so an assistant like Claude Code can read the site's audits and start one. To add it to Claude Code:

claude mcp add --transport http personamark https://work.personamark.app/api/mcp \
  --header "Authorization: Bearer $PERSONAMARK_API_KEY"

Other assistants that support remote MCP servers over HTTP take the same address and header.

ToolWhat it does
get_siteThe site's domain, whether it's verified, and its latest audit.
list_auditsThe site's audits, newest first.
get_auditAn audit's score, scores by area, and the checks to fix, in order.
get_audit_pageOne page's issues by check, and its title and description rewrites.
list_issuesAn audit's issues with their status, filtered by check and severity.
compare_auditsWhat changed since the audit before, or since one you name.
start_auditStarts an audit.
verify_siteChecks the site's ownership now.
get_audit_jobAn audit's progress, and its id once it's done.
start_preview_auditStarts an audit of a preview deployment.
get_previewA preview audit's progress and score.
compare_previewWhat a preview would change against production.
list_personasThe personas and the goals that start on this site, with their ids.
start_preview_runSends a persona at a goal on a preview deployment.
get_preview_runA preview run's outcome and score beside production's.

Only the three that start something and verify_site do anything but read. The tools return the same things as the requests above, by the same rules.

What responses contain

Responses carry our own labels, scores and page addresses, never what a page wrote. An issue's message, page titles and Search Console figures aren't part of the API. A page's title and description rewrites are, marked model_suggestion because a model wrote them. The model's reasoning and its other notes aren't.

A preview run gives its outcome, scores and friction counts, never the model's summary, friction points or recommendations. A model wrote those after reading the preview, and a page can steer it, so they'd be unsafe in a pull request comment that anyone with access to the repository reads. GET /personas returns your own persona names and goal sentences.

On this page