> ## 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.

# Update a Subject — PATCH /subjects/:id Endpoint Reference

> PATCH /v1/subjects/:id — update a subject's name, color, or weekly slots. Only the fields you include will be changed. Type changes are not supported.

Use `PATCH /v1/subjects/:id` to modify an existing subject profile. Send only the fields you want to update — all other fields remain unchanged.

## Endpoint

```
PATCH https://api.taketime.app/v1/subjects/:id
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subject you want to update.
</ParamField>

## Body Parameters

All body parameters are optional. Include only the fields you want to change.

<ParamField body="name" type="string">
  Updated display name. Maximum 40 characters. Must be unique across your account.
</ParamField>

<ParamField body="color" type="string">
  Updated hex color code (e.g. `#6366f1`).
</ParamField>

<ParamField body="slots" type="array">
  A full replacement of the subject's weekly slot schedule. The value you provide replaces the entire existing `slots` array — it is not merged. Send an empty array (`[]`) to remove all scheduled slots.
</ParamField>

<Warning>
  Changing the `type` of a subject after creation is not supported. If you need a different type, delete the existing subject and create a new one. Note that deleting a subject also removes all its associated blocks.
</Warning>

## Response

Returns the full updated subject object inside the `data` field.

<ResponseField name="id" type="string">
  Unique identifier for the subject.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the subject.
</ResponseField>

<ResponseField name="type" type="string">
  The subject type. Unchanged by this endpoint.
</ResponseField>

<ResponseField name="color" type="string">
  Hex color code for this subject.
</ResponseField>

<ResponseField name="slots" type="array">
  The updated weekly time slots for this subject.
</ResponseField>

<ResponseField name="syllabus" type="array">
  Array of syllabus topic objects. Each item has `title` (string), `duration` (integer, minutes), and `done` (boolean). Unchanged by this endpoint.
</ResponseField>

**Example response**

```json theme={null}
{
  "data": {
    "id": "sub_xyz",
    "name": "JavaScript",
    "type": "study",
    "color": "#6366f1",
    "slots": [
      {
        "days": [1, 3, 5],
        "start": "09:00",
        "end": "10:00"
      }
    ],
    "syllabus": [
      { "title": "Arrays", "duration": 30, "done": false }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Update color and reschedule slots
  curl -X PATCH https://api.taketime.app/v1/subjects/sub_xyz \
    -H "Authorization: Bearer tt_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "color": "#6366f1",
      "slots": [
        {
          "days": [1, 3, 5],
          "start": "09:00",
          "end": "10:00"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.taketime.app/v1/subjects/sub_xyz', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer tt_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      color: '#6366f1',
      slots: [
        {
          days: [1, 3, 5],
          start: '09:00',
          end: '10:00',
        },
      ],
    }),
  });

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

  if (error) {
    console.error('Failed to update subject:', error.code, error.message);
  } else {
    console.log('Updated subject:', data.id);
  }
  ```
</CodeGroup>

<Note>
  When you update `slots`, the new array fully replaces the old one. Any previously defined slots not included in the new array will be removed.
</Note>