Docs / Reference / Badges

/api/badges

Verification markers, status indicators, and content trust badges used across the Aevum Encyclopedia ecosystem. Integrate these into your client applications to reflect article credibility, AI enhancement levels, and editorial status.

Overview

Badges are machine-readable metadata objects that represent the verification state, editorial tier, and AI processing level of encyclopedia entries. They are returned alongside article payloads and can be requested independently.

HTTP / JSON 
// GET /api/badges
// Returns paginated list of available badge definitions
{
  "data": [
    {
      "id": "verified_source",
      "name": "Verified Source",
      "tier": "trust",
      "css_class": "badge-pill verified",
      "icon": "✓"
    }
  ],
  "meta": {
    "total": 12,
    "version": "2.4.1"
  }
}

Implementation

Client-Side Rendering

Use the provided CSS classes to maintain visual consistency across platforms. The badge-pill base class handles typography and spacing, while modifier classes control color and border states.

HTML / CSS 
<!-- Base structure -->
<span class="badge-pill verified" role="status" aria-label="Verified Source">
  ✓ Verified Source
</span>

/* CSS Variables for theming */
:root {
  --badge-bg: rgba(16,185,129,0.15);
  --badge-color: #10b981;
  --badge-border: 1px solid rgba(16,185,129,0.3);
}

API Integration Pattern

Fetch badge metadata dynamically using the article's badge_ids array. The endpoint resolves semantic labels, icons, and localization strings.

JavaScript / Fetch 
async function renderBadges(articleId) {
  const res = await fetch(`/api/articles/${articleId}/badges`);
  const badges = await res.json();
  
  return badges.data.map(b => `
    <span class="badge-pill ${b.css_class}" data-badge-id="${b.id}">
      ${b.icon} ${b.name}
    </span>
  `).join('');
}

Endpoints

Method Path Description Status
GET /api/badges Retrieve all available badge definitions with localization support Stable
GET /api/badges/{id} Fetch single badge metadata including CSS class and icon mapping Stable
GET /api/articles/{id}/badges Get resolved badges attached to a specific article Stable
POST /api/badges/validate Check if badge configuration matches current schema version Beta

Response Schema

JSON Schema (Simplified) 
{
  "BadgeObject": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "format": "slug" },
      "name": { "type": "string" },
      "icon": { "type": "string" },
      "css_class": { "type": "string" },
      "tier": { "type": "string", "enum": ["trust", "process", "access"] },
      "locales": { "type": "object", "additionalProperties": true }
    }
  }
}

Versioning & Deprecation

Badge definitions are versioned alongside API releases. Breaking changes to CSS class names or schema structure will be announced 6 months prior. Always request the latest version via the X-Aevum-Version: 2.4 header.

Changelog Snippet 
# v2.4.0 (2025-03-15)
- Added `premium_access` badge tier
- Deprecated `legacy_verified` → use `verified_source`
- Updated CSS variables for WCAG 2.1 AA contrast compliance

# v2.3.1 (2025-01-20)
- Patched localization fallback for `expert_reviewed`
- Reduced payload size by 18% via icon font optimization