Basecamp API

To check if a specific resource (like a recording or message) can be commented on, inspect its JSON response for the presence of the following two attributes:

• comments_count
• comments_url

When accessing assignees or creator fields in a Todo, you receive a User object containing:

• id: Unique user identifier.
• name: Full name of the user.
• email_address: User's email.
• personable_type: Always User for these objects.
• attachable_sgid: A secure global ID used for attaching the user to other resources.
• avatar_url: Link to the user's profile image.
• can_manage_projects, can_manage_people, etc.: Boolean permissions for the user.

{
  "id": 1049715938,
  "name": "Annie Bryan",
  "personable_type": "User",
  "email_address": "annie@honchodesign.com",
  "avatar_url": "https://3.basecampapi.com/195539477/people/.../avatar"
}

Basecamp represents content for resources like messages, documents, and comments as rich text in HTML.

Reading rich text

• Rendering: Use a web view component to render the HTML unmodified.
• Plain-text conversion: To get a plain-text version, decode HTML entities, replace <br> tags with line breaks, and then strip all remaining HTML tags.

Writing rich text

• Requirements: You must generate well-formed HTML, properly encoding HTML entities and replacing line breaks with <br> tags.
• Modifying existing content: Use a full HTML parser (like Nokogiri for Ruby or Cheerio for Node.js) to ensure you do not discard formatting or attachments during manipulation.

Basecamp webhooks notify your application via HTTPS when specific events occur. A webhook is configured with a payload_url (must be HTTPS) and a list of types that trigger the calls.

Delivery Behavior:

• Basecamp attempts to call the URL up to 10 times with exponential backoff before deactivating the webhook.
• A successful response is defined as any HTTP status code in the 2xx range.
• Basecamp will not follow 3xx redirects.
• For debugging, Basecamp maintains a delivery record containing the full request and response for the 25 most recent delivery attempts.

Status Propagation Note: As of July 1, 2024, Basecamp does not notify of changes that are automatically propagated to children (e.g., archiving a Todolist will only trigger a webhook for the parent Todolist, not for the individual Todos or Comments inside it).

Tools are the specific features available within a project's 'dock' (e.g., Message Board, To-dos, Docs & Files, Campfire, Schedule).

To discover which tools are currently in a project, inspect the dock array in the response from the [Get a project] endpoint. Each entry in the dock array provides:

• id: The unique identifier for the tool.
• name: The tool's name.
• title: The display title.
• enabled: The current status of the tool.
• position: The tool's order in the dock.

Every rich text attribute in an API response (e.g., content, description) is accompanied by a corresponding *_attachments array. This array contains structured metadata for every downloadable file attachment embedded in the HTML.

Note: This array includes only downloadable file attachments. It excludes mentions, content attachments, remote images, and opengraph embeds. The array is always present, even if empty.

Common mapping:

• content $\rightarrow$ content_attachments
• description $\rightarrow$ description_attachments

Metadata fields per entry:

• id
• sgid
• filename
• content_type
• byte_size
• download_url
• width
• height
• previewable
• preview_url
• thumbnail_url

Most collection APIs are paginated using a geared ratio (15 results on page 1, 30 on page 2, 50 on page 3, and 100 on page 4+).

Do not construct pagination URLs manually. Instead, follow the RFC5988 convention by using the Link header provided in the response to find the URL for the next page. If the Link header is absent, you have reached the last page.

The API also provides an X-Total-Count header indicating the total number of resources in the collection.

Link: <https://3.basecampapi.com/999999999/message_boards/3/messages.json?page=4>; rel="next"

Gauges visualize project progress using a needle position (0–100), a color indicator (green, yellow, or red), and an optional description.

Key Concepts:

• Automatic Creation: Gauges are automatically created when a project is created. You can check for gauge data in a project response by looking for last_needle_color and last_needle_position.
• History via Needles: Each time progress is recorded, a new gauge needle is created. This preserves a history of updates rather than just overwriting a single value.
• Immutability: In a gauge needle, the position and color are immutable after creation. To record a new progress update, you must create a new gauge needle instead of updating an existing one. Only the description can be updated on an existing needle.