Tasks API

The Tasks API provides complete create, read, update, and delete functionality for managing tasks and follow-up actions.

Task Properties

Property	Type	Description
`id`	UUID	Unique task identifier
`title`	string	Task title (required)
`description`	string	Detailed task description
`status`	string	Task status: `pending`, `in_progress`, `completed`, `cancelled`
`priority`	string	Priority level: `low`, `medium`, `high`, `urgent`
`due_date`	string (ISO 8601)	Task due date
`organization_id`	UUID	Related organization
`contact_id`	UUID	Related contact
`deal_id`	UUID	Related deal
`assigned_to`	UUID	User assigned to this task
`completed_at`	string (ISO 8601)	Timestamp when task was completed
`metadata`	object	Additional custom data
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Endpoints

List Tasks

Retrieve a list of tasks with optional filtering and sorting.

GET /api-v1-tasks

Query Parameters

Parameter	Type	Description
`limit`	integer	Records per page (default: 100, max: 1000)
`page`	integer	Page number for offset pagination
`cursor`	string	Cursor for cursor-based pagination
`sort`	string	Sort field and direction (e.g., `due_date:asc`)
`filter[title]`	string	Filter by title (partial match)
`filter[status]`	string	Filter by status
`filter[priority]`	string	Filter by priority
`filter[organization_id]`	UUID	Filter by organization
`filter[contact_id]`	UUID	Filter by contact
`filter[deal_id]`	UUID	Filter by deal
`filter[assigned_to]`	UUID	Filter by assigned user
`filter[due_date]`	string	Filter by due date
`include`	string	Include relations: `organization`, `contact`, `deal`, `assigned_user`

Example Request

curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?filter[status]=pending&sort=due_date:asc&include=contact" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Follow up on demo",
      "description": "Check if they have any questions after yesterday's demo",
      "status": "pending",
      "priority": "high",
      "due_date": "2025-12-15T17:00:00Z",
      "organization_id": null,
      "contact_id": "789e0123-e89b-12d3-a456-426614174002",
      "deal_id": "012e3456-e89b-12d3-a456-426614174003",
      "assigned_to": "345e6789-e89b-12d3-a456-426614174004",
      "completed_at": null,
      "metadata": {
        "created_via": "api"
      },
      "created_at": "2025-12-09T10:00:00Z",
      "updated_at": "2025-12-09T10:00:00Z",
      "contact": {
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "first_name": "John",
        "last_name": "Doe"
      }
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 100,
    "page": 1,
    "per_page": 100,
    "total_pages": 1,
    "has_more": false
  }
}

Get Single Task

Retrieve a specific task by ID.

GET /api-v1-tasks/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Task ID

Example Request

curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Follow up on demo",
    "description": "Check if they have any questions after yesterday's demo",
    "status": "pending",
    "priority": "high",
    "due_date": "2025-12-15T17:00:00Z",
    "organization_id": null,
    "contact_id": "789e0123-e89b-12d3-a456-426614174002",
    "deal_id": "012e3456-e89b-12d3-a456-426614174003",
    "assigned_to": "345e6789-e89b-12d3-a456-426614174004",
    "completed_at": null,
    "metadata": {
      "created_via": "api"
    },
    "created_at": "2025-12-09T10:00:00Z",
    "updated_at": "2025-12-09T10:00:00Z",
    "contact": {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "first_name": "John",
      "last_name": "Doe"
    },
    "deal": {
      "id": "012e3456-e89b-12d3-a456-426614174003",
      "title": "Q4 Enterprise Deal"
    },
    "assigned_user": {
      "id": "345e6789-e89b-12d3-a456-426614174004",
      "full_name": "Alice Smith",
      "email": "alice@example.com"
    }
  }
}

Create Task

Create a new task.

POST /api-v1-tasks

Request Body

Field	Type	Required	Description
`title`	string	Yes	Task title
`description`	string	No	Task description
`status`	string	No	Status (default: `pending`)
`priority`	string	No	Priority (default: `medium`)
`due_date`	string (ISO 8601)	No	Due date
`organization_id`	UUID	No	Related organization
`contact_id`	UUID	No	Related contact
`deal_id`	UUID	No	Related deal
`assigned_to`	UUID	No	User to assign task to
`metadata`	object	No	Custom metadata

Example Request

curl -X POST "https://your-instance.supabase.co/functions/v1/api-v1-tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send contract",
    "description": "Send signed contract to legal team",
    "status": "pending",
    "priority": "high",
    "due_date": "2025-12-20T12:00:00Z",
    "deal_id": "012e3456-e89b-12d3-a456-426614174003"
  }'

Example Response

{
  "data": {
    "id": "234e5678-e89b-12d3-a456-426614174005",
    "title": "Send contract",
    "description": "Send signed contract to legal team",
    "status": "pending",
    "priority": "high",
    "due_date": "2025-12-20T12:00:00Z",
    "organization_id": null,
    "contact_id": null,
    "deal_id": "012e3456-e89b-12d3-a456-426614174003",
    "assigned_to": null,
    "completed_at": null,
    "metadata": {
      "created_via": "api"
    },
    "created_at": "2025-12-09T11:30:00Z",
    "updated_at": "2025-12-09T11:30:00Z",
    "deal": {
      "id": "012e3456-e89b-12d3-a456-426614174003",
      "title": "Q4 Enterprise Deal"
    }
  }
}

Update Task

Update an existing task. Only provided fields will be updated.

PATCH /api-v1-tasks/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Task ID

Request Body

All fields are optional. Only include fields you want to update:

Field	Type	Description
`title`	string	Task title
`description`	string	Task description
`status`	string	Status: `pending`, `in_progress`, `completed`, `cancelled`
`priority`	string	Priority: `low`, `medium`, `high`, `urgent`
`due_date`	string/null	Due date (set to `null` to remove)
`organization_id`	UUID/null	Related organization
`contact_id`	UUID/null	Related contact
`deal_id`	UUID/null	Related deal
`assigned_to`	UUID/null	Assigned user
`metadata`	object	Custom metadata

Example Request

curl -X PATCH "https://your-instance.supabase.co/functions/v1/api-v1-tasks/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "priority": "urgent"
  }'

Example Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Follow up on demo",
    "description": "Check if they have any questions after yesterday's demo",
    "status": "in_progress",
    "priority": "urgent",
    "due_date": "2025-12-15T17:00:00Z",
    "organization_id": null,
    "contact_id": "789e0123-e89b-12d3-a456-426614174002",
    "deal_id": "012e3456-e89b-12d3-a456-426614174003",
    "assigned_to": "345e6789-e89b-12d3-a456-426614174004",
    "completed_at": null,
    "metadata": {
      "created_via": "api"
    },
    "created_at": "2025-12-09T10:00:00Z",
    "updated_at": "2025-12-09T12:00:00Z",
    "contact": {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Mark Task as Complete

Convenience endpoint to mark a task as completed.

PATCH /api-v1-tasks/:id/complete

Path Parameters

Parameter	Type	Description
`id`	UUID	Task ID

Example Request

curl -X PATCH "https://your-instance.supabase.co/functions/v1/api-v1-tasks/123e4567-e89b-12d3-a456-426614174000/complete" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Follow up on demo",
    "status": "completed",
    "completed_at": "2025-12-09T13:00:00Z",
    "updated_at": "2025-12-09T13:00:00Z"
  }
}

Delete Task

Soft delete a task. The task is marked as deleted but not permanently removed.

DELETE /api-v1-tasks/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Task ID

Example Request

curl -X DELETE "https://your-instance.supabase.co/functions/v1/api-v1-tasks/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "deleted": true
  }
}

Validation Rules

title is required and must not be empty
status must be one of: pending, in_progress, completed, cancelled
priority must be one of: low, medium, high, urgent
When status is set to completed, completed_at is automatically set to current timestamp
When status is changed from completed to another status, completed_at is cleared
All foreign key references (organization_id, contact_id, deal_id) are validated

Filter Operators

Tasks support advanced filtering with these operators:

eq - Equal to (default)
ne - Not equal to
gt - Greater than
gte - Greater than or equal to
lt - Less than
lte - Less than or equal to
like - Text search (case-insensitive)
in - In array (comma-separated values)

Examples

# Tasks due this week
curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?filter[due_date][gte]=2025-12-09T00:00:00Z&filter[due_date][lt]=2025-12-16T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

# High priority or urgent tasks
curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?filter[priority][in]=high,urgent" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by title
curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?filter[title][like]=contract" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting

Sort tasks by these fields:

title - Task title
due_date - Due date
created_at - Creation date
updated_at - Last update date
priority - Priority level
status - Status

Add :asc or :desc to specify direction (default is desc):

# Sort by due date, earliest first
curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?sort=due_date:asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by priority (descending) then due date (ascending)
curl "https://your-instance.supabase.co/functions/v1/api-v1-tasks?sort=priority:desc,due_date:asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

400 Bad Request - Missing Title

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}

400 Bad Request - Invalid Status

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid status. Must be one of: pending, in_progress, completed, cancelled",
    "details": [
      {
        "field": "status",
        "message": "Must be one of: pending, in_progress, completed, cancelled"
      }
    ]
  }
}

400 Bad Request - No Fields to Update

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "No fields to update"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found"
  }
}