List Timetables

Retrieve a list of all timetables for your organization. This endpoint returns basic information about each timetable.

Endpoint

GET /api/v1/timetables

Authentication

This endpoint requires authentication. Include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Parameters

This endpoint does not require any parameters.

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": {
    "orgId": "org_12345",
    "timetables": [
      {
        "id": "tt_67890",
        "name": "Term 1 2025 Timetable",
        "status": "published",
        "createdAt": "2025-01-15T08:00:00.000Z",
        "updatedAt": "2025-01-20T14:30:00.000Z"
      },
      {
        "id": "tt_67891",
        "name": "Term 2 2025 Timetable",
        "status": "draft",
        "createdAt": "2025-03-01T09:00:00.000Z",
        "updatedAt": "2025-03-10T16:45:00.000Z"
      }
    ]
  },
  "timestamp": "2024-07-15T10:30:00.000Z"
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
data.orgId	string	Your organization identifier
data.timetables	array	Array of timetable objects
data.timetables[].id	string	Unique timetable identifier
data.timetables[].name	string	Human-readable timetable name
data.timetables[].status	string	Timetable status (draft or published)
data.timetables[].createdAt	string	ISO timestamp when timetable was created
data.timetables[].updatedAt	string	ISO timestamp when timetable was last updated
timestamp	string	ISO timestamp of the API response

Error Responses

401 Unauthorized

Missing or invalid API key.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or not found"
  }
}

429 Rate Limited

Too many requests.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "resetTime": "2025-07-15T11:30:00Z"
  }
}

500 Internal Server Error

Server error occurred.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

Code Examples

cURL

curl -X GET \
  'https://www.timetablemaster.com/api/v1/timetables' \
  -H 'Authorization: Bearer ttm_your_api_key_here' \
  -H 'Content-Type: application/json'

JavaScript

const response = await fetch(
  "https://www.timetablemaster.com/api/v1/timetables",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer ttm_your_api_key_here",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data.data.timetables);

Python

import requests

url = 'https://www.timetablemaster.com/api/v1/timetables'
headers = {
    'Authorization': 'Bearer ttm_your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
data = response.json()

if data['success']:
    timetables = data['data']['timetables']
    for timetable in timetables:
        print(f"Timetable: {timetable['name']} (Status: {timetable['status']})")

PHP

<?php
$url = 'https://www.timetablemaster.com/api/v1/timetables';
$headers = [
    'Authorization: Bearer ttm_your_api_key_here',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    foreach ($data['data']['timetables'] as $timetable) {
        echo "Timetable: " . $timetable['name'] . " (Status: " . $timetable['status'] . ")\n";
    }
}
?>

Use Cases

Display Available Timetables

Use this endpoint to show users a list of available timetables in your application:

async function displayTimetables() {
  const response = await fetch("/api/v1/timetables", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  const data = await response.json();

  if (data.success) {
    const timetableList = data.data.timetables
      .map(
        (tt) => `<option value="${tt.id}">${tt.name} (${tt.status})</option>`
      )
      .join("");

    document.getElementById("timetable-select").innerHTML = timetableList;
  }
}

Check for Updates

Monitor timetable updates by comparing the updatedAt timestamps:

def check_for_updates(last_check_time):
    response = requests.get('/api/v1/timetables', headers=headers)
    data = response.json()

    updated_timetables = []
    for timetable in data['data']['timetables']:
        if timetable['updatedAt'] > last_check_time:
            updated_timetables.append(timetable)

    return updated_timetables

Next Steps

Once you have the timetable IDs from this endpoint, you can:

• Get detailed timetable data for a specific timetable