Build on Ascended Social with a cleaner, calmer API guide.

Quick Start

1. Get an API Key

Create a free account at ascended.social, then go to Settings → Developer to generate a key. It will look like:

sk_live_REDACTED_EXAMPLE_KEY

2. Make your first request

The public health endpoint requires no key and tells you the API is up:

# No API key needed for health check
curl https://ascended.social/api/v1/healthz

# Response
{
  "status": "ok",
  "timestamp": "2026-06-03T12:00:00.000Z"
}

3. Fetch the post feed

curl -H "Authorization: Bearer sk_live_your_key" \
  "https://ascended.social/api/v1/posts?limit=5"

{
  "data": [
    {
      "id": "post_abc123",
      "authorId": "usr_xyz789",
      "content": "Just witnessed the most incredible sunrise 🌅",
      "createdAt": "2026-05-30T06:12:00.000Z"
    },
    // ... more posts
  ],
  "page": 0,
  "pageSize": 5,
  "hasMore": true
}

Authentication

Pass your API key as a Bearer token in the Authorization header on every request:

Authorization: Bearer sk_live_<your_key_here>

Key types

Key management

• Create and revoke keys at Settings → Developer
• You can have multiple keys (useful for separating services or environments)
• Revoked keys return 401 immediately and cannot be un-revoked
• last_used_at is updated on every valid request for auditing

Base URL

All API endpoints are served under:

https://ascended.social/api/v1

Example — the posts feed is at:

GET https://ascended.social/api/v1/posts

Versioning

The API version is embedded in the path (/api/v1). The current stable version is v1. We will not make breaking changes to v1 — any incompatible changes will be released under /api/v2 with ample advance notice.

Pagination

All list endpoints use page-based pagination. You control it with two query parameters:

Response envelope

Every paginated response wraps the array in a standard envelope:

{
  "data": [ /* array of results */ ],
  "page": 0,         // current page (0-indexed)
  "pageSize": 20,    // items per page you requested
  "hasMore": true    // false when you've reached the last page
}

Some endpoints add extra top-level keys (e.g. bookId in the chapters response, userId in character responses).

Walking all pages

async function fetchAll(endpoint) {
  const results = [];
  let page = 0;
  do {
    const res = await fetch(
      `https://ascended.social/api/v1/${endpoint}?page=${page}&limit=50`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );
    const json = await res.json();
    results.push(...json.data);
    if (!json.hasMore) break;
    page++;
  } while (true);
  return results;
}

const allPosts = await fetchAll('posts');

Rate Limits

Every response includes these headers so you can track consumption in real time:

X-RateLimit-Limit: 100             # requests allowed per minute
X-RateLimit-Remaining: 87          # requests left this minute
X-RateLimit-Remaining-Month: 9134  # requests left this month (Free/Pro)

Tiers

When you're rate limited

The API returns 429 Too Many Requests. The response includes a Retry-After header (seconds) and a JSON body:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded: 100 requests per minute",
  "tier": "free",
  "retryAfter": 60
}

Handling 429s in code

async function fetchWithRetry(url, opts, retries = 3) {
  const res = await fetch(url, opts);
  if (res.status === 429 && retries > 0) {
    const wait = 1000 * (parseInt(res.headers.get('Retry-After') || '60'));
    await new Promise(r => setTimeout(r, wait));
    return fetchWithRetry(url, opts, retries - 1);
  }
  return res;
}

Error Handling

All error responses share a consistent shape:

{
  "error": "Not found",      // short identifier
  "message": "Post not found"  // human-readable explanation
}

Robust error handling example

async function apiRequest(path, opts = {}) {
  const res = await fetch(`https://ascended.social/api/v1${path}`, {
    ...opts,
    headers: {
      Authorization: `Bearer ${process.env.ASCENDED_API_KEY}`,
      ...opts.headers,
    },
  });

  if (res.status === 404) return null;  // Not found — treat as absent
  if (res.status === 401) throw new Error('Invalid API key');
  if (res.status === 429) {
    const err = new Error('Rate limited');
    err.retryAfter = parseInt(res.headers.get('Retry-After') || '60');
    throw err;
  }
  if (!res.ok) throw new Error(`API error ${res.status}`);

  return res.json();
}

Privacy Model

The Ascended Social Public API is strictly read-only and returns only content users have made publicly visible:

• Private profiles are excluded from all responses (404 is returned)
• Direct messages and private posts are never accessible
• PII (email addresses, phone numbers, IP data) is stripped at the query level
• Row-Level Security (RLS) is enforced at the PostgreSQL layer — no code path can accidentally leak private data
• All API key usage is logged per-key for audit and abuse prevention

By using this API you agree to the API Terms of Use. Do not use the API to build surveillance tools, scrape data in bulk for resale, or contact users without their consent.

Health

{
  "status": "ok",
  "timestamp": "2026-06-03T12:00:00.000Z"
}

Users

curl -H "Authorization: Bearer sk_live_..." \
  https://ascended.social/api/v1/users/usr_abc123

{
  "data": [{ "id", "content", "createdAt", "updatedAt" }],
  "page": 0, "pageSize": 20, "hasMore": false
}

Posts

Books

{
  "bookId": "book_abc123",
  "data": [{ "id", "bookId", "title", "createdAt" }],
  "page": 0, "pageSize": 20, "hasMore": false
}

Videos

Live Sessions

SABS — Soul-Bound Ascension System

SABS is Ascended Social's spiritual progression game. Users create characters, join campaigns, and level up through real-world spiritual practices.

{
  "userId": "usr_abc123",
  "data": [{ "id", "userId", "name", "createdAt" }],
  "page": 0, "pageSize": 20, "hasMore": false
}

Sigils

Sigils are unique spiritual symbols minted by users. They can be offered for trade with other members of the community.

Events

Public ceremonies and rituals hosted on Ascended Social. Seances are always private and are never returned by these endpoints. Draft and cancelled events are also excluded.

Network Bots

The Ascended Social bot platform lets you build automated agents that participate in networks — sending messages, responding to slash commands, and reacting to events via webhooks.

Lifecycle at a glance

1. Create a bot — POST /bots
2. Issue a bot token with the scopes you need — POST /bots/{botId}/tokens
3. Install the bot in a network (you must be owner/admin) — POST /networks/{networkId}/bots/{botId}
4. Send messages as the bot — POST /bot/networks/{networkId}/channels/{channelId}/messages
5. Register slash commands and handle interactions via your webhook
6. Uninstall or delete when done — DELETE /networks/{networkId}/bots/{botId}

Bot Tokens

Bot tokens (bt_live_...) are separate from user API keys and must be used for all runtime bot actions. Issue them via POST /bots/{botId}/tokens.

Available scopes

Issue a token

curl -X POST https://ascended.social/api/v1/bots/<botId>/tokens \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["messages:write", "channels:read"],
    "label": "production"
  }'cURL

{
  "token": "bt_live_xxxxxxxxxxxxxxxxxxxx",
  "metadata": {
    "id": "tok_abc123",
    "scopes": ["messages:write", "channels:read"],
    "label": "production",
    "networkId": null,
    "expiresAt": null,
    "createdAt": "2026-06-10T00:00:00.000Z"
  }
}Response

⚠ The raw token value is returned only once. Store it securely (e.g. as an environment variable or in a secrets manager) — it cannot be retrieved again.

Use the token

// All bot runtime endpoints use bt_live_... instead of sk_live_...
const res = await fetch(
  "https://ascended.social/api/v1/bot/networks/<networkId>/channels/<channelId>/messages",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer bt_live_xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ content: "🌙 Daily lunar update" }),
  }
);JavaScript

Webhooks

Set a webhookUrl on your bot (or per-install) to receive real-time events over HTTPS. The URL must be publicly reachable and cannot point to private/RFC1918 addresses.

Signature verification

Every delivery includes an X-Ascended-Signature header. Verify it before processing:

// Node.js verification example
import { createHmac } from "node:crypto";

function verifyWebhook(rawBody: Buffer, sig: string, secret: string, timestamp: string) {
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return sig === `sha256=${expected}`;
}

// In your Express handler:
app.post("/hooks/ascended", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-ascended-signature"] as string;
  const ts  = req.headers["x-ascended-timestamp"]  as string;
  if (!verifyWebhook(req.body, sig, process.env.BOT_WEBHOOK_SECRET!, ts)) {
    res.status(401).end();
    return;
  }
  const event = JSON.parse(req.body.toString());
  // Handle event.type === "slash_command.invoked", "message.created", etc.
  res.json({ ok: true });
});Node.js

Retry policy

Failed deliveries are retried with exponential back-off at approximately 5 s → 30 s → 2 min → 10 min → 1 h → 1 h (6 attempts total). A delivery is considered failed if the webhook returns a non-2xx status or does not respond within the timeout.

Event types

Slash Commands

Register slash commands so network members can invoke your bot by typing /command-name in a channel. When a command is invoked, the platform sends a slash_command.invoked webhook event and your bot must respond within 3 seconds via POST /bot/interactions/{interactionId}/response.

Register a command (bot token)

// Register /transit in a network
await fetch(
  "https://ascended.social/api/v1/bot/networks/<networkId>/slash-commands",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer bt_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "transit",
      description: "Get today's planetary transit report",
      usage: "/transit [date]",
    }),
  }
);JavaScript

Handle the invocation

// Your webhook receives:
{
  "type": "slash_command.invoked",
  "interactionId": "int_abc123",
  "commandName": "transit",
  "args": "2026-06-10",
  "networkId": "net_xyz",
  "channelId": "ch_123",
  "userId": "usr_invoker"
}

// Respond within 3 seconds:
await fetch("https://ascended.social/api/v1/bot/interactions/int_abc123/response", {
  method: "POST",
  headers: { Authorization: "Bearer bt_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ content: "🌙 Moon enters Scorpio at 14:32 UTC" }),
});JavaScript

Bots — Management

All endpoints below use your user API key (Authorization: Bearer sk_live_...).

{
  "name": "AstrologyBot",
  "username": "astrology_bot",
  "description": "Daily planetary transits",
  "webhookUrl": "https://yourserver.example.com/hooks/ascended",
  "isPublic": true
}

{
  "scopes": ["messages:write", "channels:read"],
  "label": "production",
  "networkId": "net_xyz",       // optional — lock to one network
  "expiresAt": "2027-01-01T00:00:00Z"  // optional
}

{
  "permissions": ["read_messages", "write_messages", "read_members"],
  "webhookUrl": "https://yourserver.example.com/hooks/ascended"  // optional override
}

Bots — Runtime Actions

All endpoints below require a bot token (Authorization: Bearer bt_live_...). Network scope and scopes are enforced per token.

{ "content": "🌙 Moon enters Scorpio at 14:32 UTC" }

{
  "name": "transit",
  "description": "Get today's planetary transit report",
  "usage": "/transit [date]"
}

JavaScript / TypeScript

Minimal API client

A lightweight wrapper you can copy into any project:

// ascended-api.ts
const BASE = "https://ascended.social/api/v1";

async function ascendedFetch(path: string, params: Record<string, any> = {}) {
  const url = new URL(BASE + path);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));

  const res = await fetch(url.toString(), {
    headers: { Authorization: `Bearer ${process.env.ASCENDED_API_KEY}` },
  });

  if (res.status === 429) {
    const retry = parseInt(res.headers.get("Retry-After") || "60");
    throw Object.assign(new Error("Rate limited"), { retryAfter: retry });
  }
  if (!res.ok) throw new Error(`Ascended API error: ${res.status}`);
  return res.json();
}

// Usage
const posts = await ascendedFetch("/posts", { limit: 50, page: 0 });
const user  = await ascendedFetch(`/users/${userId}`);
const books = await ascendedFetch("/books", { page: 0 });

Fetch all pages (TypeScript)

async function fetchAllPages<T>(path: string): Promise<T[]> {
  const results: T[] = [];
  let page = 0;
  while (true) {
    const res: { data: T[]; hasMore: boolean } =
      await ascendedFetch(path, { page, limit: 50 });
    results.push(...res.data);
    if (!res.hasMore) break;
    page++;
  }
  return results;
}

const allBooks = await fetchAllPages<Book>("/books");

Next.js API Route example

// app/api/feed/route.ts
import { NextResponse } from "next/server";

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const page = searchParams.get("page") || "0";

  const res = await fetch(
    `https://ascended.social/api/v1/posts?page=${page}&limit=20`,
    { headers: { Authorization: `Bearer ${process.env.ASCENDED_API_KEY}` },
      next: { revalidate: 60 } }  // Cache for 60s
  );

  if (!res.ok) return NextResponse.json({ error: "upstream error" }, { status: 502 });
  return NextResponse.json(await res.json());
}

Python

Using httpx

# pip install httpx
import httpx, os

BASE = "https://ascended.social/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ASCENDED_API_KEY']}"}

def fetch_posts(page=0, limit=20):
    r = httpx.get(f"{BASE}/posts", params={"page": page, "limit": limit}, headers=HEADERS)
    r.raise_for_status()
    return r.json()

def fetch_user(user_id: str):
    r = httpx.get(f"{BASE}/users/{user_id}", headers=HEADERS)
    if r.status_code == 404:
        return None
    r.raise_for_status()
    return r.json()

def fetch_all_books():
    books, page = [], 0
    while True:
        resp = fetch_posts.__globals__['httpx'].get(
            f"{BASE}/books", params={"page": page, "limit": 50}, headers=HEADERS
        ).json()
        books.extend(resp["data"])
        if not resp["hasMore"]: break
        page += 1
    return books

# Example
feed = fetch_posts(limit=50)
print(f"Got {len(feed['data'])} posts, hasMore={feed['hasMore']}")

Using requests

# pip install requests
import requests, os

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {os.environ['ASCENDED_API_KEY']}"
})

BASE = "https://ascended.social/api/v1"

resp = session.get(f"{BASE}/posts", params={"page": 0, "limit": 20})
resp.raise_for_status()
data = resp.json()

for post in data["data"]:
    print(post["id"], post["content"][:60])

cURL

# Health check (no key needed)
curl https://ascended.social/api/v1/healthz

# Post feed
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  "https://ascended.social/api/v1/posts?limit=20&page=0"

# User profile
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/users/usr_abc123

# Books library
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  "https://ascended.social/api/v1/books?page=0&limit=50"

# Chapters in a book
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/books/book_abc123/chapters

# Video feed
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/videos

# Live sessions
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/live/sessions

# Public events (ceremonies + rituals)
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  "https://ascended.social/api/v1/events?limit=20&page=0"

# Single public event
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/events/evt_abc123

# SABS campaigns
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/sabs/campaigns

# SABS characters for a user
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/sabs/characters/by-user/usr_abc123

# Sigil trade
curl -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/sigils/trades/trade_abc123

# Save rate limit headers to a file for inspection
curl -D headers.txt -H "Authorization: Bearer $ASCENDED_API_KEY" \
  https://ascended.social/api/v1/posts -o /dev/null 2>&1
grep -i "X-RateLimit" headers.txt

Changelog

v1.0.0 — June 2026

• Initial public release of the Ascended Social Public API
• 15 read-only REST endpoints: users, posts, events (ceremonies & rituals), books, chapters, videos, live sessions, SABS campaigns, SABS characters, sigil trades, and health
• SHA-256 API key hashing for O(1) indexed key lookup
• Per-minute and per-month rate limiting with response headers
• Full usage tracking to api_usage table (per-request endpoint, method, status, response time)
• Row-Level Security enforced at the database layer for all API tables
• Interactive Swagger UI at api-docs.ascended.social
• OpenAPI 3.1 spec at api-docs.ascended.social/openapi.yaml
• MCP server at developers.ascended.social/mcp — 15 tools, 2 resources, 2 prompts for AI agent integrations
• Status monitoring at status.ascended.social

Support