openapi: 3.1.0
info:
  description: 'Fixture''s public v1 CRM API for Accounts, Contacts, Deals, Leads, Activities, Pipelines, Notes, and Tasks. Authenticate with `Authorization: Bearer ...` using either a Fixture API key or a Fixture OAuth access token.'
  title: Fixture Accounts Tasks API
  version: v1
servers:
- url: https://beta-api.fixture.app
security:
- bearerAuth: []
tags:
- description: Create, read, update, and delete Tasks.
  name: Tasks
paths:
  /api/v1/tasks:
    get:
      deprecated: false
      description: Return a paginated list of Tasks. Filter by `task_status_id`, `assignee_id`, and `entity_type` + `entity_id` together (to scope to one CRM record), plus `due_before`/`due_after` and created/updated timestamp windows. Pass `overdue=true` to limit results to Tasks past their due date and not in a completed status. Sort supports `created_at` or `-created_at`; pagination uses `limit` and `cursor`.
      operationId: listTasks
      parameters:
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Maximum number of records to return.
        in: query
        name: limit
        required: false
        schema:
          default: 50
          example: 50
          type: integer
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Opaque cursor returned by the previous page. Omit for the first page.
        in: query
        name: cursor
        required: false
        schema:
          example: eyJ2IjoxLCJzb3J0IjoiLWNyZWF0ZWRfYXQiLCJ2YWx1ZSI6IjIwMjYtMDMtMjJUMTQ6MDA6MDFaIiwiaWQiOiI2NjAxZDYxZC0xMTI5LTQyN2MtODI1NS0wOGI1ZjEyZGRhYjUifQ
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Sort by a supported field. Prefix with `-` for descending order.
        in: query
        name: sort
        required: false
        schema:
          default: -created_at
          example: -created_at
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Opaque Task status ID with the `taskstatus_` prefix.
        in: query
        name: task_status_id
        required: false
        schema:
          example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Opaque user ID with the `user_` prefix.
        in: query
        name: assignee_id
        required: false
        schema:
          example: user_9T5jXRFuLpTQ3nM4PkGvW2
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Filter to a specific related entity type.
        in: query
        name: entity_type
        required: false
        schema:
          enum:
          - account
          - contact
          - deal
          - lead
          example: contact
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Filter to one specific related entity. Requires `entity_type`.
        in: query
        name: entity_id
        required: false
        schema:
          example: contact_6M4jXRFuLpTQ3nM4PkGvW8
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only Tasks due on or before this ISO 8601 date.
        in: query
        name: due_before
        required: false
        schema:
          example: '2026-04-30'
          format: date
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only Tasks due on or after this ISO 8601 date.
        in: query
        name: due_after
        required: false
        schema:
          example: '2026-04-01'
          format: date
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only records created after this ISO 8601 timestamp.
        in: query
        name: created_after
        required: false
        schema:
          example: '2026-03-01T00:00:00Z'
          format: date-time
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only records created before this ISO 8601 timestamp.
        in: query
        name: created_before
        required: false
        schema:
          example: '2026-03-31T23:59:59Z'
          format: date-time
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only records updated after this ISO 8601 timestamp.
        in: query
        name: updated_after
        required: false
        schema:
          example: '2026-03-01T00:00:00Z'
          format: date-time
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only records updated before this ISO 8601 timestamp.
        in: query
        name: updated_before
        required: false
        schema:
          example: '2026-03-31T23:59:59Z'
          format: date-time
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: When true, return only Tasks past their due date and not in a done status.
        in: query
        name: overdue
        required: false
        schema:
          default: false
          example: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  completed_at: null
                  created_at: '2026-04-19T09:00:00Z'
                  created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  description: Confirm the renewal timeline after the quarterly review.
                  due_date: '2026-04-30'
                  entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                  entity_type: contact
                  id: task_8W3jXRFuLpTQ3nM4PkGvW0
                  task_status:
                    category: todo
                    color: gray
                    id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                    name: To Do
                    position: 0
                  task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                  title: Follow up with Acme
                  updated_at: '2026-04-19T09:00:00Z'
                pagination:
                  has_more: false
                  limit: 50
                  next_cursor: null
              schema:
                $ref: '#/components/schemas/V1TaskListPayload'
          description: Paginated Task list.
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: entity_type and entity_id must be provided together
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid filter, pagination, or sort parameter.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid or missing API key
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: 'Missing required scope: tasks:read'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
      security:
      - bearerAuth: []
      summary: List Tasks
      tags:
      - Tasks
    post:
      deprecated: false
      description: Create a new Task. Resolve the Task status by passing exactly one of `task_status_id` (a `taskstatus_` ID) or `task_status_name` (looked up case-insensitively among the organization's Task Statuses). To link the Task to a CRM record, pass `entity_type` and `entity_id` together.
      operationId: createTask
      requestBody:
        content:
          application/json:
            example:
              assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
              description: Confirm the renewal timeline after the quarterly review.
              due_date: '2026-04-30'
              entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
              entity_type: contact
              task_status_name: To Do
              title: Follow up with Acme
            schema:
              $ref: '#/components/schemas/V1CreateTaskRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                data:
                  assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  completed_at: null
                  created_at: '2026-04-19T09:00:00Z'
                  created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  description: Confirm the renewal timeline after the quarterly review.
                  due_date: '2026-04-30'
                  entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                  entity_type: contact
                  id: task_8W3jXRFuLpTQ3nM4PkGvW0
                  task_status:
                    category: todo
                    color: gray
                    id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                    name: To Do
                    position: 0
                  task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                  title: Follow up with Acme
                  updated_at: '2026-04-19T09:00:00Z'
              schema:
                $ref: '#/components/schemas/V1TaskDetailResponsePayload'
          description: Task created.
        '400':
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: 'Task status not found: VIP'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Validation error — includes missing required fields, blank optional strings, unknown references (e.g. a task_status_name with no match or a cross-org task_status_id), mutually-exclusive status inputs, and mismatched entity_type/entity_id pairs.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid or missing API key
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: 'Missing required scope: tasks:write'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
      security:
      - bearerAuth: []
      summary: Create a Task
      tags:
      - Tasks
  /api/v1/tasks/{task_id}:
    delete:
      deprecated: false
      description: Delete a Task by ID.
      operationId: deleteTask
      parameters:
      - deprecated: false
        description: Opaque Task ID with the `task_` prefix.
        in: path
        name: task_id
        required: true
        schema:
          example: task_8W3jXRFuLpTQ3nM4PkGvW0
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                deleted: true
                id: task_8W3jXRFuLpTQ3nM4PkGvW0
              schema:
                $ref: '#/components/schemas/V1TaskDeletePayload'
          description: Task deleted.
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: Invalid Task ID
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid Task ID.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid or missing API key
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: 'Missing required scope: tasks:write'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
        '404':
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Task not found
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Task not found.
      security:
      - bearerAuth: []
      summary: Delete a Task
      tags:
      - Tasks
    get:
      deprecated: false
      description: Return a single Task by its `task_` ID with full detail, including the assignee, linked entity (when set), and resolved Task status.
      operationId: getTask
      parameters:
      - deprecated: false
        description: Opaque Task ID with the `task_` prefix.
        in: path
        name: task_id
        required: true
        schema:
          example: task_8W3jXRFuLpTQ3nM4PkGvW0
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  completed_at: null
                  created_at: '2026-04-19T09:00:00Z'
                  created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  description: Confirm the renewal timeline after the quarterly review.
                  due_date: '2026-04-30'
                  entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                  entity_type: contact
                  id: task_8W3jXRFuLpTQ3nM4PkGvW0
                  task_status:
                    category: todo
                    color: gray
                    id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                    name: To Do
                    position: 0
                  task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                  title: Follow up with Acme
                  updated_at: '2026-04-19T09:00:00Z'
              schema:
                $ref: '#/components/schemas/V1TaskDetailResponsePayload'
          description: Task detail.
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: Invalid Task ID
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid Task ID.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid or missing API key
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: 'Missing required scope: tasks:read'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
        '404':
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Task not found
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Task not found.
      security:
      - bearerAuth: []
      summary: Get a Task
      tags:
      - Tasks
    patch:
      deprecated: false
      description: Partially update a Task by ID. `title`, `task_status_id`, and `task_status_name` are non-nullable — they cannot be cleared. When changing the status, pass either `task_status_id` or `task_status_name`, not both.
      operationId: updateTask
      parameters:
      - deprecated: false
        description: Opaque Task ID with the `task_` prefix.
        in: path
        name: task_id
        required: true
        schema:
          example: task_8W3jXRFuLpTQ3nM4PkGvW0
          type: string
      requestBody:
        content:
          application/json:
            example:
              due_date: '2026-05-07'
              task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
              title: Follow up with Acme — v2
            schema:
              $ref: '#/components/schemas/V1UpdateTaskRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  completed_at: null
                  created_at: '2026-04-19T09:00:00Z'
                  created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
                  description: Confirm the renewal timeline after the quarterly review.
                  due_date: '2026-04-30'
                  entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                  entity_type: contact
                  id: task_8W3jXRFuLpTQ3nM4PkGvW0
                  task_status:
                    category: todo
                    color: gray
                    id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                    name: To Do
                    position: 0
                  task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
                  title: Follow up with Acme
                  updated_at: '2026-04-19T09:00:00Z'
              schema:
                $ref: '#/components/schemas/V1TaskDetailResponsePayload'
          description: Updated Task.
        '400':
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: Task status not found in this organization
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid ID or request body.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Invalid or missing API key
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: 'Missing required scope: tasks:write'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
        '404':
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Task not found
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Task not found.
      security:
      - bearerAuth: []
      summary: Update a Task
      tags:
      - Tasks
components:
  schemas:
    V1UpdateTaskRequest:
      description: Request body for partially updating a Task. Explicit JSON `null` on `description`, `assignee_id`, `due_date`, or the entity link clears the field; omitting the field leaves it untouched; empty strings are rejected. `task_status_id` and `task_status_name` are mutually exclusive on a single request.
      properties:
        assignee_id:
          description: Opaque `user_` identifier.
          example: user_9T5jXRFuLpTQ3nM4PkGvW2
          oneOf:
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: string
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: 'null'
        description:
          oneOf:
          - type: string
          - type: 'null'
        due_date:
          example: '2026-04-30'
          oneOf:
          - example: '2026-04-30'
            format: date
            type: string
          - example: '2026-04-30'
            type: 'null'
        entity_id:
          oneOf:
          - type: string
          - type: 'null'
        entity_type:
          enum:
          - account
          - contact
          - deal
          - lead
          oneOf:
          - enum:
            - account
            - contact
            - deal
            - lead
            type: string
          - enum:
            - account
            - contact
            - deal
            - lead
            type: 'null'
        task_status_id:
          type: string
        task_status_name:
          type: string
        title:
          type: string
      required: []
      title: V1UpdateTaskRequest
      type: object
    V1TaskPayload:
      description: Task payload (shared by list and detail responses).
      properties:
        assignee_id:
          description: Opaque `user_` identifier.
          example: user_9T5jXRFuLpTQ3nM4PkGvW2
          oneOf:
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: string
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: 'null'
        completed_at:
          oneOf:
          - format: date-time
            type: string
          - type: 'null'
        created_at:
          example: '2026-03-22T14:00:01Z'
          format: date-time
          type: string
        created_by_id:
          description: Opaque `user_` identifier.
          example: user_9T5jXRFuLpTQ3nM4PkGvW2
          oneOf:
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: string
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: 'null'
        description:
          oneOf:
          - type: string
          - type: 'null'
        due_date:
          example: '2026-04-30'
          oneOf:
          - example: '2026-04-30'
            format: date
            type: string
          - example: '2026-04-30'
            type: 'null'
        entity_id:
          oneOf:
          - type: string
          - type: 'null'
        entity_type:
          enum:
          - account
          - contact
          - deal
          - lead
          oneOf:
          - enum:
            - account
            - contact
            - deal
            - lead
            type: string
          - enum:
            - account
            - contact
            - deal
            - lead
            type: 'null'
        id:
          description: Opaque `task_` identifier.
          example: task_8W3jXRFuLpTQ3nM4PkGvW0
          type: string
        task_status:
          $ref: '#/components/schemas/V1TaskStatusPayload'
        task_status_id:
          description: Opaque `taskstatus_` identifier.
          example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
          type: string
        title:
          type: string
        updated_at:
          example: '2026-03-22T14:00:01Z'
          format: date-time
          type: string
      required:
      - assignee_id
      - completed_at
      - created_at
      - created_by_id
      - description
      - due_date
      - entity_id
      - entity_type
      - id
      - task_status
      - task_status_id
      - title
      - updated_at
      title: V1TaskPayload
      type: object
    V1PaginationPayload:
      description: Cursor pagination block for public list responses.
      properties:
        has_more:
          description: Whether another page is available.
          example: false
          type: boolean
        limit:
          description: Requested page size.
          example: 50
          type: integer
        next_cursor:
          description: Opaque cursor to pass as `cursor` for the next page, or null when this is the last page.
          example: null
          type:
          - string
          - 'null'
      required:
      - limit
      - next_cursor
      - has_more
      type: object
    V1CreateTaskRequest:
      description: Request body for creating a Task. `description` is plain text only; sending it clears any rich-text state the UI may have previously stored.
      properties:
        assignee_id:
          description: Opaque `user_` identifier.
          example: user_9T5jXRFuLpTQ3nM4PkGvW2
          oneOf:
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: string
          - description: Opaque `user_` identifier.
            example: user_9T5jXRFuLpTQ3nM4PkGvW2
            type: 'null'
        description:
          oneOf:
          - type: string
          - type: 'null'
        due_date:
          example: '2026-04-30'
          oneOf:
          - example: '2026-04-30'
            format: date
            type: string
          - example: '2026-04-30'
            type: 'null'
        entity_id:
          oneOf:
          - type: string
          - type: 'null'
        entity_type:
          enum:
          - account
          - contact
          - deal
          - lead
          oneOf:
          - enum:
            - account
            - contact
            - deal
            - lead
            type: string
          - enum:
            - account
            - contact
            - deal
            - lead
            type: 'null'
        task_status_id:
          description: Opaque `taskstatus_` identifier.
          example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
          oneOf:
          - description: Opaque `taskstatus_` identifier.
            example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
            type: string
          - description: Opaque `taskstatus_` identifier.
            example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
            type: 'null'
        task_status_name:
          oneOf:
          - type: string
          - type: 'null'
        title:
          type: string
      required:
      - title
      title: V1CreateTaskRequest
      type: object
    V1TaskListPayload:
      description: Paginated list response for Tasks.
      properties:
        data:
          items:
            $ref: '#/components/schemas/V1TaskPayload'
          type: array
        pagination:
          $ref: '#/components/schemas/V1PaginationPayload'
      required:
      - data
      - pagination
      title: V1TaskListPayload
      type: object
    V1ErrorResponse:
      description: Standard error envelope for all public v1 API errors.
      properties:
        error:
          properties:
            code:
              description: Stable machine-readable error code.
              example: not_found
              type: string
            message:
              description: Human-readable error message.
              example: Account not found
              type: string
          required:
          - code
          - message
          type: object
      required:
      - error
      type: object
    V1TaskStatusPayload:
      description: Task status definition payload.
      properties:
        category:
          type: string
        color:
          type: string
        id:
          description: Opaque `taskstatus_` identifier.
          example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
          type: string
        name:
          type: string
        position:
          type: integer
      required:
      - category
      - color
      - id
      - name
      - position
      title: V1TaskStatusPayload
      type: object
    V1TaskDeletePayload:
      description: Envelope returned when a Task is deleted.
      properties:
        deleted:
          const: true
          type: boolean
        id:
          description: Opaque `task_` identifier.
          example: task_8W3jXRFuLpTQ3nM4PkGvW0
          type: string
      required:
      - deleted
      - id
      title: V1TaskDeletePayload
      type: object
    V1TaskDetailResponsePayload:
      description: Single-Task response envelope.
      properties:
        data:
          $ref: '#/components/schemas/V1TaskPayload'
      required:
      - data
      title: V1TaskDetailResponsePayload
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: API key or OAuth access token
      description: Send either a Fixture API key or a Fixture OAuth access token in the Authorization header as a bearer token.
      scheme: bearer
      type: http