Schedule API

Overview

The Schedule API provides access to global shipping schedules from multiple shipping lines. Coverage is not universal — different carriers provide varying levels of schedule data. Users can retrieve schedules in three ways:

• By Port → Port (most frequent coverage, 79 shipping lines)
• By Vessel (46 shipping lines)
• By Port (24 shipping lines)

This document details which shipping lines are supported for each type of query.

Coverage

Base URL: https://api.sinay.ai/schedule/api/v1

Getting started

Every request must be authenticated with your API key, passed in the API_KEY header, together with the standard HTTP headers.

GET /schedule/api/v1/schedule/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your-api-key>

See Mandatory Headers for the full list of required HTTP headers.

A request with a missing, invalid or expired key — or a key without access to the Schedule product — is rejected (401 / 403) and does not consume any credit.

How credits are counted

Access to the Schedule API is credit-based. The rule is simple:

You are charged 1 credit per schedule api call.

Good to know

• Failed requests are free. Authentication errors, malformed port codes, and quota-exceeded responses never consume credits.
• Schedule credits are a dedicated credit type and are independent from your other products (Shipment, Congestion, …).

Quotas and rate limiting

Two independent protections can stop a request:

• Credit quota reached → 403 Forbidden. The request is blocked before processing — no credit is consumed. Top up or wait for your next period.
• Too many requests in a short window → 429 Too Many Requests. A maximum call rate of 10 requests per 10 seconds per API key applies. Simply retry shortly after.

See Rate Limit for details.

Tracking your consumption

To check your balance without consuming a credit:

GET /schedule/api/v1/consumption/current-period
API_KEY: <your-api-key>

Typical fields returned:

To retrieve the full history of your periods, use /consumption/periods.

See Current consumption period and Consumption periods.

Error responses

All errors share a common body:

{
  "errorCode": 404,
  "message": "unable to retrieve schedule",
  "details": [],
  "time": "2026-06-24T10:30:00Z"
}