> ## 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 Study Block — PATCH /blocks/:id Reference

> PATCH /v1/blocks/:id — update fields on an existing block. Send only the fields you want to change, including marking a block as done.

Use `PATCH /v1/blocks/:id` to update an existing study block. Only include the fields you want to change — all other fields remain unchanged. This is also how you mark a block as complete.

## Endpoint

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

## Path Parameters

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

## Body Parameters

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

<ParamField body="subject_id" type="string">
  Reassign the block to a different subject by providing a new subject ID.
</ParamField>

<ParamField body="start" type="string">
  Updated start time in `HH:MM` format.
</ParamField>

<ParamField body="end" type="string">
  Updated end time in `HH:MM` format. Must be after `start` if both are provided.
</ParamField>

<ParamField body="done" type="boolean">
  Set to `true` to mark the block as complete, or `false` to mark it incomplete.
</ParamField>

<ParamField body="topic" type="string">
  Updated topic or syllabus item label. Pass an empty string to clear the existing topic.
</ParamField>

## Response

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

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

<ResponseField name="subject_id" type="string">
  The ID of the subject this block belongs to.
</ResponseField>

<ResponseField name="subject_name" type="string">
  The display name of the subject.
</ResponseField>

<ResponseField name="date" type="string">
  The date of the block in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="start" type="string">
  The block's start time in `HH:MM` format.
</ResponseField>

<ResponseField name="end" type="string">
  The block's end time in `HH:MM` format.
</ResponseField>

<ResponseField name="topic" type="string">
  The topic label for this block, or `null` if none is set.
</ResponseField>

<ResponseField name="done" type="boolean">
  Whether the block has been marked as complete.
</ResponseField>

**Example response**

```json theme={null}
{
  "data": {
    "id": "blk_abc123",
    "subject_id": "sub_xyz",
    "subject_name": "JavaScript",
    "date": "2026-06-11",
    "start": "09:00",
    "end": "10:00",
    "topic": "Ch. 3 — Arrays",
    "done": true
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}
```

## Marking a Block as Done

To mark a block as complete, send a `PATCH` request with only `{ "done": true }` in the body. Every other field on the block stays exactly as it was.

```json theme={null}
{
  "done": true
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Mark a block as complete
  curl -X PATCH https://api.taketime.app/v1/blocks/blk_abc123 \
    -H "Authorization: Bearer tt_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"done": true}'
  ```

  ```javascript Node.js theme={null}
  // Mark a block as complete
  const response = await fetch('https://api.taketime.app/v1/blocks/blk_abc123', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer tt_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ done: true }),
  });

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

  if (error) {
    console.error('Failed to update block:', error.code, error.message);
  } else {
    console.log('Block marked done:', data.done);
  }
  ```
</CodeGroup>

<Note>
  You can update `start` and `end` independently. If you update only one, the API validates the final pair — so ensure the resulting `start` is still before `end`.
</Note>