Manage project templates and construct projects from them
openapi: 3.1.0
info:
title: Basecamp Authorization Templates 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: Templates
description: Manage project templates and construct projects from them
paths:
/templates.json:
get:
operationId: listTemplates
summary: List templates
description: Returns a paginated list of active project templates visible to the authenticated user. Optionally filter by status.
tags:
- Templates
parameters:
- name: status
in: query
description: Filter templates by status.
required: false
schema:
type: string
enum:
- archived
- trashed
responses:
'200':
description: List of templates
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Template'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createTemplate
summary: Create a template
description: Creates a new project template with the given name and optional description. Returns the template with a 201 Created status.
tags:
- Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateCreateRequest'
responses:
'201':
description: Template created
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/templates/{templateId}.json:
get:
operationId: getTemplate
summary: Get a template
description: Returns the project template with the given ID.
tags:
- Templates
parameters:
- $ref: '#/components/parameters/TemplateId'
responses:
'200':
description: Template details
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateTemplate
summary: Update a template
description: Updates the name and description of an existing project template.
tags:
- Templates
parameters:
- $ref: '#/components/parameters/TemplateId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateCreateRequest'
responses:
'200':
description: Updated template
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteTemplate
summary: Delete a template
description: Moves the template with the given ID to trash.
tags:
- Templates
parameters:
- $ref: '#/components/parameters/TemplateId'
responses:
'204':
description: Template trashed
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/templates/{templateId}/project_constructions.json:
post:
operationId: createProjectFromTemplate
summary: Create project from template
description: Starts the construction of a new project based on the given template. Returns a project construction object whose status can be polled until it transitions from "pending" to "completed".
tags:
- Templates
parameters:
- $ref: '#/components/parameters/TemplateId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectConstructionRequest'
responses:
'201':
description: Project construction initiated
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectConstruction'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/templates/{templateId}/project_constructions/{constructionId}.json:
get:
operationId: getProjectConstruction
summary: Get project construction status
description: Returns the current status of a project construction job. Poll this endpoint until status changes from "pending" to "completed".
tags:
- Templates
parameters:
- $ref: '#/components/parameters/TemplateId'
- $ref: '#/components/parameters/ConstructionId'
responses:
'200':
description: Project construction status
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectConstruction'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
ConstructionId:
name: constructionId
in: path
required: true
description: Unique identifier of the project construction job
schema:
type: integer
TemplateId:
name: templateId
in: path
required: true
description: Unique identifier of the template
schema:
type: integer
schemas:
Template:
type: object
required:
- id
- name
- status
properties:
id:
type: integer
description: Template ID
status:
type: string
description: Template status
enum:
- active
- archived
- trashed
created_at:
type: string
format: date-time
description: Timestamp when the template was created
updated_at:
type: string
format: date-time
description: Timestamp when the template was last updated
name:
type: string
description: Template name
description:
type: string
description: Template description
nullable: true
url:
type: string
format: uri
description: API URL for this template
app_url:
type: string
format: uri
description: Web URL for this template
dock:
type: array
description: Tools available in this template
items:
$ref: '#/components/schemas/DockItem'
ProjectConstruction:
type: object
properties:
id:
type: integer
description: Project construction job ID
status:
type: string
description: Construction status
enum:
- pending
- completed
url:
type: string
format: uri
description: API URL to poll for this construction job
project:
$ref: '#/components/schemas/Project'
description: The resulting project once construction is completed
ProjectConstructionRequest:
type: object
required:
- project
properties:
project:
type: object
required:
- name
properties:
name:
type: string
description: Name for the new project being constructed
description:
type: string
description: Optional description for the new project
TemplateCreateRequest:
type: object
required:
- name
properties:
name:
type: string
description: Template name
description:
type: string
description: Optional template description
DockItem:
type: object
description: A tool available on a project's dock
properties:
id:
type: integer
description: Dock item ID
title:
type: string
description: Display title of the tool
name:
type: string
description: Internal name of the tool (e.g., message_board, todoset)
enabled:
type: boolean
description: Whether this tool is enabled on the project
position:
type: integer
description: Display position of the tool in the dock
nullable: true
url:
type: string
format: uri
description: API URL for this tool's resource
app_url:
type: string
format: uri
description: Web URL for this tool's resource
Project:
type: object
required:
- id
- name
- status
properties:
id:
type: integer
description: Unique project identifier
status:
type: string
description: Project status (active, archived, trashed)
enum:
- active
- archived
- trashed
created_at:
type: string
format: date-time
description: Timestamp when the project was created
updated_at:
type: string
format: date-time
description: Timestamp when the project was last updated
name:
type: string
description: Project name
description:
type: string
description: Project description
nullable: true
purpose:
type: string
description: Project purpose classification
clients_enabled:
type: boolean
description: Whether client access is enabled for this project
timesheet_enabled:
type: boolean
description: Whether timesheets are enabled for this project
color:
type: string
description: Project color identifier
nullable: true
url:
type: string
format: uri
description: API URL for this project
app_url:
type: string
format: uri
description: Web URL for this project
bookmark_url:
type: string
format: uri
description: API URL to bookmark this project
dock:
type: array
description: List of tools available on this project
items:
$ref: '#/components/schemas/DockItem'
Error:
type: object
properties:
error:
type: string
description: Human-readable error message
responses:
BadRequest:
description: Bad request — missing required fields or invalid values
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'
Unauthorized:
description: Unauthorized — missing or invalid Bearer token
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