Score Build Guide

0

Prerequisites

You need a SocialOS API key to use these endpoints. If you don't have one yet, follow the Agent Quick Start to get your free sandbox key in under 2 minutes.

Base URL: https://sandbox.socialos.io/v2

1

Compute Score

Update a user's trust score based on a specific action. The engine tracks the running total, calculates global rank and percentile, and returns the updated score immediately.

POST /gamification/score

curl

curl -X POST https://sandbox.socialos.io/v2/gamification/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "alice.kred",
    "metric": "trust",
    "action": "content_quality",
    "value": 10
  }'

Response 200 OK

{
  "userId": "alice.kred",
  "metric": "trust",
  "previous": 85,
  "current": 95,
  "rank": 8,
  "percentile": 92,
  "updated_at": "2026-02-20T11:00:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/gamification/score",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "userId": "alice.kred",
        "metric": "trust",
        "action": "content_quality",
        "value": 10
    }
)
result = resp.json()
print(result)

2

Rank Leaderboard

Fetch the top-ranked users for a given metric. The leaderboard endpoint returns ranked entries with scores, and the total number of participants in the pool.

GET /analytics

curl

curl "https://sandbox.socialos.io/v2/analytics?type=leaderboard&metric=trust&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "type": "leaderboard",
  "metric": "trust",
  "entries": [
    {"rank": 1, "userId": "bob.kred", "score": 99},
    {"rank": 2, "userId": "alice.kred", "score": 95},
    {"rank": 3, "userId": "charlie.kred", "score": 91}
  ],
  "total": 1024
}

Python

import requests

resp = requests.get(
    "https://sandbox.socialos.io/v2/analytics",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"type": "leaderboard", "metric": "trust", "limit": 5}
)
result = resp.json()
print(result)

3

Flag Anomalies

Scan for suspicious score changes within a time window. The filter endpoint flags users whose score deltas exceed a confidence threshold, helping detect gaming or abuse.

POST /filter

curl

curl -X POST https://sandbox.socialos.io/v2/filter \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "anomaly",
    "scope": "scores",
    "threshold": 0.8,
    "window": "24h"
  }'

Response 200 OK

{
  "flagged": [
    {
      "userId": "suspect_42",
      "metric": "trust",
      "delta": 55,
      "reason": "rapid_increase",
      "timestamp": "2026-02-20T08:00:00Z"
    }
  ],
  "scanned": 1024,
  "flagged_count": 1
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/filter",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "type": "anomaly",
        "scope": "scores",
        "threshold": 0.8,
        "window": "24h"
    }
)
result = resp.json()
print(result)

4

Complete Agent

A complete Score agent that computes a trust score, fetches the leaderboard, and scans for anomalies in one script.

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://sandbox.socialos.io/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def compute_score(user_id: str, action: str, value: int) -> dict:
    """Update a user's trust score for a given action."""
    resp = requests.post(f"{BASE}/gamification/score", headers=HEADERS, json={
        "userId": user_id,
        "metric": "trust",
        "action": action,
        "value": value
    })
    return resp.json()


def rank_leaderboard(metric: str = "trust", limit: int = 5) -> dict:
    """Fetch the top-ranked users for a metric."""
    resp = requests.get(f"{BASE}/analytics", headers=HEADERS, params={
        "type": "leaderboard",
        "metric": metric,
        "limit": limit
    })
    return resp.json()


def flag_anomalies(threshold: float = 0.8, window: str = "24h") -> dict:
    """Scan for suspicious score changes within a time window."""
    resp = requests.post(f"{BASE}/filter", headers=HEADERS, json={
        "type": "anomaly",
        "scope": "scores",
        "threshold": threshold,
        "window": window
    })
    return resp.json()


def main():
    # Step 1 - Compute a trust score
    score = compute_score("alice.kred", "content_quality", 10)
    print(f"Score: {score['previous']} -> {score['current']} (rank #{score['rank']})")

    # Step 2 - Check the leaderboard
    board = rank_leaderboard("trust", limit=5)
    print(f"\nLeaderboard ({board['total']} participants):")
    for entry in board["entries"]:
        print(f"  #{entry['rank']} {entry['userId']} - {entry['score']}")

    # Step 3 - Scan for anomalies
    anomalies = flag_anomalies(threshold=0.8, window="24h")
    print(f"\nScanned {anomalies['scanned']} users, flagged {anomalies['flagged_count']}:")
    for flag in anomalies["flagged"]:
        print(f"  {flag['userId']}: +{flag['delta']} ({flag['reason']})")


if __name__ == "__main__":
    main()

5

Next Steps

Continue building with these related guides and resources.

Build Identity

Verify credentials, score reputation, and resolve names.

Build a Sim Game

Run simulations, award points, and execute trades.

Agent Quick Start

Authentication, base setup, and your first API call in under 5 minutes.

Full API Reference

Complete documentation for every endpoint, parameter, and response type.

Pricing

Compare plans and find the right tier for your agent's usage volume.