openapi: 3.1.0
info:
  title: Filevine Tasks API
  description: >
    The Tasks API manages assignable work items on a Filevine project — to-do
    items routed to staff, with due dates, statuses, priority, and task
    chains generated by workflow automation. Tasks are distinct from notes
    and deadlines and have their own assignment and completion lifecycle.
  version: '2.0'
  contact:
    name: Filevine API Support
    url: https://developer.filevine.io/
  license:
    name: Filevine Terms of Service
    url: https://www.filevine.com/terms-of-service/

servers:
  - url: https://api.filevine.io
    description: Filevine API Gateway (US)
  - url: https://api.filevineapp.ca
    description: Filevine API Gateway (Canada)

security:
  - BearerAuth: []

tags:
  - name: Tasks
    description: Project tasks.

paths:
  /core/projects/{projectId}/tasks:
    parameters:
      - name: projectId
        in: path
        required: true
        schema: { type: integer, format: int64 }
    get:
      summary: Filevine List Project Tasks
      description: List tasks on a project filtered by assignee, status, and due date.
      operationId: listProjectTasks
      tags: [Tasks]
      parameters:
        - name: assigneeId
          in: query
          schema: { type: integer, format: int64 }
        - name: status
          in: query
          schema:
            type: string
            enum: [open, inProgress, completed, cancelled]
      responses:
        '200':
          description: Task list.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskList' }
    post:
      summary: Filevine Create Task
      description: Create a task on a project and assign it to a user.
      operationId: createTask
      tags: [Tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateTaskRequest' }
      responses:
        '201':
          description: Task created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Task' }
  /core/tasks/{taskId}:
    parameters:
      - name: taskId
        in: path
        required: true
        schema: { type: integer, format: int64 }
    patch:
      summary: Filevine Update Task
      description: Update a task status, due date, assignee, or priority.
      operationId: updateTask
      tags: [Tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateTaskRequest' }
      responses:
        '200':
          description: Task updated.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Task:
      type: object
      properties:
        taskId: { type: integer, format: int64 }
        projectId: { type: integer, format: int64 }
        title: { type: string }
        body: { type: string }
        status:
          type: string
          enum: [open, inProgress, completed, cancelled]
        priority:
          type: string
          enum: [low, normal, high, urgent]
        dueDate: { type: string, format: date-time }
        assigneeId: { type: integer, format: int64 }
        completedDate: { type: string, format: date-time }
    TaskList:
      type: object
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Task' }
        hasMore: { type: boolean }
    CreateTaskRequest:
      type: object
      required: [title, assigneeId]
      properties:
        title: { type: string }
        body: { type: string }
        assigneeId: { type: integer, format: int64 }
        dueDate: { type: string, format: date-time }
        priority:
          type: string
          enum: [low, normal, high, urgent]
    UpdateTaskRequest:
      type: object
      properties:
        status:
          type: string
          enum: [open, inProgress, completed, cancelled]
        priority:
          type: string
          enum: [low, normal, high, urgent]
        dueDate: { type: string, format: date-time }
        assigneeId: { type: integer, format: int64 }