OPEN BY
DEFAULT

FlowDesk's task schema, agent actions, and MCP server are a public spec — so any tool or agent can read from and write to FlowDesk. Protocol ownership beats walled gardens. This page is the canonical reference.

01TASK SCHEMA

The shape of a task. Natural language in, this structure out — the same object the API, the app, and agents all speak.

task

{
  "id":        "uuid",
  "title":     "string",
  "priority":  "critical | high | medium | low",
  "assignee":  "string | null",
  "deadline":  "string | null",
  "tags":      "string[]",
  "done":      "boolean",
  "parent_id": "uuid | null",   // sub-steps point to their parent
  "source":    "manual | ai | agent | workflow",  // how it was created
  "created_at":"timestamp"
}

// inline parameters in any title: !priority · #tag · @assignee · ^deadline

02AGENT ACTIONS

Declared in /.well-known/agents.json and callable over REST or MCP. Read endpoints need no auth.

Action	Method · Path	Purpose
`get_pricing`	GET `/api/v1/pricing`	Plans & prices
`get_features`	GET `/api/v1/features`	Capability matrix
`start_trial`	POST `/api/v1/trials`	Provision a trial (human confirms)
`start_checkout`	POST `/api/v1/checkout`	Stripe checkout URL for a human
`list_agents`	GET `/api/v1/agents`	Discover registered agents
`register_agent`	POST `/api/v1/agents/register`	Publish an agent

03MCP SERVER

Streamable-HTTP MCP endpoint. Connect any MCP-capable assistant; the actions above are exposed as tools.

mcp config

{
  "mcpServers": {
    "flowdesk": {
      "type": "http",
      "url": "https://flowdesk-landing-2yz.pages.dev/mcp"
    }
  }
}

04SCOPED AGENT KEYS & CONSTITUTION

Task read/write runs through per-agent keys — scoped, per-key rate-limited, and audited — and every write is checked against a per-workspace, machine-readable constitution.

Action	Method · Path	Auth
`list_tasks`	GET `/api/v1/agent/tasks`	Bearer fdk_… · `tasks:read`
`create_task`	POST `/api/v1/agent/tasks`	Bearer fdk_… · `tasks:write`

workspace constitution

{
  "max_priority":        "high",            // agents can't exceed this
  "forbidden_terms":     ["delete all"],    // blocked in task titles
  "quiet_hours_utc":     { "start": 22, "end": 6 },
  "max_creates_per_day": 200
}

// A violated rule returns 403 { "error", "rule" } and is written to the agent audit log. Declarative workflows (DAG + retry + manual approval gates) compose these same actions.

05PRINCIPLES

Human-in-the-loop by default — agents evaluate, provision, and register autonomously; a human always confirms payment.
Machine-readable everywhere — schema.org, OpenAPI, llms.txt, agents.json on every surface.
Stable & versioned — this is v1; breaking changes ship as v2, never in place.