diff --git a/README.md b/README.md index 761b49b..715f21d 100644 --- a/README.md +++ b/README.md @@ -298,6 +298,7 @@ API endpoints - [Comments](sections/comments.md#comments) - [Documents](sections/documents.md#documents) - [Events](sections/events.md#events) +- [External links](sections/external_links.md#external-links) - [Forwards](sections/forwards.md#forwards) - [Gauges](sections/gauges.md#gauges) - [Hill charts](sections/hill_charts.md#hill-charts) diff --git a/sections/external_links.md b/sections/external_links.md new file mode 100644 index 0000000..980786c --- /dev/null +++ b/sections/external_links.md @@ -0,0 +1,136 @@ +External links +============== + +External links (previously known as **doors**) are quick links to outside services like Dropbox, Google Drive, Trello, or any arbitrary URL that appear in a project's "External links" section. Each external link has a service type, URL, title, and optional description. + +External links are a separate collection from tools and do not appear in the project's `dock` array. The endpoint URLs continue to use the original `doors` resource name. + +Endpoints: + +- [Get an external link](#get-an-external-link) +- [Create an external link](#create-an-external-link) +- [Update an external link](#update-an-external-link) +- [Trash an external link](#trash-an-external-link) + + +Get an external link +-------------------- + +* `GET /buckets/1/dock/doors/2.json` for the external link with ID `2` in the project with ID `1`. + +This endpoint behaves as a redirector rather than returning a JSON resource: it responds with `302 Found` and a `Location` header pointing to the external link's `url`. There is currently no public endpoint that returns the JSON representation of a single external link. + +To retrieve external link metadata (id, title, url, service, status), use [Search](search.md#search) and filter results by `type: "Door"`. The shape returned in search results is shown below. + +###### Example JSON Response + +```json +{ + "id": 1069479500, + "status": "active", + "visible_to_clients": false, + "created_at": "2026-02-12T06:09:34.667Z", + "updated_at": "2026-02-12T06:13:57.731Z", + "title": "Design system", + "inherits_status": true, + "type": "Door", + "url": "https://www.figma.com/file/abc", + "app_url": "https://3.basecampapi.com/195539477/buckets/2085958504/dock/doors/1069479500", + "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiLmdpZDovL2JjMy9SZWNvcmRpbmcvMTA2OTQ3OTUwMD9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg1yZWFkYWJsZQY7AFQ=--placeholder.json", + "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958504/recordings/1069479500/subscription.json", + "position": 1, + "bucket": { + "id": 2085958504, + "name": "The Leto Laptop", + "type": "Project" + }, + "creator": { + "id": 1049715913, + "name": "Victor Cooper", + "email_address": "victor@honchodesign.com" + }, + "service": { + "name": "Figma", + "example_url": "https://www.figma.com/file/...", + "code": "figma", + "valid_patterns": ["www\\.figma\\.com\\/file\\/.+"], + "supporting_text": null + }, + "description": null, + "content": null +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -A "MyApp (yourname@example.com)" \ + https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/dock/doors/2.json +``` + + +Create an external link +----------------------- + +* `POST /buckets/1/dock/doors.json` creates a new external link in the project with ID `1`. + +**Required parameters**: +* `door[service]` - the service type. Use `other` for a generic external link, or one of `dropbox`, `google_drive`, `trello`, `github`, `figma`, `airtable`, `notion`, `slack`, `zoom`. Unrecognized values return `422 Unprocessable Entity`. +* `door[url]` - the URL the link points to. +* `door[title]` - the title shown in the External links section. + +_Optional parameters_: +* `door[description]` - a short description shown beneath the title. +* `door[image]` - a thumbnail image (binary, multipart upload). + +Unlike most BC3 endpoints, this endpoint expects parameters in `application/x-www-form-urlencoded` form (with bracketed keys), not JSON. It returns `302 Found` redirecting to the project's dock edit page on success with an empty response body. The new external link's ID is not returned — discover it via [Search](search.md#search). + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -A "MyApp (yourname@example.com)" \ + --data-urlencode "door[service]=other" \ + --data-urlencode "door[url]=https://example.com" \ + --data-urlencode "door[title]=External link" \ + --data-urlencode "door[description]=Optional description" \ + https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/dock/doors.json +``` + + +Update an external link +----------------------- + +* `PUT /buckets/1/dock/doors/2.json` updates the external link with ID `2` in the project with ID `1`. + +Any of the [Create an external link](#create-an-external-link) parameters may be supplied. Like create, this endpoint expects `application/x-www-form-urlencoded` parameters with bracketed keys and returns `302 Found` redirecting to the project's dock edit page on success with an empty response body. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -A "MyApp (yourname@example.com)" \ + -X PUT \ + --data-urlencode "door[title]=Updated title" \ + --data-urlencode "door[url]=https://example.com/new-path" \ + https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/dock/doors/2.json +``` + + +Trash an external link +---------------------- + +* `DELETE /buckets/1/dock/doors/2.json` trashes the external link with ID `2` in the project with ID `1`. + +This endpoint will return `204 No Content` if successful. Trashed external links are soft-deleted: their `status` becomes `"deleted"` (visible in [Search](search.md#search) results) and they no longer appear in the project's External links section. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -A "MyApp (yourname@example.com)" \ + -X DELETE \ + https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/dock/doors/2.json +```