Submit hopping job

Run berth-hopping analysis asynchronously.

POST /v1/jobs/hopping

Scope charts:write · Cost 4 requests · Plans Scale and Enterprise

Creates a durable train-specific hopping job with optional completion callback and one automatic retry.

Authentication

Send your key in one header: X-RailCore-Key, Authorization: Bearer or X-Api-Key. Two headers with different keys answer 401 AMBIGUOUS_API_KEY. This operation requires the charts:write scope. 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. See the authentication guide and HMAC signing.

Request parameters

This operation takes no path or query parameters.

JSON body

FieldTypeDescription
train_numberstringTrain to analyze.
fromstringBoarding station code.
tostringDestination station code.
datestring(date)Journey date in YYYY-MM-DD.
quotaQuotaReservation quota, default GN.
viastringComma-separated stations the plan must cross.
max_hopsintegerMaximum chain length, 1 to 12.
prefer_berth / avoid_berthstringComma-separated berth preference codes.
prefer_class / avoid_classstringComma-separated class preference codes.
include_farebooleanAdd fare details.
include_alternate_boardingbooleanEvaluate nearby boarding stations.
include_cross_classbooleanAllow class changes between hops.
strategiesstringmin_hops, min_seat_changes, cheapest, or all.
callback_urlstring(uri)Optional. Where RailCore POSTs the job's outcome when it finishes, signed with the webhook_secret this request returns. An https URL on a public host, port 443 or 1024 and up, with no user name or password. localhost, private, link-local, CGNAT and cloud metadata addresses are refused with 400 VALIDATION_ERROR (details[].field callback_url). See the webhooks guide.

Code examples

Base URL https://ir.railcore.tech/v1. Keep the key in an environment variable and call from a trusted server-side environment.

cURL

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

curl -sS -X POST \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"train_number":"12656","from":"BSL","to":"ADI","date":"'"$RUN_DATE"'","quota":"GN","max_hops":"6","include_fare":"true","prefer_class":"3A"}' \
  "https://ir.railcore.tech/v1/jobs/hopping"

JavaScript

const runDate = new Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Kolkata" }).format(new Date());

const response = await fetch("https://ir.railcore.tech/v1/jobs/hopping", {
  method: "POST",
  headers: {
    "X-RailCore-Key": process.env.RAILCORE_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "train_number": "12656",
  "from": "BSL",
  "to": "ADI",
  "date": runDate,
  "quota": "GN",
  "max_hops": "6",
  "include_fare": "true",
  "prefer_class": "3A"
}),
});

const body = await response.json();
console.log(response.status, body);

Python

import datetime
import os
import requests

run_date = datetime.datetime.now(datetime.timezone(datetime.timedelta(hours=5, minutes=30))).date().isoformat()

response = requests.request(
    "POST",
    "https://ir.railcore.tech/v1/jobs/hopping",
    headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
    json={"train_number": "12656", "from": "BSL", "to": "ADI", "date": run_date, "quota": "GN", "max_hops": "6", "include_fare": "true", "prefer_class": "3A"},
    timeout=20,
)
print(response.status_code, response.json())

Rate limits and cost

This operation counts as 4 requests and is available on Scale and Enterprise. Failed requests are free. Per-minute budgets, daily caps and the headers reporting what is left are in rate limits; plans and prices are in requests and billing.

Response fields

FieldTypeDescription
job_idstringUse this identifier for polling, streaming, or cancellation.
statusprocessingInitial job state.
poll_urlstringRelative polling endpoint.
stream_urlstringRelative SSE endpoint.
messagestringSubmission summary.
webhook_secretstringPresent when you gave a callback_url: the secret (whsec_…) that signs this job's callbacks. It is shown once and RailCore does not store it, so save it with the job_id.

Example response

{
  "success": true,
  "data": {
    "job_id": "job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "status": "processing",
    "poll_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "stream_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8/stream",
    "message": "Hopping analysis submitted. Poll the poll_url for results."
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "trace_id": "trc_01J5Z7Y8N2K4M6P8R0T2V4X6Z9",
    "timestamp": "2026-11-20T10:57:05.609Z",
    "freshness": {
      "mode": "live",
      "retrieved_at": "2026-11-20T10:57:05.609Z",
      "sources": [
        {
          "confidence": "high"
        }
      ]
    }
  }
}

Errors

StatusCodeDescriptionRetry
400VALIDATION_ERRORA required field is missing or invalid, or callback_url is not an https URL on a public host. error.details[].field names the field. Not counted.Not retryable
429JOB_LIMIT_EXCEEDEDFive jobs are already active on this account, across all of its keys.Retryable
401MISSING_API_KEYNo key in X-RailCore-Key, Authorization: Bearer or X-Api-Key, or the key is too short.Not retryable
401INVALID_API_KEYThe key is unknown or revoked. A disabled or expired key answers API_KEY_DISABLED or API_KEY_EXPIRED.Not retryable
401AMBIGUOUS_API_KEYMore than one key header was sent, with different keys. Send the key in one header.Not retryable
401SIGNATURE_INVALIDHMAC signature missing or not verified. Growth, Scale and Enterprise keys must sign every request; a key with no signing secret must be rotated.Not retryable
403SCOPE_MISSINGThe key lacks this operation's scope.Not retryable
403PLAN_ENDPOINT_DISABLEDThe account's plan does not include this endpoint.Not retryable
402CREDITS_EXHAUSTEDThe month's requests are used up, or too few are left for this request. Nothing is fetched.Not retryable
429RATE_LIMITEDThe account's per-minute budget, or a Free account's daily budget, is used up. Every key on the account shares it. Honor Retry-After.Retryable
410API_VERSION_SUNSETThis API version has reached its announced sunset date. Migrate to a supported major version.Not retryable
503UPSTREAM_UNAVAILABLELive data could not be retrieved. Wait for Retry-After, then retry with backoff. Not counted.Retryable
503UPSTREAM_TIMEOUTThe live-data request ran past its deadline. Wait for Retry-After, then retry with backoff. Not counted.Retryable
503METERING_UNAVAILABLEThe request could not be counted, so no data was returned. Retry with backoff.Retryable

Implementation notes

Related Jobs endpoints

All RailCore Indian Railways API endpoints · Quickstart · Rate limits

Last updated