JobMojito Tasks API

openapi: 3.2.0
info:
  title: JobMojito Tasks API
  version: 1.0.0
  description: Public API for JobMojito, served by Supabase Edge Functions. Authenticate with a Supabase JWT access token via the Authorization header.
servers:
- url: https://cool.jobmojito.com/functions/v1
  description: Production
tags:
- name: Tasks
  description: Follow-up tasks for the hiring team, about a candidate, an application or a position.
paths:
  /merchant-task-list:
    get:
      tags:
      - Tasks
      summary: List tasks
      description: 'Tasks of the company (the tasks feature): to-dos of recruiters and hiring managers about a candidate, an application or a position. By default your own open tasks. candidate_id lists the tasks about one candidate, position_id the tasks about one position, assignee_profile_id the tasks of one user (owners only); when one of them is given, scope is ignored. Filters combine. Position access applies: tasks about candidates or positions you may not see are never listed, and hiring managers see only tasks assigned to them. counts are your own open tasks. Read only.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          format: uuid
          description: Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
          example: 28106cba-1c27-4e53-b149-32113e5e8e31
        required: false
        name: merchant_id
        in: query
      - schema:
          type: string
          enum:
          - mine
          - created
          - all
          default: mine
          description: mine (assigned to you, default), created (created by you) or all (every task of the company; owners only). Ignored with candidate_id, position_id or assignee_profile_id.
        required: false
        name: scope
        in: query
      - schema:
          type: string
          format: uuid
          description: Only tasks about this candidate (profile_interview.id), including those about one of their applications.
        required: false
        name: candidate_id
        in: query
      - schema:
          type: string
          format: uuid
          description: Only tasks about this position (position_def_set.id) or interview (interview_def_set.id) itself.
        required: false
        name: position_id
        in: query
      - schema:
          type: string
          format: uuid
          description: 'Only tasks assigned to this user (profile.id). Without candidate_id and position_id this lists a team member''s tasks: owners only.'
        required: false
        name: assignee_profile_id
        in: query
      - schema:
          type: string
          enum:
          - open
          - done
          - cancelled
          - all
          default: open
          description: open (default), done, cancelled or all.
        required: false
        name: status
        in: query
      - schema:
          type: string
          enum:
          - overdue
          - today
          - upcoming
          - none
          description: Only open tasks overdue, due today (company time zone), upcoming, or without a due date (none).
        required: false
        name: due
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
          description: Tasks per page (1 to 500, default 50).
          example: 50
        required: false
        name: limit
        in: query
      - schema:
          type: integer
          nullable: true
          minimum: 0
          default: 0
          description: Number of records to skip from the start of the result set.
          example: 0
        required: false
        name: offset
        in: query
      responses:
        '200':
          description: One page of tasks, your task counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsTaskList'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, another company, the tasks feature is off, or scope all / assignee_profile_id alone without being an owner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: list_tasks
  /merchant-task-save:
    post:
      tags:
      - Tasks
      summary: Create or change a task
      description: 'Creates a task (no task_id: title, assignee_profile_id and one of candidate_id, application_id, position_id), or changes one: title, notes, assignee, due date, and status (open, done, cancelled; cancelled is final). Fields left out keep their value. Owners change any task; recruiters the tasks they created or are assigned; hiring managers are read only here. E-mail: giving the task to someone other than you (a new task, or a new assignee) sends that person one "task assigned" e-mail with the title, the start of the notes, the due date, the candidate or position and your name. Assigning yourself, editing and status changes send nothing. Needs the tasks feature; position access applies (a candidate or position you may not see answers 404).'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtsTaskSaveRequest'
      responses:
        '200':
          description: The task after the call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsTaskSaveResult'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, a hiring manager (read only), not the creator, assignee or an owner of this task, another company, or the tasks feature is off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such task (or it is cancelled), or its candidate, application or position is not visible to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: save_task
components:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total matching records across all pages.
          example: 137
        limit:
          type: integer
          description: Page size used for this response.
          example: 50
        offset:
          type: integer
          description: Offset used for this response.
          example: 0
        has_more:
          type: boolean
          description: True when more records exist beyond this page (offset + returned < total).
          example: true
      required:
      - total
      - limit
      - offset
      - has_more
    AtsTaskSaveResult:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
          description: The task (merchant_task.id).
        created:
          type: boolean
          description: true when this call created the task.
        status:
          type: string
          enum:
          - open
          - done
          - cancelled
          description: The task status after the call.
        assignee_notified:
          type: boolean
          description: 'true when the assignee was e-mailed "task assigned": a new task, or a new assignee, given to someone other than you.'
      required:
      - task_id
      - created
      - status
      - assignee_notified
    AtsTaskList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AtsTask'
          description: 'Tasks of this page: open ones overdue first, then due today, upcoming, without a due date; then done and cancelled, newest first.'
        pagination:
          $ref: '#/components/schemas/Pagination'
        counts:
          $ref: '#/components/schemas/AtsTaskCounts'
        truncated:
          type: boolean
          description: 'true when more than 500 tasks matched the database query: only the first 500 can be paged and counted. Narrow the filters.'
      required:
      - data
      - pagination
      - counts
      - truncated
    Error:
      type: object
      properties:
        error:
          type: string
          example: Field is required.
        name:
          type: string
          example: interview_result_id
      required:
      - error
    AtsTask:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Task id (merchant_task.id).
        title:
          type: string
          description: Title, 1 to 200 characters.
        notes:
          type: string
          description: Notes, at most 4000 characters. Left out when empty.
        status:
          type: string
          enum:
          - open
          - done
          - cancelled
          description: open, done or cancelled (cancelled is final).
        due_at:
          type: string
          description: Due date and time (ISO 8601). Left out when the task has no due date.
        due_state:
          type: string
          enum:
          - overdue
          - today
          - upcoming
          - none
          description: overdue (the due time has passed), today (due today in the company time zone), upcoming, or none (no due date, or not open).
        assignee_profile_id:
          type: string
          format: uuid
          description: Assignee (profile.id of a company user).
        assignee_name:
          type: string
          description: Assignee's name, or e-mail when the name is empty.
        created_by:
          type: string
          format: uuid
          description: Who created the task (profile.id).
        created_by_name:
          type: string
          description: Creator's name, or e-mail when the name is empty.
        created_at:
          type: string
          description: When the task was created (ISO 8601).
        completed_at:
          type: string
          description: When the task was marked done (ISO 8601).
        candidate_id:
          type: string
          format: uuid
          description: Candidate the task is about (profile_interview.id).
        candidate_name:
          type: string
          description: Candidate's name.
        application_id:
          type: string
          format: uuid
          description: Application the task is about (position_result.id).
        definition_id:
          type: string
          format: uuid
          description: Position (position_def_set.id) or interview (interview_def_set.id) the task is about; see definition_kind.
        definition_kind:
          type: string
          enum:
          - position
          - interview
          description: 'What definition_id is: position or interview.'
        definition_name:
          type: string
          description: Name of the position or interview.
        can_edit:
          type: boolean
          description: You may change title, notes, assignee and due date (creator, assignee or owner).
        can_complete:
          type: boolean
          description: You may change the status.
        admin_path:
          type: string
          description: Path of the task subject in the JobMojito admin (append to the admin host).
      required:
      - id
      - title
      - status
      - due_state
      - assignee_profile_id
      - created_at
      - can_edit
      - can_complete
    AtsTaskSaveRequest:
      type: object
      properties:
        merchant_id:
          type: string
          format: uuid
          description: Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.
        task_id:
          type: string
          format: uuid
          description: The task to change (merchant_task.id, from list_tasks). Leave out to create a task.
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Title, 1 to 200 characters. Required to create.
        assignee_profile_id:
          type: string
          format: uuid
          description: Who does it (profile.id of an active user of the company who can see the candidate or position). Required to create.
        due_at:
          type: string
          nullable: true
          pattern: ^$|^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$
          description: Due date and time (ISO 8601 with offset). An empty string (or null) removes it; left out keeps it.
        notes:
          type: string
          nullable: true
          maxLength: 4000
          description: Notes, at most 4000 characters. An empty string (or null) removes them; left out keeps them.
        candidate_id:
          type: string
          format: uuid
          description: 'Create only: the candidate the task is about (profile_interview.id).'
        application_id:
          type: string
          format: uuid
          description: 'Create only: one application of the candidate (position_result.id); the candidate is taken from it.'
        position_id:
          type: string
          format: uuid
          description: 'Create only: the position (position_def_set.id) or interview (interview_def_set.id) the task is about.'
        status:
          type: string
          enum:
          - open
          - done
          - cancelled
          description: 'open, done or cancelled. Cancelled is final: a cancelled task cannot be changed or reopened. Applied after the other changes.'
    AtsTaskCounts:
      type: object
      properties:
        open:
          type: integer
          description: Your open tasks (assigned to you).
        overdue:
          type: integer
          description: Of those, overdue.
        today:
          type: integer
          description: Of those, due today (company time zone).
      required:
      - open
      - overdue
      - today
      description: Your own open tasks (as the To do menu shows them), whatever the filters.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT — `Authorization: Bearer <token>`.'