uCord Public API

All endpoints

All endpoints require API key authentication. Base URL: https://ucord.cc/api/v1

Authentication

All requests to /api/v1/* require an API key. Keys use the format ucordAPI_ + 32 hex characters.

Supported methods

• Header (recommended): X-API-Key: ucordAPI_your_key_here
• Bearer: Authorization: Bearer ucordAPI_your_key_here
• Query (fallback): ?api-key=ucordAPI_your_key_here

Never expose API keys in client-side code or public repositories. Use headers in server-side requests.

Response format

All responses use a standard JSON envelope:

{
  "success": true,
  "data": { ... } | [ ... ],
  "meta": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }
}

Paginated endpoints include meta. Errors use success: false and an error object with code and message.

Try it now

Response will appear here.

Response will appear here.

Response will appear here.

Response will appear here.

Endpoint reference

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/servers?page=1&limit=20&sort=rankScore&order=desc&category=Gaming"

{
  "success": true,
  "data": [
    {
      "id": "123456789",
      "name": "Gaming Community",
      "description": "A fun gaming server...",
      "category": "Gaming",
      "tags": ["FPS", "Competitive"],
      "memberCount": 5000,
      "averageRating": 4.5,
      "totalReviews": 42,
      "vanityCode": "gaming-hub",
      "inviteUrl": "https://discord.gg/abc123",
      "iconUrl": "https://cdn.discordapp.com/icons/...",
      "bannerUrl": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }
}

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/server/ucord"

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/server/123456789012345678"

{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found or not discoverable."
  }
}

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/categories"

{
  "success": true,
  "data": [
    { "name": "Gaming", "count": 45, "description": "Gaming communities" },
    { "name": "Community", "count": 32, "description": "Community communities" }
  ]
}

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/servers/search?q=gaming&limit=10&nsfw=false"

Server object

Each server in responses includes these fields:

Error reference

Example error JSON (all errors follow this shape):

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Provide X-API-Key header, Authorization: Bearer , or api-key query parameter."
  }
}

Rate limiting

Per key, per endpoint limits:

• 100 req/min for /servers, /server/:identifier, /categories
• 30 req/min for /servers/search

All responses include rate limit headers:

• X-RateLimit-Limit — Max requests per window
• X-RateLimit-Remaining — Remaining requests
• X-RateLimit-Reset — Unix timestamp when the window resets

On 429, use the Retry-After header (seconds). Implement exponential backoff and cache responses on the client where appropriate.

Code examples

JavaScript (Fetch)

const res = await fetch('https://ucord.cc/api/v1/servers?page=1&limit=20', {
  headers: { 'X-API-Key': 'YOUR_KEY' }
});
const data = await res.json();
if (data.success) console.log(data.data);
else console.error(data.error);

Node.js (Axios)

const axios = require('axios');
const res = await axios.get('https://ucord.cc/api/v1/servers', {
  headers: { 'X-API-Key': 'YOUR_KEY' },
  params: { page: 1, limit: 20 }
});
console.log(res.data.data);

Python (requests)

import requests
r = requests.get('https://ucord.cc/api/v1/servers', headers={'X-API-Key': 'YOUR_KEY'}, params={'page': 1, 'limit': 20})
data = r.json()
print(data['data'] if data.get('success') else data.get('error'))

cURL

curl -H "X-API-Key: YOUR_KEY" "https://ucord.cc/api/v1/servers?page=1&limit=20"

PHP

$ch = curl_init('https://ucord.cc/api/v1/servers?page=1&limit=20');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY'],
  CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data['data'] ?? $data['error']);

Permission-scoped data

The totalClicks field (and other analytics) is only returned when your API key belongs to a user who has Manage Server permission for that Discord server. Otherwise it is omitted. This prevents partners from seeing other servers’ analytics.

Changelog

v1 (initial) — Servers list, single server, categories, full-text search. API key auth, per-key rate limits, permission-scoped analytics, CORS enabled.