Borealis Protocol API
Build trust-aware applications with the Borealis Protocol public API. Verify AI agent credentials, display trust badges, and integrate agent intelligence into your platform.
Getting Started
The Borealis Protocol API provides open access to agent verification data, marketplace listings, and trust metrics. All public endpoints require no authentication—perfect for building trust-aware integrations.
Borealis is a decentralized framework for verifying and benchmarking AI agents. The BM Score measures agent reliability, certification demonstrates audited compliance, and the Hedera ledger provides immutable verification records.
Authentication
Public API endpoints do not require authentication. All data is publicly accessible and suitable for third-party integrations.
Public Endpoints
These endpoints are available without any API key or authentication:
GET /v1/verify/:agentId- Verify agent statusGET /v1/verify/:agentId/badge.svg- Trust badge imageGET /v1/verify/:agentId/badge.js- Badge widgetGET /v1/agents/public- List certified agentsGET /v1/terminal/stats- Marketplace statisticsGET /v1/marketplace/listings- Marketplace listings
Authenticated Endpoints
To manage your own agent, deploy updates, and access private dashboard data, register an account at borealisprotocol.com and generate an API key. Authenticated endpoints support Bearer token authentication via the Authorization header.
Base URL
All API requests should be made to:
https://borealismark-api.onrender.com
Rate Limiting
Public API endpoints are rate limited to ensure fair usage and service stability.
| Endpoint Type | Limit | Window | Headers |
|---|---|---|---|
| Public Endpoints | 100 requests | 60 seconds | X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset |
| Badge Assets | 500 requests | 60 seconds | X-RateLimit-Limit, X-RateLimit-Remaining |
| Authenticated Endpoints | 1000 requests | 60 seconds | X-RateLimit-Limit, X-RateLimit-Remaining |
If you exceed the rate limit, the API will return a 429 status code. Respect the Retry-After header and implement exponential backoff in your client.
API Endpoints
Retrieve verification status and trust metrics for an AI agent. This is the core endpoint for third-party verification and trust gates.
| Parameter | Type | Description |
|---|---|---|
agentId |
string | The unique agent identifier (e.g., agent_abc123) |
curl -X GET https://borealismark-api.onrender.com/v1/verify/agent_abc123 \
-H "Accept: application/json"
{
"verified": true,
"agentId": "agent_abc123",
"name": "My AI Agent",
"bmScore": 82,
"tier": "Gold",
"certifiedAt": "2026-01-15T00:00:00Z",
"lastAudit": "2026-03-01T12:00:00Z",
"hedera": {
"transactionId": "[email protected]",
"topicId": "0.0.5678"
}
}
- Third-party verification of agent credentials
- Trust gates that require minimum BM Score
- Integration checks before routing requests
- Dashboard displays of agent trust metrics
- Automated audit trail checks
Returns an SVG trust badge that automatically updates when the agent's score changes. Perfect for embedding in web pages, READMEs, and marketing materials.
| Parameter | Values | Default | Description |
|---|---|---|---|
style |
flat, rounded, minimal |
flat |
Badge visual style |
theme |
dark, light |
dark |
Badge color theme |
curl -X GET https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.svg?style=rounded&theme=dark
Returns an SVG image with status code 200. The badge displays the agent's current BM Score and tier, automatically cached with appropriate headers.
- Project README badges showing agent certification
- Marketplace listings displaying trust score
- Partner integration pages showing verification status
- Email signatures and newsletters
- Live dashboards with auto-updating scores
Returns an interactive JavaScript widget that displays a rich badge with hover tooltip. The widget handles rendering and updates automatically.
<script src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.js"></script>
Injects an interactive badge element into the page that displays agent verification status. Hover shows detailed metrics including BM Score, tier, and last audit date.
- Interactive trust badges on landing pages
- Rich tooltips showing verification details
- Dynamic agent cards in marketplaces
- Integration verification in partner portals
Retrieve a paginated list of publicly listed certified agents. Supports filtering by tier and sorting by various criteria.
| Parameter | Type | Default | Description |
|---|---|---|---|
tier |
string | all |
Filter by tier: platinum, gold, silver, bronze |
limit |
number | 20 |
Number of results per page (max 100) |
page |
number | 1 |
Page number for pagination |
sort |
string | score |
Sort by: score, name, recent |
curl -X GET "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=20&page=1&sort=score" \
-H "Accept: application/json"
{
"agents": [
{
"agentId": "agent_abc123",
"name": "My AI Agent",
"bmScore": 82,
"tier": "Gold",
"certifiedAt": "2026-01-15T00:00:00Z"
}
],
"total": 150,
"page": 1,
"pages": 8
}
Retrieve global marketplace statistics including total agents, certification count, and tier distribution.
curl -X GET https://borealismark-api.onrender.com/v1/terminal/stats \
-H "Accept: application/json"
{
"totalAgents": 150,
"certifiedAgents": 89,
"averageScore": 72.4,
"tierDistribution": {
"platinum": 12,
"gold": 34,
"silver": 28,
"bronze": 15
}
}
- Dashboard widgets showing ecosystem health
- Landing page statistics and metrics
- Analytics and reporting tools
- Integration readiness checks
Retrieve marketplace agent listings with detailed information including pricing and categorization.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
number | 20 |
Number of results per page (max 100) |
page |
number | 1 |
Page number for pagination |
category |
string | all |
Filter by category |
curl -X GET "https://borealismark-api.onrender.com/v1/marketplace/listings?limit=20&page=1&category=all" \
-H "Accept: application/json"
{
"listings": [
{
"id": "listing_001",
"agentName": "CodeReview Pro",
"tier": "Gold",
"bmScore": 84,
"description": "Advanced code review assistant...",
"pricing": "free"
}
],
"total": 45
}
Error Handling
The API uses standard HTTP status codes to indicate success or failure. Always check the status code and handle errors gracefully.
| Status Code | Meaning | Description |
|---|---|---|
200 |
OK | Request succeeded |
400 |
Bad Request | Invalid parameters or malformed request |
401 |
Unauthorized | Missing or invalid authentication token |
404 |
Not Found | Agent or resource not found |
429 |
Too Many Requests | Rate limit exceeded. Check Retry-After header |
500 |
Server Error | Internal server error. Try again later |
Error Response Format
{
"error": {
"code": "AGENT_NOT_FOUND",
"message": "The requested agent does not exist",
"status": 404
}
}
Handling Errors in Your Code
async function verifyAgent(agentId) {
try {
const response = await fetch(
`https://borealismark-api.onrender.com/v1/verify/${agentId}`
);
if (!response.ok) {
const error = await response.json();
throw new Error(error.error.message);
}
return await response.json();
} catch (err) {
console.error('Verification failed:', err.message);
}
}
Badge Embedding
Display trust badges on your website, documentation, or marketplace to show agent verification status. Badges automatically update when the agent's score changes.
SVG Badge (Static)
Perfect for READMEs, documentation, and static pages.
[](https://borealisprotocol.com/verify/agent_abc123)
SVG Badge (HTML)
<a href="https://borealisprotocol.com/verify/agent_abc123">
<img src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.svg?style=rounded"
alt="BorealisMark Verified"
width="200"/>
</a>
JavaScript Widget (Interactive)
For rich interactive badges with tooltips and automatic updates.
<script src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.js"></script>
Badge Styling Options
| Style | Use Case | Example URL |
|---|---|---|
flat |
Default badge style | /badge.svg?style=flat |
rounded |
Rounded corners | /badge.svg?style=rounded |
minimal |
Compact design | /badge.svg?style=minimal |
React Component
import React from 'react';
export function AgentBadge({ agentId, style = 'flat' }) {
return (
<a href={`https://borealisprotocol.com/verify/${agentId}`}>
<img
src={`https://borealismark-api.onrender.com/v1/verify/${agentId}/badge.svg?style=${style}`}
alt="BorealisMark Verified"
width="200"
/>
</a>
);
}
Code Examples
Verify an Agent (JavaScript)
async function verifyAgent(agentId) {
const url = `https://borealismark-api.onrender.com/v1/verify/${agentId}`;
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
if (data.verified) {
console.log(`✓ ${data.name} is verified with BM Score: ${data.bmScore}`);
console.log(`Tier: ${data.tier}`);
} else {
console.log('Agent is not verified');
}
return data;
} catch (error) {
console.error('Verification failed:', error);
}
}
// Usage
verifyAgent('agent_abc123');
Check BM Score with Trust Gate (Python)
import requests
import time
def trust_gate(agent_id, min_score=70):
"""Verify an agent meets minimum trust score"""
url = f"https://borealismark-api.onrender.com/v1/verify/{agent_id}"
try:
response = requests.get(url, timeout=5)
response.raise_for_status()
data = response.json()
if data["verified"] and data["bmScore"] >= min_score:
return True, data
return False, "Insufficient trust score"
except requests.RequestException as e:
return False, str(e)
# Usage
passed, result = trust_gate("agent_abc123", min_score=75)
if passed:
print(f"✓ Agent {result['name']} approved")
else:
print(f"✗ Agent blocked: {result}")
List Certified Agents (cURL)
# Get top Gold tier agents sorted by score
curl -X GET "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=10&sort=score" \
-H "Accept: application/json" \
-H "User-Agent: MyApp/1.0"
# Pretty print with jq
curl -s "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=10" | jq '.agents[] | {name, bmScore, tier}'
SDKs & Libraries
Official SDKs and community libraries for integrating with Borealis Protocol.
Official SDKs for JavaScript, Python, and Go are in development. Check back soon for client libraries that streamline integration.
Using the API Without an SDK
The API is straightforward to use directly without any additional libraries. All endpoints are standard HTTP and return JSON, making integration simple with any programming language or HTTP client.
Recommended HTTP Clients
- JavaScript:
fetch(built-in), axios, node-fetch - Python:
requests, httpx, urllib - Go:
net/http, resty - Rust: reqwest, hyper
- cURL: For shell scripts and testing
Community Contributions
Have you built a wrapper library? Submit it to the Borealis Protocol GitHub and we'll feature it here.