AI-Powered Schedule Suggestions — Take Time REST API

Use POST /v1/schedule/suggest to get AI-powered schedule suggestions. The endpoint analyzes your completion patterns and available time slots to recommend an optimized weekly plan aligned with your stated goals.

Endpoint

POST /v1/schedule/suggest

Request Body

string

A natural language description of what you want to improve or focus on, e.g. "study more math" or "reduce evening sessions and front-load the week". The AI uses this to bias its recommendations toward your priorities.

number

The maximum number of study hours you can commit to each day. When provided, the AI will not recommend more than this total daily load. Omit this field to let the AI infer availability from your existing schedule patterns.

Response Fields

array

An array of schedule recommendation objects. Each suggestion describes a proposed change or addition:

string

The kind of change recommended: "add_block", "move_block", "remove_block", or "rebalance".

string

The subject the suggestion applies to.

string

The day of the week targeted by this suggestion, e.g. "Monday".

string

Proposed block start time in HH:MM 24-hour format.

string

Proposed block end time in HH:MM 24-hour format.

string

A human-readable explanation of why this change is recommended, based on your completion data and stated goal.

Example Response

{
  "data": {
    "suggestions": [
      {
        "type": "add_block",
        "subject_id": "sub_math",
        "day": "Wednesday",
        "start": "09:00",
        "end": "10:30",
        "reason": "Your math completion rate is highest on Wednesday mornings. Adding a session here aligns with your goal to study more math."
      },
      {
        "type": "move_block",
        "subject_id": "sub_python",
        "day": "Friday",
        "start": "14:00",
        "end": "15:00",
        "reason": "Your Friday afternoon completion rate is strong. Moving this session from the evening improves your predicted completion."
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}

Code Examples

curl -X POST https://api.taketime.app/v1/schedule/suggest \
  -H "Authorization: Bearer tt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "study more math",
    "available_hours": 3
  }'

const response = await fetch(
  "https://api.taketime.app/v1/schedule/suggest",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer tt_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      goal: "study more math",
      available_hours: 3,
    }),
  }
);

const { data, error } = await response.json();

if (error) {
  console.error("Suggestion request failed:", error);
} else {
  data.suggestions.forEach((s) => {
    console.log(`[${s.type}] ${s.day} ${s.start}–${s.end}: ${s.reason}`);
  });
}

Suggestions are recommendations only — they are not applied to your schedule automatically. Use the create_block MCP tool or the schedule endpoints to act on suggestions you want to adopt.

The more historical data Take Time has, the more accurate the suggestions become. For best results, use the app consistently for at least two weeks before relying heavily on AI recommendations.

Overview

Blocks

Subjects

Stats & Schedule

AI-Powered Schedule Suggestions — Take Time REST API

Endpoint

Request Body

Response Fields

Example Response

Code Examples

​Endpoint

​Request Body

​Response Fields

​Example Response

​Code Examples

Endpoint

Request Body

Response Fields

Example Response

Code Examples