canonical: https://jentic.com/apis/3.basecampapi.com/basecamp

# 3 Basecampapi Basecamp 3 API

Jentic publishes the only available OpenAPI specification for Basecamp 3 API, keeping it validated and agent-ready. The Basecamp 3 API is a JSON REST interface to Basecamp's project management workspace, covering projects, message boards, to-do sets, to-dos, people, comments, documents, vaults, Campfires, schedules, uploads, webhooks, and recordings. All requests are scoped to an account ID in the base URL and authenticated with an OAuth 2.0 bearer token. The spec exposes 74 endpoints across 24 resource tags, enough to drive most workflow automation that Basecamp users do in the UI.

## For AI agents

Create and update Basecamp 3 projects, to-dos, messages, documents, and comments, list people on a project, and post into Campfire chats using OAuth 2.0 bearer auth.

## Scope

Does not handle billing, time tracking, video calls, or external file storage - use for project, to-do, message, document, and comment management inside a Basecamp 3 account only.

## Capabilities

- Create and update Basecamp projects, including archiving and trashing through status filters
- Manage to-do lists and individual to-dos - create, complete, uncomplete, reposition, and assign people
- Post and update messages on a project's message board with rich-text HTML content
- List and grant or revoke project access for specific people via the project users endpoint
- Create and update documents inside a project's vault for shared reference material
- Read Campfire chat lines and list all Campfires the authenticated user can access
- Add and update threaded comments on any Basecamp recording (message, to-do, document, or upload)

## Use cases

### Client Project Bootstrapping

When onboarding a new client, automatically create a Basecamp project, populate an initial to-do list, post a kick-off message, and grant the client team members access. POST /projects.json creates the project, POST /todosets/{todoSetId}/todolists.json adds the list, and PUT /projects/{projectId}/people/users.json grants access in a single workflow rather than clicking through the UI.

Example prompt: Create a Basecamp project named 'Acme Q3 Redesign', add a to-do list 'Kickoff', create the to-dos 'Send brief', 'Schedule kickoff call', and 'Confirm scope', and grant access to two emails.

### Status Reporting From To-Dos

Pull current to-do state from Basecamp to feed an external dashboard or weekly status email. GET /todolists/{todoListId}/todos.json with completed=true or completed=false returns to-dos by completion state so a reporting job can compute on-time vs overdue counts without scraping the UI.

Example prompt: For project ID 12345, fetch all to-do lists, then list completed and outstanding to-dos for each, and produce a weekly summary email.

### Cross-Tool Message Mirroring

Mirror messages posted in Slack or another chat tool into a Basecamp project's message board so durable decisions live alongside the work. POST /message_boards/{messageBoardId}/messages.json accepts a subject and HTML body, and POST /recordings/{recordingId}/comments.json lets follow-ups land as threaded comments.

Example prompt: Post a message titled 'Decision: API contract approved' with a one-paragraph HTML body to message board 5678, then attach a comment summarising the next step.

### AI Agent Project Operations

Let an AI agent run routine Basecamp operations - create to-dos from a meeting transcript, archive completed projects, post weekly recaps - through Jentic. The agent searches for the operation by intent, loads the spec, and executes; OAuth tokens stay isolated in Jentic's vault.

Example prompt: Through Jentic, search 'create a basecamp todo', load the createTodo schema, and add follow-up to-dos to list 9876 from a meeting transcript.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /projects.json | Create a new project |
| GET | /projects.json | List all projects |
| POST | /todolists/{todoListId}/todos.json | Create a to-do in a list |
| POST | /todos/{todoId}/completion.json | Mark a to-do complete |
| POST | /message_boards/{messageBoardId}/messages.json | Post a message to a board |
| POST | /recordings/{recordingId}/comments.json | Add a comment to a recording |
| PUT | /projects/{projectId}/people/users.json | Grant or revoke project access |

## Key resources

- **Projects** — Create, update, list, and retrieve Basecamp projects
- **Todos / TodoLists / TodoSets** — Manage to-do sets, lists, and individual to-dos including completion and repositioning
- **Messages / MessageBoards** — Post and update messages on project message boards
- **People** — List people on a project, grant or revoke access, retrieve profiles
- **Comments** — Read, create, and update threaded comments on any recording
- **Documents / Vaults** — Create and update documents inside project vaults
- **Campfires** — List Campfires and read chat lines

## Why Jentic

- **Setup:** Wiring the Basecamp 3 API by hand means managing its OAuth 2.0 bearer and refresh tokens and stitching your account id into the base URL yourself. Through Jentic you install once, import the Basecamp 3 API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Basecamp 3 puts the project and recording id in the URL path (/projects/{projectId}/..., /todolists/{todoListId}/todos.json), so a rule can pin your agent to one project: it can add todos and messages there and nothing else. You choose the operations it may call, so managing project people is not included unless you add it.
- **Credential handling:** Your Basecamp 3 OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Basecamp todo' or 'post a message to a project', and Jentic returns the matching Basecamp 3 operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Asana API** — Asana offers a richer task hierarchy with sections, custom fields, and portfolios for larger product teams.
- **Trello API** — Trello uses a board-and-card model rather than Basecamp's project-and-todo-list structure.
- **Linear API** — Linear targets engineering issue tracking with cycles and triage queues rather than general project management.
- **Slack API** — Mirror Slack threads into Basecamp messages or comments so decisions persist alongside the work.

## FAQ

### Why is there no official OpenAPI spec for Basecamp 3 API?

Basecamp publishes Markdown reference docs at github.com/basecamp/bc3-api but no OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Basecamp 3 API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Basecamp 3 API use?

Basecamp 3 uses OAuth 2.0 bearer tokens, sent in the Authorization header. Through Jentic, OAuth tokens are stored encrypted in the vault and refreshed automatically, so the agent never handles raw client secrets or refresh tokens.

### Can I create and complete to-dos with the Basecamp 3 API?

Yes. POST /todolists/{todoListId}/todos.json creates a to-do with content, due date, and assignees, POST /todos/{todoId}/completion.json marks it complete, and DELETE /todos/{todoId}/completion.json reopens it. Repositioning is handled by PUT /todos/{todoId}/position.json.

### What are the rate limits for the Basecamp 3 API?

Basecamp enforces a documented limit of 50 requests per 10-second window per access token; exceeding it returns 429 Too Many Requests with a Retry-After header. Build retries with exponential backoff and respect Retry-After when calling at scale.

### How do I post a message to a Basecamp project through Jentic?

Run pip install jentic, then search 'post a basecamp message', load the createMessage operation, supply messageBoardId plus a subject and HTML content body, and execute. Run it through Jentic One, the self-hosted execution layer to receive an agent API key.

### Does the Basecamp 3 API require an account ID in every request?

Yes. The base URL is https://3.basecampapi.com/{accountId}, and every endpoint path is appended to that account-scoped prefix. The account ID is returned alongside the access token during the OAuth 2.0 authorisation flow.

### Can I limit what my agent is allowed to do with the Basecamp 3 API?

Yes. Because you run Jentic One yourself, your own rules decide which Basecamp 3 operations and credentials the agent may use. Basecamp 3 carries the project and recording id in the URL path (for example /projects/{projectId}/... and /todolists/{todoListId}/todos.json), so a rule can pin the agent to a single project where it adds to-dos via POST /todolists/{todoListId}/todos.json and posts to a board via POST /message_boards/{messageBoardId}/messages.json and nothing else. You also pick the exact operations it may call, so an action like granting project access through PUT /projects/{projectId}/people/users.json stays off unless you add it.