Get started

Quickstart

Make the first authenticated request.

1. Sign up and verify your email

Create a RailCore account and open the link in the email we send you. Keys and the rest of the developer console unlock once your email is verified.

2. Create a key

Open Dashboard > Developer > API keys and create a key with the live:read scope. The Free plan costs nothing: 500 requests a month, 10 a minute and 100 a day, on 20 of the 30 endpoints, live train status included. Build and evaluate. No card, no phone number.

The plaintext appears once

Copy the key into your secret manager immediately. RailCore stores only its hash.
Terminal
export RAILCORE_KEY="rk_live_your_key_here"

3. Ask where a train is

Live train status for 12951, for the run that leaves its first station today in India. Each sample works out today's date when it runs.

RUN_DATE=$(TZ=Asia/Kolkata date +%F)

curl -sS -i \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  "https://ir.railcore.tech/v1/trains/12951/live?date=$RUN_DATE"

The key travels in X-RailCore-Key, Authorization: Bearer or X-Api-Key: pick one under Key header and every sample in these docs is written that way. Send the key in one header only.

4. Read the response

Path, Use table
PathUse
successBranch before reading data or error.
dataEndpoint payload on success: here the run's status, delay and every station.
error.codeStable machine-readable failure code.
meta.request_idLog this value and include it in support requests.
meta.freshnessLive retrieval and confidence context.

Headers to expect

HTTP
HTTP/2 200
Content-Type: application/json; charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate, private
X-RailCore-Request-ID: req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8
X-RailCore-Plan: developer_free
X-RailCore-RateLimit-Limit: 10
X-RailCore-RateLimit-Remaining: 9
X-RailCore-RateLimit-Reset: 1785472200
X-RailCore-RateLimit-Day-Limit: 100
X-RailCore-RateLimit-Day-Remaining: 99
X-RailCore-RateLimit-Day-Reset: 1785522600
X-RailCore-Credits-Cost: 1
X-RailCore-Credits-Remaining: 499
X-RailCore-Confidence: high
Server-Timing: key;dur=3, limits;dur=2, credits;dur=4, upstream;dur=21, total;dur=31

This request counts as 1 request: X-RailCore-Credits-Cost says what it counted as and X-RailCore-Credits-Remaining how many requests are left this month. A request that fails is not counted. The rate-limit headers are your account's, shared by all its keys. Every header.

5. On a signed plan, sign it

Growth, Scale and Enterprise keys must sign

Growth, Scale and Enterprise keys must also sign every request with HMAC-SHA256, sending X-RailCore-Timestamp, X-RailCore-Nonce and X-RailCore-Signature. Free and Starter keys send the key alone. Without a signature their requests answer 401 SIGNATURE_INVALID. How to sign a request.
Node.js, signed
import crypto from "node:crypto";

const runDate = new Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Kolkata" }).format(new Date());
const path = "/v1/trains/12951/live";
const query = `date=${runDate}`;
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString("hex");
// A GET has no body, so its hash is the hash of zero bytes.
const bodyHash = crypto.createHash("sha256").update("").digest("hex");
const payload = ["GET", path, query, bodyHash, timestamp, nonce].join("\n");
const signature = crypto
  .createHmac("sha256", process.env.RAILCORE_HMAC_SECRET)
  .update(payload)
  .digest("base64");

const response = await fetch(`https://ir.railcore.tech${path}?${query}`, {
  headers: {
    "X-RailCore-Key": process.env.RAILCORE_KEY,
    "X-RailCore-Timestamp": timestamp,
    "X-RailCore-Nonce": nonce,
    "X-RailCore-Signature": signature,
  },
});

The signing secret is shown once, with the key, when you create or rotate a Growth, Scale or Enterprise key. Keep it on your server, here as RAILCORE_HMAC_SECRET.

The signature covers the method, path, query, a hash of the exact body bytes, the timestamp and a nonce. HMAC signing has the full rules.

Next

  • Try any endpoint from its page with the playground. Signed in, choose Use my account: it works on every plan, with no signing, within your plan's per-minute limit. Or paste a Free or Starter key. Using the playground.
  • See what every endpoint counts as in requests and billing, and the limits in rate limits.
  • Compare plans on pricing.

Last updated