API

Health check

GET/v1/health

No API keyRate-limited

Whether the API is up and can reach its database. This site’s status indicator uses it. It counts toward your rate limit like any other request.

Try it#

Sends a real request to the production API through this site. No credentials are used, so you see exactly what anyone would.

Request#

curl "https://api.rankdmusic.app/v1/health"

const response = await fetch('https://api.rankdmusic.app/v1/health');
const body = await response.json();

if (!response.ok) {
  const code = typeof body.error === 'string' ? body.error : body.error.code;
  throw new Error(`Rankd API ${response.status}: ${code}`);
}

const { data, meta } = body;

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/health")!
let (data, response) = try await URLSession.shared.data(from: url)

guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
    throw URLError(.badServerResponse)
}

let body = try JSONSerialization.jsonObject(with: data) as? [String: Any]
let result = body?["data"]

import requests

response = requests.get("https://api.rankdmusic.app/v1/health", timeout=10)
body = response.json()

if not response.ok:
    error = body["error"]
    raise RuntimeError(error if isinstance(error, str) else error["code"])

data = body["data"]

Response#

A successful response is { "data": …, "meta": … }. data is a Health, and meta is a Meta.

Field	Type	Description
databasealways	string	Whether the API could query its database. One of: `ok`, `error`

Responses#

200The API answered. database says whether it could query its data.

Captured from production: GET /v1/health

200 response

{
  "data": {
    "database": "ok"
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

429Too many requests this minute. Wait Retry-After seconds, then try again.

Headers: Retry-After Seconds to wait. Always 60.

429 response

{
  "error": "rate limited"
}

503The API is running without its database.

503 response

{
  "error": {
    "code": "database_unavailable",
    "message": "The Rankd database is not bound to this deployment."
  }
}