ZenZap Tasks API

openapi: 3.2.0
info:
  title: Zenzap External Integration Tasks API
  description: API for external applications to integrate with Zenzap.
  version: 2.0.0
  contact:
    name: Zenzap Support
    url: https://zenzap.co/support
servers:
- url: https://api.zenzap.co
  description: Production server
security:
- bearerAuth: []
  hmacSignature: []
- oauth2ClientCredentials: []
tags:
- name: Tasks
  description: Operations for managing tasks
paths:
  /v2/tasks:
    get:
      summary: List tasks
      description: 'List tasks visible to your bot.


        Optional filters:

        - `topicId`: only tasks from a specific topic

        - `status`: `Open` or `Done`

        - `assignee`: profile ID of assignee (pass empty string to filter unassigned tasks)


        Pagination:

        - `limit`: default `50`, max `100`

        - `cursor`: opaque cursor from the previous response (`nextCursor`)'
      operationId: listTasks
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - task:read
      tags:
      - Tasks
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      - name: topicId
        in: query
        required: false
        description: Filter tasks by topic ID
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: status
        in: query
        required: false
        description: Filter by task status
        schema:
          type: string
          enum:
          - Open
          - Done
        example: Open
      - name: assignee
        in: query
        required: false
        description: Filter by assignee profile ID (empty value filters unassigned tasks)
        schema:
          type: string
        example: 550e8400-e29b-41d4-a716-446655440001
      - name: limit
        in: query
        required: false
        description: Maximum tasks to return (default 50, max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from a previous `nextCursor` value.
        schema:
          type: string
      responses:
        '200':
          description: Tasks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create a task
      description: 'Create a task in a topic. Tasks can be assigned to specific users and have due dates.


        Limits:

        - task title is limited to 256 characters

        - task description is limited to 10000 characters

        - you can only assign tasks to members that are already in your topic

        - task due date must be a valid Unix timestamp in milliseconds (e.g., 1699564800000)

        - task externalId is limited to 100 characters'
      operationId: createTask
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - task:write
      tags:
      - Tasks
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
            examples:
              basic:
                summary: Basic task
                value:
                  topicId: 550e8400-e29b-41d4-a716-446655440000
                  title: Review documentation
              withAssignee:
                summary: Assigned task with due date
                value:
                  topicId: 550e8400-e29b-41d4-a716-446655440000
                  title: Complete quarterly review
                  description: Review all metrics and prepare report
                  assignee: 550e8400-e29b-41d4-a716-446655440001
                  dueDate: 1699564800000
                  externalId: jira-PROJ-123
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreateResponse'
              example:
                id: 880e8400-e29b-41d4-a716-446655440003
                topicId: 550e8400-e29b-41d4-a716-446655440000
                title: Review documentation
                createdAt: 1699564800000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/tasks/{taskId}:
    get:
      summary: Get task details
      description: Get a single task by ID.
      operationId: getTask
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - task:read
      tags:
      - Tasks
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      - name: taskId
        in: path
        required: true
        description: The task ID
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440003
      responses:
        '200':
          description: Task retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a task
      description: 'Update task fields. This endpoint supports partial updates.


        Updatable fields:

        - `name` (alias of `title`)

        - `description`

        - `assignee`

        - `dueDate`

        - `status` (`Open` or `Done`)


        Notes:

        - Provide either `name` or `title` (not both)

        - Setting `assignee` to an empty string unassigns the task

        - Setting `dueDate` to `0` clears the due date

        - When status is set to `Done`, the task is marked as closed

        - When `status` is provided, `topicId` is required

        - Every successful update creates a task system message in the topic'
      operationId: patchTask
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - task:write
      tags:
      - Tasks
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      - name: taskId
        in: path
        required: true
        description: The task ID to update
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440003
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskPatchRequest'
            examples:
              completeTask:
                summary: Mark task as done
                value:
                  topicId: 550e8400-e29b-41d4-a716-446655440000
                  status: Done
              renameAndReassign:
                summary: Rename and reassign task
                value:
                  name: Review webhook integration docs
                  assignee: 550e8400-e29b-41d4-a716-446655440001
                  description: Update docs with long polling + multipart examples
              updateDueDate:
                summary: Set due date
                value:
                  dueDate: 1699564800000
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPatchResponse'
              example:
                id: 880e8400-e29b-41d4-a716-446655440003
                updatedAt: 1699564800000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a task
      description: Delete a task by ID.
      operationId: deleteTask
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - task:write
      tags:
      - Tasks
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      - name: taskId
        in: path
        required: true
        description: The task ID to delete
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440003
      responses:
        '204':
          description: Task deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    TaskListResponse:
      type: object
      properties:
        tasks:
          type: array
          description: Tasks matching the provided filters
          items:
            $ref: '#/components/schemas/TaskResponse'
        nextCursor:
          type: string
          description: Cursor for the next page. Omitted when there are no more results.
        hasMore:
          type: boolean
          description: Whether there are more tasks available.
    TaskCreateResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The created task ID
        topicId:
          type: string
          format: uuid
          description: The topic ID where the task was created
        title:
          type: string
          description: The task title
        createdAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
    TaskPatchRequest:
      type: object
      description: Partial task update payload. At least one field must be provided.
      properties:
        topicId:
          type: string
          format: uuid
          description: Required when `status` is provided.
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          maxLength: 256
          description: Task title (alias of `title`). Provide either `name` or `title`.
          example: Review webhook integration docs
        title:
          type: string
          maxLength: 256
          description: Task title. Provide either `title` or `name`.
          example: Review webhook integration docs
        description:
          type: string
          maxLength: 10000
          description: Task description
          example: Update docs with long polling + multipart examples
        assignee:
          type: string
          description: Assignee profile ID. Empty string removes assignee.
          example: 550e8400-e29b-41d4-a716-446655440001
        dueDate:
          type: integer
          format: int64
          description: Due date as Unix timestamp in milliseconds. Set to `0` to clear.
          example: 1699564800000
        status:
          type: string
          description: Task status
          enum:
          - Open
          - Done
          example: Done
    TaskResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Task ID
          example: 880e8400-e29b-41d4-a716-446655440003
        topicId:
          type: string
          format: uuid
          description: Topic ID the task belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
        title:
          type: string
          description: Task title
          example: Review documentation
        description:
          type: string
          description: Task description
          example: Review and update all API documentation
        status:
          type: string
          enum:
          - Open
          - Done
          description: Task status
          example: Open
        assignee:
          type: string
          description: Assignee profile ID (empty if unassigned)
          example: 550e8400-e29b-41d4-a716-446655440001
        dueDate:
          type: integer
          format: int64
          description: Due date as Unix timestamp in milliseconds (0 if not set)
          example: 1699564800000
        isDueDateTimeSelected:
          type: boolean
          description: Whether due date includes time
          example: false
        index:
          type: number
          format: double
          description: Internal task ordering index
          example: 1000000
        createdAt:
          type: integer
          format: int64
          description: Task creation timestamp (ms)
          example: 1699564800000
        updatedAt:
          type: integer
          format: int64
          description: Task last update timestamp (ms)
          example: 1699564801000
    TaskPatchResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Updated task ID
        updatedAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the task was updated
    TaskCreateRequest:
      type: object
      required:
      - topicId
      - title
      properties:
        topicId:
          type: string
          format: uuid
          description: The ID of the topic where the task should be created
          example: 550e8400-e29b-41d4-a716-446655440000
        title:
          type: string
          maxLength: 256
          description: The task title
          example: Review documentation
        description:
          type: string
          maxLength: 10000
          description: Optional task description
          example: Review and update all API documentation
        assignee:
          type: string
          format: uuid
          description: Optional user ID to assign the task to
          example: 550e8400-e29b-41d4-a716-446655440001
        dueDate:
          type: integer
          format: int64
          description: Optional due date as Unix timestamp in milliseconds
          example: 1699564800000
        externalId:
          type: string
          maxLength: 100
          description: Optional external identifier for tracking purposes
          example: jira-PROJ-123
  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        text/plain:
          schema:
            type: string
          example: text is required
    Unauthorized:
      description: Unauthorized - invalid or missing API token
      content:
        text/plain:
          schema:
            type: string
          example: unauthorized
    InternalServerError:
      description: Internal server error
      content:
        text/plain:
          schema:
            type: string
          example: internal server error
    NotFound:
      description: Resource not found
      content:
        text/plain:
          schema:
            type: string
          example: Topic not found
  parameters:
    XSignature:
      name: X-Signature
      in: header
      required: false
      description: "HMAC signature of the request for authentication and replay protection.\n\n**Required only when authenticating with a static API key.** If you are using an OAuth access token (issued by `POST /oauth/token`), omit this header — the JWT carries all the authentication and integrity guarantees.\n\n**Replay Protection:** The signature includes a timestamp to prevent replay attacks.\nRequests with timestamps older than 5 minutes are rejected.\n\nThe signature payload differs by HTTP method:\n- **POST/PUT/PATCH/DELETE**: HMAC-SHA256 of `{timestamp}.{body}`\n- **GET**: HMAC-SHA256 of `{timestamp}.{uri}`\n\nThe signature is calculated as:\n1. Get the current Unix timestamp in milliseconds\n2. Determine the payload:\n   - For POST/PUT/PATCH/DELETE: Use `{timestamp}.{body}` where body is the request body\n   - For GET: Use `{timestamp}.{uri}` where uri is the full request URI (e.g., `/v2/members?limit=10`)\n3. Calculate HMAC-SHA256 of the combined payload using your API secret\n4. Hex-encode the output\n5. Include the timestamp in the `X-Timestamp` header\n\nExample for GET request to `/v2/members?limit=10`:\n```\ntimestamp = 1699564800000\npayload = \"1699564800000./v2/members?limit=10\"\nsignature = HMAC-SHA256(secret, payload)\nX-Signature: hex(signature)\nX-Timestamp: 1699564800000\n```\n\nExample for POST request with body `{\"topicId\":\"123\",\"text\":\"Hello\"}`:\n```\ntimestamp = 1699564800000\npayload = '1699564800000.{\"topicId\":\"123\",\"text\":\"Hello\"}'\nsignature = HMAC-SHA256(secret, payload)\nX-Signature: hex(signature)\nX-Timestamp: 1699564800000\n```\n\nFor `multipart/form-data` requests, sign the exact raw request body bytes\n(including boundaries and file bytes) as transmitted.\n"
      schema:
        type: string
        pattern: ^[a-f0-9]{64}$
        example: a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6
    XTimestamp:
      name: X-Timestamp
      in: header
      required: false
      description: 'Unix timestamp in milliseconds when the request was created.

        Used for replay protection — requests older than 5 minutes are rejected.


        **Required only when authenticating with a static API key.** Omit when using an OAuth access token.

        '
      schema:
        type: integer
        format: int64
        example: 1699564800000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token for the request. Two flavors:


        - **Static API key** — pass your API key (the value returned as `apiKey` when the bot was created). Must be paired with `X-Signature` + `X-Timestamp` (the `hmacSignature` scheme).

        - **OAuth access token** — pass the JWT returned by `POST /oauth/token`. No signature headers are required.

        '
    hmacSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: 'HMAC-SHA256 signature for request verification. Required **only** when authenticating with a static API key. Omit when using an OAuth access token.

        '
    oauth2ClientCredentials:
      type: oauth2
      description: 'OAuth 2.0 `client_credentials` grant for API-key bots. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) to mint short-lived access tokens. See [Authentication](/api-reference/authentication) for details.


        Access tokens are bearer JWTs and expire after 1 hour. There is no refresh token — re-mint with the client credentials when the token expires.

        '
      flows:
        clientCredentials:
          tokenUrl: https://api.zenzap.co/oauth/token
          scopes:
            channel:list: List topics the bot belongs to
            channel:read: Read topic metadata
            channel:write: Create/update topics and manage members
            message:read: Read messages
            message:send: Send messages
            message:write: Edit / delete / mark-delivered / mark-read messages
            reaction:write: Add and remove reactions on messages
            task:read: Read tasks
            task:write: Create / update / delete tasks
            poll:write: Create polls and cast / retract votes
            member:read: List organization members
            updates:read: Long-poll for outbound events