Sync API docs from bc3: spotlights, questions 403 note, schedule entries 422 note

README.md

@@ -331,6 +331,7 @@ API endpoints
 - [Schedule entries](sections/schedule_entries.md#schedule-entries)
 - [Schedules](sections/schedules.md#schedules)
 - [Search](sections/search.md#search)
+- [Spotlights](sections/spotlights.md#spotlights)
 - [Subscriptions](sections/subscriptions.md#subscriptions)
 - [Templates](sections/templates.md#templates)
 - [Timeline](sections/timeline.md#timeline)

sections/questions.md

@@ -245,7 +245,7 @@ Update a question
 
 * `PUT /questions/2.json` allows changing the question with an ID of `2`.
 
-This endpoint will return `200 OK` with the current JSON representation of the question if the update was a success. See the [Get a question](#get-a-question) endpoint for more info on the payload.
+This endpoint will return `200 OK` with the current JSON representation of the question if the update was a success. Client users may only update a question they created; updating any other question returns `403 Forbidden`. See the [Get a question](#get-a-question) endpoint for more info on the payload.
 
 ###### Example JSON Request
 

sections/schedule_entries.md

@@ -293,7 +293,7 @@ _Optional parameters_:
 
 The remaining `recurrence_schedule` attributes shown in [Get a schedule entry](#get-a-schedule-entry) (`hour`, `minute`, `start_date`, `duration`, `end_date`) are derived from `starts_at`, `ends_at`, and `recurs_until` — they're ignored on input. An invalid `recurrence_schedule` is discarded on create: the entry is created without recurring.
 
-This endpoint will return `201 Created` with the current JSON representation of the schedule entry if the creation was a success. See the [Get a schedule entry](#get-a-schedule-entry) endpoint for more info on the payload.
+This endpoint will return `201 Created` with the current JSON representation of the schedule entry if the creation was a success. See the [Get a schedule entry](#get-a-schedule-entry) endpoint for more info on the payload. An entry that fails validation — a missing `starts_at` or `ends_at`, for example — returns `422 Unprocessable Entity` with a JSON `errors` payload.
 
 ###### Example JSON Request
 

sections/spotlights.md

@@ -0,0 +1,69 @@
+Spotlights
+==========
+
+A spotlight puts a recording's card on the home page of the project or template
+it belongs to, alongside the tools. A spotlight doesn't change who can see the
+recording: clients see a spotlight only when the recording is shared with them.
+A recording can be spotlighted once, and only in its own project or template.
+
+A spotlight isn't a resource of its own: it's a mark on the recording, like a
+pin. Spotlighting a recording returns that recording, and the project's `dock`
+array is unaffected, since spotlights aren't tools. See
+[recordings](recordings.md) for the shape of a recording and
+[Get a project](projects.md#get-a-project) for the dock.
+
+Endpoints:
+
+- [Spotlight a recording](#spotlight-a-recording)
+- [Remove a spotlight](#remove-a-spotlight)
+
+
+Spotlight a recording
+---------------------
+
+* `POST /recordings/2/spotlight.json` will spotlight the recording with an ID of
+  `2` on the home page of its project or template.
+
+No parameters are required. This endpoint returns `201 Created` with the
+recording that was spotlighted. Spotlighting a recording that's already
+spotlighted also returns `201 Created`.
+
+Not every recording can be spotlighted: containers such as message boards and
+to-do sets can't, nor can recordings that are archived or trashed. Those
+requests return `422 Unprocessable Entity`.
+Spotlighting also requires permission to edit the project, so clients and people
+without that permission get `403 Forbidden`.
+
+###### Copy as cURL
+
+```shell
+curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X POST \
+  https://3.basecampapi.com/$ACCOUNT_ID/recordings/2/spotlight.json
+```
+
+
+Remove a spotlight
+------------------
+
+* `DELETE /recordings/2/spotlight.json` will remove the spotlight on the
+  recording with an ID of `2`.
+
+This endpoint returns `204 No Content`. Removing a spotlight that doesn't exist
+also returns `204 No Content`.
+
+###### Copy as cURL
+
+```shell
+curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \
+  https://3.basecampapi.com/$ACCOUNT_ID/recordings/2/spotlight.json
+```
+
+
+Legacy project-scoped routes
+-----------------------------
+
+The following project-scoped routes are still supported and will remain
+available, but flat routes above are the canonical form for new integrations.
+
+* `POST /buckets/1/recordings/2/spotlight.json` → [Spotlight a recording](#spotlight-a-recording)
+* `DELETE /buckets/1/recordings/2/spotlight.json` → [Remove a spotlight](#remove-a-spotlight)