Note: This file is for API Key (OpenClaw / custom bot) setups only. For the ChatGPT OAuth GPT Builder setup, see /dashtask-gpt-oauth/.

DashTask Agent API — Skills File (API Key Setup)

Overview

DashTask is a collaborative task management and CRM platform. Each organization has its own tasks, projects, CRM leads, contacts, companies, activities, quotes, and configurable dimensions. AI agents interact with DashTask via a single REST endpoint.

Quick Start

1. Get Organization Context (call ONCE per conversation — never repeat in the same session)

curl -s -X POST "$DASHTASK_ENDPOINT" \
  -H "X-API-Key: $DASHTASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_org_context"}'

2. List Tasks

curl -s -X POST "$DASHTASK_ENDPOINT" \
  -H "X-API-Key: $DASHTASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "list_tasks", "filters": {"status": "open", "limit": 20}}'

3. Create a Task

curl -s -X POST "$DASHTASK_ENDPOINT" \
  -H "X-API-Key: $DASHTASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "create_task", "title": "Follow up with client", "urgency": 7}'

4. Create a CRM Lead

curl -s -X POST "$DASHTASK_ENDPOINT" \
  -H "X-API-Key: $DASHTASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "create_lead", "lead_name": "Acme Corp", "lead_status": "new_lead", "priority": 5}'

See the full Actions Reference below for all 60+ available actions.

Authentication

This integration uses an API Key passed in the X-API-Key header. Set it once in your environment:

export DASHTASK_API_KEY="your_key_here"
export DASHTASK_ENDPOINT="https://fgkytboizxksqustdfuc.supabase.co/functions/v1/agent-api"

All requests must include:

POST $DASHTASK_ENDPOINT
Content-Type: application/json
X-API-Key: $DASHTASK_API_KEY

Generate your key in DashTask → Settings → Team → Invite AI Agent. The key is scoped to specific permissions at the time of creation.

Scopes

• tasks — Tasks, projects, assignees, tags, discussions, notifications, team members
• crm — Leads, contacts, companies, activities, quotes, lead discussions
• settings — Dimension management (categories, entities, departments, types, tags, CRM dimensions)

Request Format

All requests are POST with a JSON body. All fields are top-level (no nesting under params):

{
  "action": "<action_name>",
  "title": "My task title",
  "id": "<uuid>",
  "filters": { ... }
}

• action (required): The operation to perform
• All create/update fields go at the top level alongside action
• id: UUID of the record for update/delete operations
• filters: Optional filters for list operations

Response Format

{
  "success": true,
  "data": { ... }
}

On error:

{
  "success": false,
  "error": "Description of what went wrong"
}

---

IMPORTANT: Discovery-First Pattern

Dimensions are dynamic. Organizations can add, rename, and remove dimension options at any time. Before creating or updating tasks/leads, you must discover what values are valid for this organization.

Recommended: get_org_context (call ONCE per conversation session, never again)

Call get_org_context only on your very first message in a conversation. Store the result in your memory for the entire session.

RULE: If you have already called get_org_context at any point in this conversation, DO NOT call it again. Use the cached response you already have. This applies to every subsequent message in the same session.

Decision logic (follow strictly):

1. Has get_org_context been called earlier in this conversation? → Use cached data. Skip the call entirely.
2. Is this the very first message in the conversation? → Call get_org_context once, then cache.
3. Did the API return an "Invalid dimension" error? → Call get_org_context once to refresh, then stop.

NEVER call get_org_context:

• Before every action or tool call
• When the user asks a follow-up question
• When checking task status or listing tasks
• In the same conversation where it was already called

Only call get_org_context again if:

• You receive an "Invalid dimension" or "Invalid entity" error from the API
• It has been more than 24 hours since the last call in a long-running session

The response includes:

• projects — all active projects with IDs
• task_dimensions — entity, category, department, type options
• custom_task_dimensions — custom dimension types and their items
• crm_dimensions — lead_source, industry, lead_quality, lead_action_status options
• lead_stages — pipeline stages
• team_members — IDs, names, emails
• tags — tag IDs and names
• dimension_visibility — which dimensions are visible/hidden
• fetched_at — ISO timestamp for cache expiry tracking

Alternative: Individual Discovery Calls

You can still call individual discovery actions if you only need a specific subset:

If you provide an invalid dimension value, the API returns an error with the list of valid options so you can self-correct.

---

Actions Reference

Discovery Actions

get_org_context

Scope: any (tasks, crm, or settings) — returns data scoped to your permissions Returns all organization context in a single call. Recommended for first call — cache the result.

list_task_dimensions

Scope: tasks Lists the 4 fixed task dimensions (entity, category, department, type) with their current options.

list_custom_task_dimensions

Scope: tasks Lists custom dimension types (max 4 per org) and their items.

list_crm_dimensions

Scope: crm Lists CRM dimension types (lead_source, industry, lead_quality, lead_action_status) with options.

list_lead_stages

Scope: crm Lists custom lead pipeline stages for the organization.

list_dimension_visibility

Scope: settings Returns which dimensions are visible/hidden for the organization.

---

Task Actions

list_tasks

Scope: tasks | Filters: status, project_id, limit

create_task

Scope: tasks

{
  "action": "create_task",
  "title": "Follow up with client",
  "description": "Send proposal draft",
  "status": "open",
  "urgency": 7,
  "entity": "acme_corp",
  "category": "marketing",
  "department": "sales",
  "task_type": "task",
  "project_id": "uuid-or-null",
  "parent_task_id": "uuid-or-null",
  "due_date": "2026-03-01",
  "start_date": "2026-02-15",
  "estimated_cost": 500,
  "sales": 1000,
  "hours": 4,
  "budget_hours": 8
}

Fields:

Field	Type	Required	Description
title	string	Yes	Task title
description	string	No	Task description
status	string	No	open, in-progress, approval, or done (default: open)
urgency	integer	No	1-10 scale, 10 = most urgent (default: 5)
entity	string	No	Must be valid entity name (discover via list_task_dimensions)
category	string	No	Must be valid category name
department	string	No	Must be valid department name
type	string	No	Must be valid type name
project_id	uuid	No	Associate with a project
parent_task_id	uuid	No	Parent task UUID — creates this as a subtask
due_date	string	No	ISO date
start_date	string	No	ISO date
estimated_cost	number	No	Estimated cost
sales	number	No	Sales value
hours	number	No	Hours spent
budget_hours	number	No	Budgeted hours

update_task

Scope: tasks | Requires: id Same fields as create_task (including parent_task_id). Only include fields you want to change.

delete_task

Scope: tasks | Requires: id

list_subtasks

Scope: tasks | Requires: parent_task_id or id (parent task UUID) Returns all subtasks of a given parent task.

{ "action": "list_subtasks", "parent_task_id": "uuid" }

assign_task

Scope: tasks

{ "action": "assign_task", "task_id": "uuid", "team_member_id": "uuid" }

unassign_task

Scope: tasks

{ "action": "unassign_task", "task_id": "uuid", "team_member_id": "uuid" }

list_task_assignees

Scope: tasks | Requires: id (task id)

add_task_tag

Scope: tasks

{ "action": "add_task_tag", "task_id": "uuid", "tag_id": "uuid" }

remove_task_tag

Scope: tasks

add_task_discussion

Scope: tasks

{ "action": "add_task_discussion", "task_id": "uuid", "message": "Progress update: completed phase 1" }

---

Project Actions

list_projects

Scope: tasks

create_project

Scope: tasks

{ "action": "create_project", "name": "Q1 Campaign", "description": "Marketing campaign" }

update_project

Scope: tasks | Requires: id

archive_project

Scope: tasks | Requires: id

---

CRM Lead Actions

list_leads

Scope: crm | Filters: lead_status, deal_status, lead_stage, limit

create_lead

Scope: crm

{
  "action": "create_lead",
  "lead_name": "Acme Corp Deal",
  "lead_status": "new_lead",
  "lead_stage": "new_existing",
  "deal_status": "active",
  "priority": 5,
  "email": "contact@acme.com",
  "phone": "+1234567890",
  "lead_source": "website",
  "probability": 50,
  "annual_deal_value": 50000
}

Fixed enum fields:

Field	Values
lead_status	existing_customer, new_lead, attempted_contact, contacted, unqualified, qualified
lead_stage	new_existing, demo_discovery, proposal_quote, negotiation_asks, closed_lost, closed_won
deal_status	active, won, lost, stale

Dynamic fields (discover via list_crm_dimensions):

• lead_source — e.g., "website", "referral" (org-specific)
• lead_action_status — org-specific action statuses

Field	Type	Description
lead_name	string	Required. Lead/deal name
priority	integer	1-5 scale
probability	integer	0-100 win probability
monthly_deal_value	number	Monthly recurring value
annual_deal_value	number	Annual deal value
one_time_deal_value	number	One-time payment value
lifetime_deal_value	number	Total lifetime value
next_steps	string	Next action description
next_step_date	string	ISO date for next action
company_id	uuid	Link to company
primary_contact_id	uuid	Link to primary contact
assignee_id	uuid	Team member UUID
timezone	string	IANA timezone

update_lead

Scope: crm | Requires: id

delete_lead

Scope: crm | Requires: id

assign_lead / unassign_lead

Scope: crm

{ "action": "assign_lead", "lead_id": "uuid", "team_member_id": "uuid" }

add_lead_party / remove_lead_party

Scope: crm

add_lead_discussion

Scope: crm

{ "action": "add_lead_discussion", "lead_id": "uuid", "message": "Client requested revised timeline" }

---

CRM Company Actions

list_companies / create_company / update_company / delete_company

Scope: crm

{
  "action": "create_company",
  "company_name": "Acme Corp",
  "website": "https://acme.com",
  "industry": "Technology",
  "employee_count": 500,
  "headquarters": "New York, NY"
}

---

CRM Contact Actions

list_contacts / create_contact / update_contact / delete_contact

Scope: crm

{
  "action": "create_contact",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@acme.com",
  "phone": "+1234567890",
  "title": "VP Sales",
  "priority": "high",
  "company_id": "uuid"
}

Field	Values
priority	low, medium, high

---

CRM Activity Actions

list_activities

Scope: crm | Filters: lead_id, contact_id, company_id, type, limit

create_activity

Scope: crm

{
  "action": "create_activity",
  "activity_type": "call",
  "direction": "outbound",
  "subject": "Discovery call",
  "content": "Discussed requirements and timeline",
  "lead_id": "uuid",
  "contact_id": "uuid"
}

Field	Values
type	email, call, text, demo, meeting, note
direction	inbound, outbound

---

CRM Quote Actions

list_quotes / create_quote / update_quote

Scope: crm

{
  "action": "create_quote",
  "lead_id": "uuid",
  "plan": "Enterprise",
  "seats": 50,
  "billing_cycle": "annual",
  "price": 25000,
  "status": "draft"
}

Field	Values
status	draft, sent, accepted, rejected
billing_cycle	monthly, annual, one-time

---

Communication Actions

send_nudge

Scope: tasks Sends a nudge email to a team member about a specific task.

{
  "action": "send_nudge",
  "task_id": "uuid",
  "recipient_email": "john@example.com",
  "recipient_name": "John Doe",
  "sender_name": "Sales Bot",
  "tone": "professional"
}

send_crm_email

Scope: crm Sends an email related to a CRM lead.

{
  "action": "send_crm_email",
  "lead_id": "uuid",
  "recipient_email": "client@acme.com",
  "subject": "Follow-up on our discussion",
  "body": "Hi, just following up..."
}

---

Settings & Dimension Management Actions

list_tags / create_tag

Scope: settings

create_task_dimension_option

Scope: settings Add a new option to entity, category, department, or type.

{
  "action": "create_task_dimension_option",
  "dimension": "entity",
  "name": "new_client",
  "label": "New Client"
}

delete_task_dimension_option

Scope: settings | Requires: id, dimension

create_custom_task_dimension

Scope: settings (max 4 per org)

{
  "action": "create_custom_task_dimension",
  "name": "region",
  "label": "Region"
}

delete_custom_task_dimension

Scope: settings | Requires: id

create_custom_task_dimension_item / delete_custom_task_dimension_item

Scope: settings

create_crm_dimension_option

Scope: settings

{
  "action": "create_crm_dimension_option",
  "dimension_type": "lead_source",
  "name": "linkedin",
  "label": "LinkedIn"
}

update_crm_dimension_option / delete_crm_dimension_option

Scope: settings (locked options cannot be deleted)

---

Team & Notification Actions

list_team_members

Scope: tasks (read-only)

create_notification

Scope: tasks

{
  "action": "create_notification",
  "user_id": "uuid",
  "title": "New task assigned",
  "message": "You've been assigned to 'Follow up with client'",
  "type": "info"
}

---

Restricted Actions (Bot Cannot)

• Transfer admin privileges
• Change member roles
• Manage billing or subscriptions
• Access platform admin operations
• Delete the organization
• Access data outside the authorized organization

---

Error Handling

Invalid dimension value:

{
  "success": false,
  "error": "Invalid entity 'xyz'. Valid values: [\"acme_corp\", \"beta_inc\"]"
}

Missing scope:

{
  "success": false,
  "error": "Missing scope: crm"
}

Missing required field:

{
  "success": false,
  "error": "title is required"
}

Rate Limiting

Be respectful of API usage. Recommended: max 60 requests per minute per key.

Workflow Examples

Full Lead Lifecycle

1. get_org_context — first message only — discover all dimensions, stages, and team members (cache for entire session)
2. create_company — create the company
3. create_contact — create the primary contact
4. create_lead — create the lead linked to company and contact
5. create_activity — log a discovery call
6. update_lead — update stage to demo_discovery
7. create_quote — generate a quote
8. update_lead — update stage to proposal_quote, set probability
9. add_lead_discussion — add internal notes
10. send_crm_email — send follow-up email

Task Management Pipeline

1. get_org_context — first message only — discover all dimensions, projects, and team members (cache for entire session)
2. create_project — create a project
3. create_task — create tasks within the project
4. assign_task — assign team members
5. send_nudge — nudge assignees about overdue tasks
6. update_task — mark as done