uCord Public API

Authentication

Every request to /api/v1/* needs an API key, reads included. Keys look like ucord_sk_ followed by 43 characters (keys made before October 2026 start ucordAPI_ and keep working). A key is shown once when you create it on your dashboard; uCord stores only a hash of it, so a lost key is replaced, not recovered.

X-API-Key: ucord_sk_Xk3v9QbT0aR2mW7cYp5LhN8sD1fG4jU6eZqA0iKoB2w
Authorization: Bearer ucord_sk_Xk3v9QbT0aR2mW7cYp5LhN8sD1fG4jU6eZqA0iKoB2w
?api-key=ucord_sk_Xk3v9QbT0aR2mW7cYp5LhN8sD1fG4jU6eZqA0iKoB2w

Any one of the three works; if you send more than one, X-API-Key is used. Prefer a header — query strings end up in server logs and browser history. The MCP server takes the same key in either header (not the query parameter).

Writing to a listing needs more than a key: a read-write key (chosen when you create it; older keys write on the plus and partner tiers), and Manage Server permission on that guild in Discord, checked against Discord rather than a stored owner id. A key you limited to chosen servers works only on those. The same key works as a bearer token on the MCP server's owner tools, where an agent can instead sign in with Discord.

Response format

Every response is JSON with a success flag. Paginated endpoints add meta. Failures use success: false and an error object carrying code and message.

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

Server object

What a listing looks like in a response. Fields marked always present appear on every listing; the rest can be null or absent.

Errors

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

Rate limiting

Limits are per key, per endpoint, per minute. Search is capped harder than everything else, because text search is the most expensive query here and would otherwise be the cheapest way to load the database.

Tiers above free are assigned by uCord — there is no self-service upgrade today. Every response carries:

• X-RateLimit-Limit — your allowance for this endpoint
• X-RateLimit-Remaining — what is left in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• X-RateLimit-Tier — the tier being applied

On a 429, wait for X-RateLimit-Reset (or Retry-After where it is sent) and back off exponentially rather than retrying immediately.

Try it

Send a real request with your own key. Nothing is stored — the key stays in this page and goes straight to the API. Read endpoints only; the write endpoints change a live listing, so they are not wired to a button here.

Response will appear here.

Response will appear here.

Response will appear here.

Response will appear here.

Code examples

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

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

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()['data']

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