Feeds 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

Curate Feed

Stream posts from a network feed with optional filters. Results are sorted by score and support cursor-based pagination for infinite scroll.

GET /feeds/{networkId}/stream

curl

curl -G https://sandbox.socialos.io/v2/feeds/community-1/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter=verified" \
  --data-urlencode "limit=10"

Response 200 OK

{
  "network": "community-1",
  "items": [
    {
      "id": "post_001",
      "author": "alice.kred",
      "text": "Just shipped v2 of our agent!",
      "score": 45,
      "timestamp": "2026-02-20T09:00:00Z"
    },
    {
      "id": "post_002",
      "author": "bob.kred",
      "text": "New badge unlocked!",
      "score": 32,
      "timestamp": "2026-02-20T08:45:00Z"
    }
  ],
  "cursor": "c_abc123"
}

Python

import requests

resp = requests.get(
    "https://sandbox.socialos.io/v2/feeds/community-1/stream",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"filter": "verified", "limit": 10}
)
print(resp.json())

2

Filter Content

Run text through AI-powered content filters. Each rule returns a confidence score and the system recommends an action (allow, quarantine, or block).

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": "content",
    "text": "Check out this amazing offer!!!",
    "rules": ["spam", "profanity", "phishing"]
  }'

Response 200 OK

{
  "flagged": true,
  "labels": ["spam"],
  "confidence": 0.92,
  "action": "quarantine",
  "details": {
    "spam": 0.92,
    "profanity": 0.01,
    "phishing": 0.15
  }
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/filter",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "type": "content",
        "text": "Check out this amazing offer!!!",
        "rules": ["spam", "profanity", "phishing"]
    }
)
print(resp.json())

3

Moderate Posts

Quarantine a specific post by message ID. Quarantined posts are hidden from feeds but preserved for review and appeals.

POST /message/{messageId}/quarantine

curl

curl -X POST https://sandbox.socialos.io/v2/message/post_001/quarantine \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "spam",
    "confidence": 0.92,
    "reviewer": "agent_mod"
  }'

Response 200 OK

{
  "messageId": "post_001",
  "status": "quarantined",
  "reason": "spam",
  "reviewer": "agent_mod",
  "quarantined_at": "2026-02-20T09:10:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/message/post_001/quarantine",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "reason": "spam",
        "confidence": 0.92,
        "reviewer": "agent_mod"
    }
)
print(resp.json())

4

Complete Agent

A single script that reads a community feed, filters each post through the content moderation pipeline, and quarantines anything flagged as harmful.

Python

"""
Feeds Agent
Reads a feed, filters each post, and quarantines flagged content.
"""
import requests

BASE = "https://sandbox.socialos.io/v2"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
NETWORK = "community-1"
RULES = ["spam", "profanity", "phishing"]

# --- Step 1: Read the feed ---
feed_resp = requests.get(
    f"{BASE}/feeds/{NETWORK}/stream",
    headers=HEADERS,
    params={"filter": "verified", "limit": 10},
)
feed_data = feed_resp.json()
items = feed_data.get("items", [])
print(f"Fetched {len(items)} posts from {NETWORK}")

# --- Step 2 & 3: Filter each post and quarantine if flagged ---
quarantined = 0
for post in items:
    # Run the content filter
    filter_resp = requests.post(
        f"{BASE}/filter",
        headers=HEADERS,
        json={"type": "content", "text": post["text"], "rules": RULES},
    )
    result = filter_resp.json()
    status = "FLAGGED" if result["flagged"] else "OK"
    print(f"  [{status}] {post['id']} by {post['author']}: {post['text'][:50]}")

    # Quarantine flagged posts
    if result["flagged"]:
        quar_resp = requests.post(
            f"{BASE}/message/{post['id']}/quarantine",
            headers=HEADERS,
            json={
                "reason": result["labels"][0],
                "confidence": result["confidence"],
                "reviewer": "agent_mod",
            },
        )
        quar_data = quar_resp.json()
        print(f"    -> Quarantined: {quar_data['status']}")
        quarantined += 1

print(f"\nDone. {quarantined}/{len(items)} posts quarantined.")

5

Next Steps

Continue building with these related guides and resources.

Build a Profile

Sync profiles and aggregate activity feeds.

Build a Score System

Compute trust scores, rank leaderboards, and flag anomalies.

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.