Trust Badge

Add a dynamic Oathe trust badge to your README showing your skill's score and verdict.

Overview

The Oathe trust badge is a dynamic image that displays your skill’s current trust score and verdict. It updates automatically after every new audit and can be embedded in any README, documentation page, or website.

Markdown Syntax

Use this in any Markdown file (GitHub README, docs site, etc.):

[![Oathe Trust Score](https://oathe.ai/api/badge?skill_url=https://github.com/your-org/your-skill)](https://oathe.ai/skills?url=https://github.com/your-org/your-skill)

The badge image is served at:

https://oathe.ai/api/badge?skill_url=<encoded-skill-url>

The link wrapping it points to the full audit report on Oathe.

Shields.io Integration

If you prefer to use the Shields.io endpoint (for consistent styling with your other badges), use the audit engine’s JSON endpoint instead:

[![Oathe Trust Score](https://img.shields.io/endpoint?url=https://audit-engine.oathe.ai/api/badge/your-org/your-skill)](https://oathe.ai/skills?url=https://github.com/your-org/your-skill)

Replace your-org/your-skill with your GitHub or ClawHub slug. See the Badge API reference for the full endpoint specification.

HTML Syntax

For HTML pages or sites that do not render Markdown:

<a href="https://oathe.ai/skills?url=https://github.com/your-org/your-skill">
  <img
    src="https://oathe.ai/api/badge?skill_url=https://github.com/your-org/your-skill"
    alt="Oathe Trust Score"
  />
</a>

Badge Colors

The badge color reflects the verdict from the most recent completed audit:

VerdictColorHexMeaning
SAFEbrightgreen#4c1No significant findings
CAUTIONyellow#dfb317Minor findings, generally safe
DANGEROUSorange#fe7d37Notable behavioral concerns
MALICIOUSred#e05d44Dangerous behavior detected
NOT SCANNEDlightgrey#9f9f9fNo completed audit exists yet

The badge label always reads oathe and the value shows the numeric score (e.g., 92/100) alongside the verdict.

Caching Behavior

Badge responses are cached at two levels:

  1. Oathe server cache: 1-hour TTL. After a new audit completes, the cache is invalidated and the next request returns the updated badge.
  2. Shields.io / CDN cache: If you route through Shields.io or a CDN, their own caching layer applies. Shields.io typically caches for 300 seconds.

In practice, a badge updates within a few minutes of a new audit completing. If you need an immediate refresh during testing, append a cache-busting query parameter:

https://oathe.ai/api/badge?skill_url=https://github.com/your-org/your-skill&_t=1700000000

Automatic Updates

You do not need to take any manual action to update the badge. The flow is:

  1. A new audit completes (triggered manually, by webhook, or by CI).
  2. Oathe updates the stored score and verdict for that skill URL.
  3. The next badge request after cache expiry returns the new values.

If you have webhooks configured (see CI/CD Integration), the badge stays current with every push or release automatically.

Troubleshooting

  • Badge shows “not scanned”: The skill URL has no completed audit. Submit an audit first.
  • Badge shows an old score: Wait for the 1-hour cache TTL to expire, or use a cache-busting parameter.
  • Badge does not render in GitHub: Make sure the URL is not blocked by a content security policy. GitHub allows images from external hosts in READMEs.