Documentation/API Reference/Endpoints

API Endpoints

Complete reference for the RealmKit Hub REST API. Build integrations, tools, and custom interfaces using these endpoints.

Base URL

All API endpoints are relative to this base URL

https://api.realmkit.com/v1

Production

https://api.realmkit.com/v1

Staging

https://staging-api.realmkit.com/v1

Authentication

Most endpoints are public, but some require authentication

API Key

Server-to-server integrations

Include API key in Authorization header

Authorization: Bearer your-api-key-here

OAuth 2.0

Web applications, user actions

OAuth flow for user authentication

Authorization: Bearer oauth-access-token

JWT Token

Web interface, temporary access

JSON Web Token from login

Authorization: Bearer jwt-token
Getting API Keys
API keys can be generated from your account settings.Learn more about authentication →

Available Endpoints

GET
/api/realms

List all available realms with optional filtering

Parameters

NameTypeLocationDescription
categorystringqueryFilter by category (saas, blog, api, etc.)
tagsstringqueryComma-separated list of tags
limitnumberqueryMaximum number of results (default: 20)
offsetnumberqueryNumber of results to skip (default: 0)
searchstringquerySearch term for name and description
featuredbooleanqueryOnly return featured realms

Response

200
application/json
{
  "realms": [
    {
      "id": "string",
      "name": "string",
      "slug": "string",
      "description": "string",
      "category": "string",
      "tags": [
        "string"
      ],
      "downloadCount": "number",
      "starCount": "number",
      "author": {
        "username": "string",
        "name": "string",
        "image": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "pagination": {
    "total": "number",
    "limit": "number",
    "offset": "number",
    "hasMore": "boolean"
  }
}

Example Request

curl -X GET \
  "https://api.realmkit.com/v1/api/realms" \
  -H "Content-Type: application/json"

GET
/api/realms/{slug}

Get detailed information about a specific realm

Parameters

NameTypeLocationDescription
slugstringpathUnique realm identifier

Response

200
application/json
{
  "id": "string",
  "name": "string",
  "slug": "string",
  "description": "string",
  "longDescription": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "downloadCount": "number",
  "starCount": "number",
  "version": "string",
  "license": "string",
  "author": {
    "username": "string",
    "name": "string",
    "image": "string",
    "bio": "string"
  },
  "features": {
    "auth": "boolean",
    "payments": "boolean",
    "database": "boolean"
  },
  "requirements": {
    "node": "string",
    "npm": "string"
  },
  "repository": "string",
  "demo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Example Request

curl -X GET \
  "https://api.realmkit.com/v1/api/realms/{slug}" \
  -H "Content-Type: application/json"

POST
/api/realms/{slug}/download

Record a download and get download URL

Parameters

NameTypeLocationDescription
slugstringpathRealm identifier

Response

200
application/json
{
  "downloadUrl": "string",
  "expiresAt": "string"
}

Example Request

curl -X POST \
  "https://api.realmkit.com/v1/api/realms/{slug}/download" \
  -H "Content-Type: application/json"

POST
/api/realms
Auth Required

Create a new realm (requires authentication)

Parameters

NameTypeLocationDescription
name
required
stringqueryRealm name
description
required
stringqueryShort description
category
required
stringqueryPrimary category
tagsarrayqueryTags for discovery
visibilitystringquerypublic, unlisted, or private
licensestringquerySoftware license
repositorystringquerySource code repository URL

Response

201
application/json
{
  "id": "string",
  "slug": "string",
  "uploadUrl": "string",
  "uploadToken": "string"
}

Example Request

curl -X POST \
  "https://api.realmkit.com/v1/api/realms" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key"

GET
/api/collections

Get curated collections of realms

Parameters

NameTypeLocationDescription
featuredbooleanqueryOnly featured collections

Response

200
application/json
{
  "collections": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "realms": [
        "string"
      ],
      "createdBy": "string",
      "createdAt": "string"
    }
  ]
}

Example Request

curl -X GET \
  "https://api.realmkit.com/v1/api/collections" \
  -H "Content-Type: application/json"

GET
/api/stats

Get platform statistics

Response

200
application/json
{
  "totalRealms": "number",
  "totalDownloads": "number",
  "totalUsers": "number",
  "categories": {
    "saas": "number",
    "blog": "number",
    "api": "number",
    "ecommerce": "number"
  }
}

Example Request

curl -X GET \
  "https://api.realmkit.com/v1/api/stats" \
  -H "Content-Type: application/json"

HTTP Status Codes

Standard HTTP status codes used by the API

200
Success

Request completed successfully

201
Created

Resource created successfully

400
Bad Request

Invalid request parameters

401
Unauthorized

Authentication required

403
Forbidden

Insufficient permissions

404
Not Found

Resource does not exist

429
Rate Limited

Too many requests

500
Server Error

Internal server error

Rate Limiting

API usage limits and headers

Rate Limits

  • Anonymous requests100/hour
  • Authenticated requests1000/hour
  • Premium users5000/hour
  • Upload operations10/hour

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

SDKs and Tools

Official libraries and tools for API integration

JavaScript SDK

Official Node.js and browser SDK

npm install @realmkit/sdk
Python SDK

Python library for API integration

pip install realmkit
GraphQL API

Alternative GraphQL endpoint

Coming Soon

Next Steps

Continue exploring the API documentation

Authentication
API keys and OAuth setup
Official SDKs
JavaScript and Python libraries
Interactive Docs
Try the API in your browser