Unified API Reference

Complete API documentation for all RitualOS ecosystem services. All services use OAuth 2.0 for authentication and return JSON responses.

Base URLs

---

ID Service APIs

Authentication

POST /api/oauth/authorize

Initialize OAuth 2.0 authorization flow.

Response: Redirects to authorization page or returns error

POST /api/oauth/token

Exchange authorization code for access token.

Response:

{
  "access_token": "rit_access_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rit_refresh_..."
}

GET /api/claims

Get user identity claims.

Response:

{
  "identityId": "usr_abc123",
  "displayName": "Traveler",
  "house": "Dawn",
  "archetype": "Explorer",
  "level": 5,
  "xp": 2500,
  "credentials": [
    {
      "type": "path_initiate",
      "issuedAt": "2026-03-10T12:00:00Z"
    }
  ]
}

Credentials

GET /api/credentials

List user credentials.

Response:

{
  "credentials": [
    {
      "id": "cred_123",
      "type": "governance_participant",
      "claims": {
        "voted": true,
        "proposalCount": 5
      },
      "issuedAt": "2026-03-10T12:00:00Z"
    }
  ],
  "total": 1
}

POST /api/credentials/issue

Issue a credential (requires admin API key).

Response:

{
  "success": true,
  "credentialId": "cred_gov_part_abc123",
  "issuedAt": "2026-03-10T14:30:00Z"
}

Identity Management

GET /api/me

Get current user info.

PATCH /api/me/username

Update username.

Wallets

GET /api/wallets

List linked wallets.

POST /api/wallets/link

Link a new wallet.

---

Path Service APIs

Quests

GET /api/quests

List available quests.

Response:

{
  "quests": [
    {
      "id": "quest_daily_001",
      "title": "Daily Ritual: Login",
      "description": "Log in today to earn XP",
      "xpReward": 50,
      "goldReward": 10,
      "type": "daily",
      "difficulty": "beginner"
    }
  ]
}

POST /api/quests/:id/complete

Complete a quest.

Response:

{
  "success": true,
  "xpEarned": 50,
  "goldEarned": 10,
  "credentialIssued": {
    "id": "cred_path_initiate",
    "type": "path_initiate"
  },
  "newLevel": 2,
  "newXP": 1050
}

---

Learn Service APIs

Courses

GET /api/courses

List available courses.

Response:

{
  "courses": [
    {
      "id": "course_intro_001",
      "title": "Introduction to RitualOS",
      "description": "Learn the basics",
      "lessons": 10,
      "duration": "2 hours",
      "skillPoints": 100
    }
  ]
}

POST /api/courses/:id/enroll

Enroll in a course.

---

Governance Service APIs

Proposals

GET /api/proposals

List proposals.

Response:

{
  "proposals": [
    {
      "id": "prop_001",
      "title": "Increase Daily Quest XP",
      "description": "Proposal to increase daily quest rewards",
      "status": "active",
      "yesVotes": 15,
      "noVotes": 3,
      "endTime": "2026-03-15T12:00:00Z"
    }
  ]
}

POST /api/proposals

Create a proposal (requires level 50+).

POST /api/proposals/:id/vote

Vote on a proposal.

---

Guild Service APIs

Organizations

GET /api/organizations

List organizations.

POST /api/organizations/:id/join

Join an organization.

Roles

GET /api/roles

List available roles.

POST /api/roles/:id/apply

Apply for a role.

---

Scroll Service APIs

Scrolls

GET /api/scrolls

List scrolls.

Response:

{
  "scrolls": [
    {
      "id": "scroll_001",
      "title": "The First Journey",
      "author": "Traveler",
      "house": "Dawn",
      "visibility": "public",
      "settlementWeight": 25,
      "createdAt": "2026-03-10T12:00:00Z"
    }
  ]
}

POST /api/scrolls

Create a new scroll.

---

Market Service APIs

Assets

GET /api/assets

List marketplace assets.

POST /api/listings/:id/purchase

Purchase an item.

---

Standard Response Format

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided access token is invalid or expired",
    "details": { ... }
  }
}

Common Error Codes

---

Authentication

All API requests (except /api/oauth/*) require authentication:

const response = await fetch('https://service.ritualos.com/api/endpoint', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ /* data */ })
});

Rate Limiting

Pagination

List endpoints support pagination:

GET /api/resource?page=1&limit=20

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

---

Testing APIs

Use the ApiExplorer component above to test endpoints live, or use curl:

# Get claims
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://id.ritualos.com/api/claims

# Complete quest
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://path.ritualos.com/api/quests/quest_daily_001/complete

SDKs & Libraries

Official SDKs:

• TypeScript/JavaScript: @ritualos/sdk (coming soon)
• Python: ritualos-python (beta)

---

Related Documentation

• OAuth Integration Guide
• ID Service Docs
• Credential Catalog
• Architecture

---

API Version: 3.0 Last Updated: March 10, 2026