Skip to content

Sync API docs from bc3 #446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jorgemanrubia merged 1 commit into from
Sep 17, 2026
Merged

Sync API docs from bc3 #446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,22 @@ The resource is called **person** (not user). Endpoints:
- `/projects/{id}/people.json` — people in a project
- `/my/profile.json` — current authenticated user (GET and PUT)

### Person types

A full person object includes a `personable_type` saying what kind of person it is. The [people endpoints](sections/people.md) return full person objects, and most embedded people, such as a recording's `creator`, use them too. Some responses use a minimal person object with only `id`, `name`, and `avatar_url` instead, for example [out of office](sections/out_of_office.md) and the `assignees` in [my assignments](sections/my_assignments.md). Don't assume `personable_type` is present.

The current types are:

- `User` — a member of the account: a team member (`"client": false`) or a client member (`"client": true`).
- `Agent` — an AI agent added to the account. Agents create content and use the API as themselves.
- `Integration` — a chatbot or service integration that posts into Basecamp.
- `Outsider` — someone outside the account whose email reached Basecamp, such as the sender of an [email forward](sections/forwards.md).
- `Client` — a client contact from the legacy clientside ([client correspondences](sections/client_correspondences.md), [approvals](sections/client_approvals.md), and [replies](sections/client_replies.md)). These people have `"client": false`, so check `personable_type` to identify them.
- `DummyUser` — a sample person in the example projects Basecamp creates for new accounts.
- `Tombstone` — a person who has been removed from the account, or an agent or chatbot that has been deleted. Their past content keeps its author.

**New person types may be added at any time, without a version change.** Treat `personable_type` as an open set: when you see a value you don't recognize, handle the person like any other (show their `name` and `avatar_url`) rather than failing to parse the response, and rely on the `admin`, `client`, and `can_*` flags, not the type, for what a person can do.

### To-do specifics

**Completion**: To-dos have a boolean `completed` field. By default, endpoints return active, pending (not completed) items. Use `?completed=true` for completed items. Use `?status=archived` or `?status=trashed` to see those.
Expand Down Expand Up @@ -291,6 +307,7 @@ API endpoints
- [Card table cards](sections/card_table_cards.md#card-table-cards)
- [Card table columns](sections/card_table_columns.md#card-table-columns)
- [Card table steps](sections/card_table_steps.md#card-table-steps)
- [Card table templates](sections/card_table_templates.md#card-table-templates)
- [Card table wormholes](sections/card_table_wormholes.md#card-table-wormholes)
- [Card tables](sections/card_tables.md#card-tables)
- [Chatbots](sections/chatbots.md#chatbots)
Expand All @@ -302,6 +319,7 @@ API endpoints
- [Comments](sections/comments.md#comments)
- [Documents](sections/documents.md#documents)
- [Drafts](sections/drafts.md#drafts)
- [Event feed](sections/event_feed.md#event-feed)
- [Events](sections/events.md#events)
- [Everything](sections/everything.md#everything)
- [External links](sections/external_links.md#external-links)
Expand Down Expand Up @@ -336,6 +354,7 @@ API endpoints
- [Subscriptions](sections/subscriptions.md#subscriptions)
- [Subtasks](sections/subtasks.md#subtasks)
- [Templates](sections/templates.md#templates)
- [Templatifications](sections/templatifications.md#templatifications)
- [Timeline](sections/timeline.md#timeline)
- [Timesheets](sections/timesheets.md#timesheets)
- [To-do list groups](sections/todolist_groups.md#to-do-list-groups)
Expand Down
27 changes: 15 additions & 12 deletions sections/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,17 +137,15 @@ Get authorization from Basecamp

Basecamp serves its own authorization document at the API root — no account
prefix — for any token it accepts: a Basecamp-issued OAuth token or personal
access token, or a legacy Launchpad-issued token. It mirrors Launchpad's
document above, with a few deliberate differences:

- `identity` carries only `id`. The name and email fields are omitted: they
were never suitable for identifying users within Basecamp (see the note on
the Launchpad document above) — use the [Get person][people] endpoints.
- Each account carries a `resource` indicator (`urn:bc:account:<id>`,
RFC 8707) instead of Launchpad's `product` and `app_href`. Pass it as the
`resource` parameter when requesting a token scoped to that account. A
client that reads both documents must treat `product` and `app_href` as
optional and select accounts by `href` or `resource`.
access token, or a legacy Launchpad-issued token. It carries the same
`identity` and `accounts` fields as Launchpad's document above — the same
`product: "bc3"` selection works against either issuer, and the identity's
name and email remain **not** for identifying users within Basecamp (use the
[Get person][people] endpoints) — plus a few additions:

- Each account also carries a `resource` indicator (`urn:bc:account:<id>`,
RFC 8707). Pass it as the `resource` parameter when requesting a token
scoped to that account.
- `scope` is present for every Basecamp-issued token — OAuth and personal
access tokens alike. Legacy Launchpad-issued tokens predate scopes, so a
missing `scope` is not an error.
Expand All @@ -158,13 +156,18 @@ document above, with a few deliberate differences:
```json
{
"identity": {
"id": 9999999
"id": 9999999,
"first_name": "Jason",
"last_name": "Fried",
"email_address": "jason@basecamp.com"
},
"accounts": [
{
"product": "bc3",
"id": 99999999,
"name": "Honcho Design",
"href": "https://3.basecampapi.com/99999999",
"app_href": "https://app.basecamp.com/99999999",
"resource": "urn:bc:account:99999999"
}
],
Expand Down
4 changes: 2 additions & 2 deletions sections/boosts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,9 +160,9 @@ Create a boost
* `POST /recordings/2/boosts.json` publishes a boost on the recording with an ID of `2`.
* `POST /recordings/2/events/3/boosts.json` publishes a boost on the event with ID `3` on the recording with ID of `2`. Only boostable events (`completed`, `adopted`, `column_changed`) accept boosts; other events will return `403 Forbidden`.

**Required parameters**: `content` as the body of the boost.
**Required parameters**: `content` as the body of the boost, up to 191 characters.

This endpoint will return `201 Created` with the current JSON representation of the boost if the creation was a success. See the [Get a boost](#get-a-boost) endpoint for more info on the payload.
This endpoint will return `201 Created` with the current JSON representation of the boost if the creation was a success, or `422 Unprocessable Entity` if `content` is missing or too long. See the [Get a boost](#get-a-boost) endpoint for more info on the payload.

###### Example JSON Request

Expand Down
Loading