From 4b35ecb9a6867ecfd2cf6f248477195806835a63 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Mon, 31 Aug 2026 18:19:53 -0700 Subject: [PATCH] Sync API docs from bc3: spotlights, questions 403 note, schedule entries 422 note --- README.md | 1 + sections/questions.md | 2 +- sections/schedule_entries.md | 2 +- sections/spotlights.md | 69 ++++++++++++++++++++++++++++++++++++ 4 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 sections/spotlights.md diff --git a/README.md b/README.md index ab04b9e..cd58715 100644 --- a/README.md +++ b/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) diff --git a/sections/questions.md b/sections/questions.md index 9356827..e1f14b0 100644 --- a/sections/questions.md +++ b/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 diff --git a/sections/schedule_entries.md b/sections/schedule_entries.md index f8848be..afefbfe 100644 --- a/sections/schedule_entries.md +++ b/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 diff --git a/sections/spotlights.md b/sections/spotlights.md new file mode 100644 index 0000000..4c7b8de --- /dev/null +++ b/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)