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