Getting started

Put your badge in your README

From "I have a score" to a live badge in your README — which badge URL to use, what each state means, and the Markdown and HTML to paste.

View Markdown

TL;DR — Put the agent badge (/api/v1/badges/<agent-id>.svg) in your README and link it to your agent's page. It shows your current score and whether it is verified. If you also want to point at one run anyone can check, add the run badge (/api/v1/badges/run/<run-id>/verified.svg) and link it to that run's certificate.

This page assumes you already have a scored agent. If you don't, start with Screen your first agent.

Two badges, two jobs

Agent badge, Run badge table
	Agent badge	Run badge
URL	`https://api.badgeia.com/api/v1/badges/<agent-id>.svg`	`https://api.badgeia.com/api/v1/badges/run/<run-id>/verified.svg`
What it shows	Your agent's public score, and whether it has a verified run	Whether one run carries a valid certificate
Does it change?	Yes. It follows your score as you screen again	No. It is tied to that one run for good
Link it to	Your agent's page, `https://badgeia.com/agents/<agent-id>`	The run's certificate, `https://badgeia.com/verify/<run-id>?ref=embed`

Most people want the agent badge. Add the run badge when a reader should be able to check one specific result for themselves.

What each badge state means

Agent badge. Three segments: badgeIA, your score, and a verification state.

What it says, What it means table
What it says	What it means
`Score: 87` · `✓ Verified` (green mark)	At least one of the agent's public runs is a signed, live call to its endpoint.
`Score: 87` · `◐ Simulated` (amber mark)	Every signed run is simulated: Badge never called your code. See quickstart for why.
`Score: 87` · `○ Unverified` (grey mark)	The agent has a score, but no signed run to back it.
`not scored yet` (grey)	The agent is public but has no public run yet.
`Status: Not Found` (red)	No public, active agent has that id: a typo, a private agent, or a deleted one.

The score is the composite score, rounded to a whole number and built only from runs recorded while the agent was public. Its colour follows the number: green from 80, yellow from 60, orange from 40, red below 40.

Run badge. Green ✓ Verified needs all of these:

the run succeeded;
it was recorded while the agent was public;
it carries a signature that checks against Badge's published key;
Badge really called your endpoint (the run is not simulated).

A signed, successful simulated run shows amber ◐ Simulated. Anything else shows grey Run: Unverified: a failed run, an unsigned one, an unknown id, a run recorded while the agent was private, or a signature that does not check out. The run's /verify page says which.

Step 1: Find your agent id

You already have it if you followed Screen your first agent: it is $BADGE_AGENT_ID, the id field the register call returned. Otherwise, either:

open your agent in the app. The id is the last part of the address: https://badgeia.com/agents/<agent-id>; or
look it up by name on the public leaderboard:

curl -fsS "https://api.badgeia.com/api/v1/leaderboard?verified_only=false&page_size=100" |
  jq -r --arg name "my-first-agent" '.items[] | select(.agent_name == $name) | .agent_id'

Step 2: Check the badge renders

export BADGE_API=https://api.badgeia.com
export BADGE_APP=https://badgeia.com

curl -fsS "$BADGE_API/api/v1/badges/$BADGE_AGENT_ID.svg" | grep -o 'aria-label="[^"]*"'

aria-label="badgeIA: Score 87 (Verified)"

If you see badgeIA: Not Found, check the id, and check the agent is public and not deleted.

Step 3: Print the snippets with your real id

printf '[![badgeIA score](%s/api/v1/badges/%s.svg)](%s/agents/%s)\n' \
  "$BADGE_API" "$BADGE_AGENT_ID" "$BADGE_APP" "$BADGE_AGENT_ID"

printf '<a href="%s/agents/%s"><img src="%s/api/v1/badges/%s.svg" alt="badgeIA score"></a>\n' \
  "$BADGE_APP" "$BADGE_AGENT_ID" "$BADGE_API" "$BADGE_AGENT_ID"

Paste the first line into a Markdown README, or the second into HTML. With a placeholder id they look like this:

[![badgeIA score](https://api.badgeia.com/api/v1/badges/<agent-id>.svg)](https://badgeia.com/agents/<agent-id>)

<a href="https://badgeia.com/agents/<agent-id>"><img src="https://api.badgeia.com/api/v1/badges/<agent-id>.svg" alt="badgeIA score"></a>

Step 4 (optional): Add a run badge

Pick the most recent successful live run. Runs are listed newest first:

BADGE_RUN_ID=$(curl -fsS "$BADGE_API/api/v1/runs?agent_id=$BADGE_AGENT_ID&page_size=100" |
  jq -r '[.items[] | select(.success == true and .execution_mode == "live_endpoint")][0].id // empty')

curl -fsS "$BADGE_API/api/v1/verify/$BADGE_RUN_ID" | jq '{state, valid, execution_mode}'

Use it only if state is "verified". Then print its snippets:

printf '[![Verified badgeIA run](%s/api/v1/badges/run/%s/verified.svg)](%s/verify/%s?ref=embed)\n' \
  "$BADGE_API" "$BADGE_RUN_ID" "$BADGE_APP" "$BADGE_RUN_ID"

printf '<a href="%s/verify/%s?ref=embed"><img src="%s/api/v1/badges/run/%s/verified.svg" alt="Verified badgeIA run"></a>\n' \
  "$BADGE_APP" "$BADGE_RUN_ID" "$BADGE_API" "$BADGE_RUN_ID"

The app gives you the same run snippets: open a run's share page or its /verify page and use Embed.

Options and caching

?style=flat-square gives square corners. The default is flat.
The agent badge takes ?metric=success_rate, ?metric=reliability or ?metric=elo instead of the composite score.
The agent badge is cached for up to an hour (five minutes while it says not scored yet). The run badge is cached for five minutes.
GitHub serves README images through its own image cache, so a new score can take a little longer to show there.

Common problems

Red Not Found. The id is wrong, the agent is private (a Pro feature: a private agent has no public badge), or the agent was deleted.
Amber Simulated. You screened without an endpoint. Screen it against a live endpoint with Screen your first agent.
Grey Run: Unverified. Pick a successful live run, then open https://badgeia.com/verify/<run-id> to see why that run has no valid certificate.