> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taketime.space/llms.txt
> Use this file to discover all available pages before exploring further.

# AI-Powered Schedule Suggestions — Take Time REST API

> POST /v1/schedule/suggest — get AI-powered schedule suggestions based on your completion patterns, available hours per day, and stated study goals.

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

```http theme={null}
POST /v1/schedule/suggest
```

## Request Body

<ParamField body="goal" type="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.
</ParamField>

<ParamField body="available_hours" type="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.
</ParamField>

## Response Fields

<ResponseField name="suggestions" type="array">
  An array of schedule recommendation objects. Each suggestion describes a proposed change or addition:

  <ResponseField name="type" type="string">
    The kind of change recommended: `"add_block"`, `"move_block"`, `"remove_block"`, or `"rebalance"`.
  </ResponseField>

  <ResponseField name="subject_id" type="string">
    The subject the suggestion applies to.
  </ResponseField>

  <ResponseField name="day" type="string">
    The day of the week targeted by this suggestion, e.g. `"Monday"`.
  </ResponseField>

  <ResponseField name="start" type="string">
    Proposed block start time in `HH:MM` 24-hour format.
  </ResponseField>

  <ResponseField name="end" type="string">
    Proposed block end time in `HH:MM` 24-hour format.
  </ResponseField>

  <ResponseField name="reason" type="string">
    A human-readable explanation of why this change is recommended, based on your completion data and stated goal.
  </ResponseField>
</ResponseField>

## Example Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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}`);
    });
  }
  ```
</CodeGroup>

<Info>
  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.
</Info>

<Tip>
  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.
</Tip>