Documentation
Documentation
https://github.com/basecamp/bc3-api
Documentation
https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md
OpenAPI Specification
openapi: 3.1.0
info:
title: Basecamp Authorization To-Dos API
description: The Basecamp API is a REST API that provides programmatic access to Basecamp's project management and team communication platform. It enables developers to manage projects, to-do lists, messages, documents, schedules, campfires, uploads, card tables, templates, and team members across Basecamp accounts. The API uses OAuth 2.0 for authentication and returns JSON responses, with all requests scoped to an account ID in the base URL path. Resources include projects, people, to-dos, message boards, documents, card tables, campfires, questionnaires, and webhooks, covering the full breadth of Basecamp's collaboration toolset.
version: '1.0'
contact:
name: Basecamp Developer Support
url: https://github.com/basecamp/bc3-api
termsOfService: https://basecamp.com/terms
servers:
- url: https://3.basecampapi.com/{accountId}
description: Production Server
variables:
accountId:
description: Your Basecamp account ID
default: '999999999'
security:
- bearerAuth: []
tags:
- name: To-Dos
description: Manage individual to-do items
paths:
/todolists/{todolistId}/todos.json:
get:
operationId: listTodos
summary: List to-dos
description: Returns a paginated list of active to-dos in the specified to-do list. Set completed=true to retrieve completed items instead.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodolistId'
- name: status
in: query
required: false
description: Filter by status.
schema:
type: string
enum:
- archived
- trashed
- name: completed
in: query
required: false
description: Set to true to return completed to-dos.
schema:
type: boolean
responses:
'200':
description: List of to-dos
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Todo'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createTodo
summary: Create a to-do
description: Creates a new to-do in the specified to-do list. Supports assignees, due dates, start dates, and completion subscriber notifications.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodolistId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TodoCreateRequest'
responses:
'201':
description: To-do created
content:
application/json:
schema:
$ref: '#/components/schemas/Todo'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/todos/{todoId}.json:
get:
operationId: getTodo
summary: Get a to-do
description: Returns the to-do with the given ID.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodoId'
responses:
'200':
description: To-do details
content:
application/json:
schema:
$ref: '#/components/schemas/Todo'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateTodo
summary: Update a to-do
description: Updates the content, description, assignees, due date, or other fields of the specified to-do.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodoId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TodoCreateRequest'
responses:
'200':
description: Updated to-do
content:
application/json:
schema:
$ref: '#/components/schemas/Todo'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/todos/{todoId}/completion.json:
post:
operationId: completeTodo
summary: Complete a to-do
description: Marks the specified to-do as completed and notifies completion subscribers.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodoId'
responses:
'204':
description: To-do marked as completed
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: uncompleteTodo
summary: Uncomplete a to-do
description: Marks the specified to-do as incomplete, reversing a previous completion.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodoId'
responses:
'204':
description: To-do marked as incomplete
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/todos/{todoId}/position.json:
put:
operationId: repositionTodo
summary: Reposition a to-do
description: Changes the position of the specified to-do within its to-do list. Position is 1-indexed.
tags:
- To-Dos
parameters:
- $ref: '#/components/parameters/TodoId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PositionRequest'
responses:
'204':
description: Position updated
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
TodoId:
name: todoId
in: path
required: true
description: Unique identifier of the to-do
schema:
type: integer
TodolistId:
name: todolistId
in: path
required: true
description: Unique identifier of the to-do list
schema:
type: integer
schemas:
Recording:
type: object
description: A generic recording object representing any Basecamp content resource such as a message, to-do, document, comment, or upload.
properties:
id:
type: integer
description: Recording ID
status:
type: string
description: Recording status
enum:
- active
- archived
- trashed
visible_to_clients:
type: boolean
description: Whether this recording is visible to client users
created_at:
type: string
format: date-time
description: Timestamp when the recording was created
updated_at:
type: string
format: date-time
description: Timestamp when the recording was last updated
title:
type: string
description: Title or summary of the recording
inherits_status:
type: boolean
description: Whether this recording inherits its status from a parent
type:
type: string
description: Recording type (e.g., Message, Todo, Document)
url:
type: string
format: uri
description: API URL for this recording
app_url:
type: string
format: uri
description: Web URL for this recording
bucket:
$ref: '#/components/schemas/BucketRef'
creator:
$ref: '#/components/schemas/PersonRef'
PersonRef:
type: object
description: Minimal reference to a Basecamp person
properties:
id:
type: integer
description: Person ID
attachable_sgid:
type: string
description: Signed global ID for attaching this person
name:
type: string
description: Full name
email_address:
type: string
format: email
description: Email address
personable_type:
type: string
description: Type of personable (User, Client, etc.)
title:
type: string
description: Job title
bio:
type: string
description: Short biography
location:
type: string
description: Location string
created_at:
type: string
format: date-time
description: Account creation timestamp
updated_at:
type: string
format: date-time
description: Last update timestamp
admin:
type: boolean
description: Whether the person is an account administrator
owner:
type: boolean
description: Whether the person is the account owner
client:
type: boolean
description: Whether the person is a client user
employee:
type: boolean
description: Whether the person is an employee
time_zone:
type: string
description: IANA time zone name
avatar_url:
type: string
format: uri
description: URL to the person's avatar image
company:
type: object
description: Company the person belongs to
properties:
id:
type: integer
description: Company ID
name:
type: string
description: Company name
BucketRef:
type: object
description: Reference to the project (bucket) that contains a resource
properties:
id:
type: integer
description: Project ID
name:
type: string
description: Project name
type:
type: string
description: Resource type, always "Project"
url:
type: string
format: uri
description: API URL for the project
app_url:
type: string
format: uri
description: Web URL for the project
TodoCreateRequest:
type: object
required:
- content
properties:
content:
type: string
description: To-do text description
description:
type: string
description: Additional details in HTML format
assignee_ids:
type: array
description: Person IDs to assign to this to-do
items:
type: integer
completion_subscriber_ids:
type: array
description: Person IDs to notify when this to-do is completed
items:
type: integer
notify:
type: boolean
description: Whether to immediately notify assignees
due_on:
type: string
format: date
description: Due date in ISO 8601 format
starts_on:
type: string
format: date
description: Start date in ISO 8601 format
Todo:
allOf:
- $ref: '#/components/schemas/Recording'
- type: object
properties:
content:
type: string
description: To-do text content
description:
type: string
description: HTML-formatted additional details
completed:
type: boolean
description: Whether this to-do has been completed
due_on:
type: string
format: date
description: Due date in ISO 8601 format
nullable: true
starts_on:
type: string
format: date
description: Start date in ISO 8601 format
nullable: true
position:
type: integer
description: Position within the to-do list
assignees:
type: array
description: People assigned to this to-do
items:
$ref: '#/components/schemas/PersonRef'
completion_subscribers:
type: array
description: People notified when this to-do is completed
items:
$ref: '#/components/schemas/PersonRef'
comments_count:
type: integer
description: Number of comments on this to-do
parent:
$ref: '#/components/schemas/Recording'
Error:
type: object
properties:
error:
type: string
description: Human-readable error message
PositionRequest:
type: object
required:
- position
properties:
position:
type: integer
description: New position within the list (1-indexed)
minimum: 1
responses:
BadRequest:
description: Bad request — missing required fields or invalid values
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized — missing or invalid Bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Not found — the requested resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'OAuth 2.0 Bearer token obtained via the Basecamp authorization code flow at launchpad.37signals.com. Include as "Authorization: Bearer {token}" in all requests.'
externalDocs:
description: Basecamp API Documentation
url: https://github.com/basecamp/bc3-api