Skip to main content
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

​
goal
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.
​
available_hours
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

​
suggestions
array
An array of schedule recommendation objects. Each suggestion describes a proposed change or addition:
​
type
string
The kind of change recommended: "add_block", "move_block", "remove_block", or "rebalance".
​
subject_id
string
The subject the suggestion applies to.
​
day
string
The day of the week targeted by this suggestion, e.g. "Monday".
​
start
string
Proposed block start time in HH:MM 24-hour format.
​
end
string
Proposed block end time in HH:MM 24-hour format.
​
reason
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
  }'
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.