Badges API · Gradaris Docs

Embed live GGS grade badges in your internal compliance dashboards, governance portals, or public-facing systems. Badges update automatically as assessment scores change. Available as SVG (for embedding) and JSON (for custom rendering).

Badge preview

Grade badges render as coloured labels. The left segment shows the agent identifier; the right segment shows the current grade with the corresponding color.

loan-eligibility-v2GGS A

fraud-detectionGGS B

credit-score-modelGGS C

onboarding-agentGGS D

legacy-classifierGGS F

SVG Endpoint

Returns an SVG image suitable for embedding directly in HTML, markdown, or documentation portals.

http

GET https://api.gradaris.com/v1/badges/{agent_id}/svg

# Example
GET https://api.gradaris.com/v1/badges/loan-eligibility-v2/svg
Authorization: Bearer grd_your_api_key_here

Embedding in HTML

html

<!-- Static embed (cached for 5 minutes) -->
<img
  src="https://api.gradaris.com/v1/badges/loan-eligibility-v2/svg"
  alt="GGS Grade: loan-eligibility-v2"
  height="20"
/>

<!-- With API key via query param (public dashboards) -->
<img
  src="https://api.gradaris.com/v1/badges/loan-eligibility-v2/svg?token=grd_pub_xxxx"
  alt="GGS Grade: loan-eligibility-v2"
  height="20"
/>

Embedding in Markdown

markdown

![GGS Grade](https://api.gradaris.com/v1/badges/loan-eligibility-v2/svg?token=grd_pub_xxxx)

JSON Endpoint

Returns the full assessment summary as JSON for custom badge rendering or dashboard integration.

http

GET https://api.gradaris.com/v1/badges/{agent_id}/json
Authorization: Bearer grd_your_api_key_here

Response schema

json

{
  "agent_id": "loan-eligibility-v2",
  "grade": "A",
  "score": 92,
  "tier_scores": {
    "tier_1_verified_controls": { "passed": true, "controls_passing": 4, "controls_total": 4 },
    "tier_2_empirical": { "score": 88, "confidence": "high" },
    "tier_3_structured": { "score": 90, "confidence": "medium" }
  },
  "methodology_version": "ggs-methodology-v1.2.0",
  "integrity_hash": "ggs:v1.2.0:sha256:a3f8c2d4...",
  "assessed_at": "2026-03-06T14:22:00Z",
  "next_assessment_due": "2026-04-06T14:22:00Z"
}

Authentication

Badges API supports two authentication modes depending on your use case:

Bearer token (header): Use your standard API key via the Authorization: Bearer header. Suitable for server-side rendering, internal dashboards, and CI/CD pipelines.
Public token (query param): Generate a read-only public badge token from the Gradaris dashboard under Settings → Badges → Public Tokens. Pass as ?token=grd_pub_xxxx. Scoped to specific agents and expirable. Suitable for public documentation or external portals.

Public badge tokens expose only the grade and score — not tier breakdowns, criterion details, or the integrity hash. Use the full API key endpoint when you need the complete assessment payload.

Query Parameters

Parameter	Type	Default	Description
`style`	string	`flat`	Badge style. Options: `flat`, `flat-square`, `for-the-badge`
`label`	string	agent_id	Override the left label text. URL-encoded.
`logo`	boolean	`false`	Include the Gradaris shield logo on the left segment.
`token`	string	—	Public badge token (alternative to Authorization header).
`cache`	integer	`300`	Cache TTL in seconds. Min 60, max 3600.

Example with parameters

http

GET https://api.gradaris.com/v1/badges/loan-eligibility-v2/svg
    ?style=for-the-badge
    &label=Loan%20Model%20Governance
    &logo=true
    &cache=600
    &token=grd_pub_xxxx

Rate limits

Badge endpoints are rate-limited per API key. Public badge token endpoints have lower limits than authenticated endpoints. Responses are cached at the CDN layer — cache TTL is set via the cache parameter and the Cache-Control response header. Contact us for rate limit details relevant to your use case.