diff --git a/SUMMARY.md b/SUMMARY.md index 47acecd..eb9f4b1 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -92,7 +92,7 @@ * [Developer Overview](apis-living-system-development/developers/README.md) * [Authentication](apis-living-system-development/developers/authentication.md) * [Personal Tokens](apis-living-system-development/developers/personal-tokens.md) -* [REST API v1 Reference](apis-living-system-development/comprehensive-api-guide/README.md) +* [REST API v1 Reference (Legacy)](apis-living-system-development/comprehensive-api-guide/README.md) * [Overview](apis-living-system-development/developers/api.md) * [Workspaces](apis-living-system-development/comprehensive-api-guide/workspaces/README.md) * [Get Workspaces](apis-living-system-development/comprehensive-api-guide/workspaces/get-workspaces.md) diff --git a/apis-living-system-development/developer-home.md b/apis-living-system-development/developer-home.md index 9fa5f51..79ca8dd 100644 --- a/apis-living-system-development/developer-home.md +++ b/apis-living-system-development/developer-home.md @@ -78,6 +78,59 @@ You need a **Personal Access Token** to authenticate with every Taskade develope Treat your API token like a password. Never commit it to version control or share it publicly. {% endhint %} +## Connect your AI agent (MCP) + +Point Cursor, Claude, Windsurf, or any MCP client at the hosted server with your token. This gives the agent 48 tools (44 Phase A Public API v2 ops + 4 MCP-native: `inspect_space`, `write_file`, `read_project`, `list_automations`) that the v1 stdio wrapper does not expose. Gated on Starter+ plans (`mcp.access`). + +{% tabs %} +{% tab title="Cursor / Windsurf / VS Code" %} +```json +{ + "mcpServers": { + "taskade": { + "type": "http", + "url": "https://www.taskade.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` +{% endtab %} + +{% tab title="Claude Desktop / Claude Code" %} +```json +{ + "mcpServers": { + "taskade": { + "type": "http", + "url": "https://www.taskade.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` +{% endtab %} + +{% tab title="Local stdio fallback" %} +For a local stdio server that wraps the v1 API (no app-file editing), see [Workspace MCP](workspace-mcp.md) (`@taskade/mcp-server` on npm). +{% endtab %} +{% endtabs %} + +## Make your first call + +```bash +# v2 (action-based — every call is a POST) +curl -X POST https://www.taskade.com/api/v2/listSpaces \ + -H "Authorization: Bearer your_api_key_placeholder" \ + -H "Content-Type: application/json" -d '{}' +``` + +Explore the full surface in the [Action API v2 interactive docs](https://www.taskade.com/api/documentation/v2) or the [REST API v1 interactive docs (Legacy)](https://www.taskade.com/api/documentation/v1). + ## Developer Resources | Resource | Description | diff --git a/apis-living-system-development/sdk-quickstart.md b/apis-living-system-development/sdk-quickstart.md index bf5ae28..af66ee1 100644 --- a/apis-living-system-development/sdk-quickstart.md +++ b/apis-living-system-development/sdk-quickstart.md @@ -7,12 +7,21 @@ description: >- # TypeScript SDK (Preview) {% hint style="warning" %} -**The `@taskade/sdk` package is in preview and not yet published to the public npm registry.** Until it ships, call the API directly over HTTP — every Taskade endpoint is a plain HTTPS request and works from any language or runtime. This page shows both. +**Prefer HTTP or MCP.** Every Taskade endpoint is a plain HTTPS request and works from any language or runtime. The hosted MCP server at `https://www.taskade.com/mcp` gives AI agents (Cursor, Claude, Codex) 48 tools including app-file editing (`inspect_space`, `write_file`). The `@taskade/sdk` package below is a generated client that is **not yet on public npm** — use HTTP or MCP until it ships. {% endhint %} -## Call the API today (no SDK required) +## Call the API today (any language) -Authenticate with a [personal access token](developers/authentication.md) and hit either API directly. +Authenticate with a [personal access token](developers/authentication.md) and hit either API directly. The fastest path is a single curl call: + +```bash +curl https://www.taskade.com/api/v2/listSpaces \ + -H "Authorization: Bearer tskdp_YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +Get a token at [taskade.com/settings/api](https://www.taskade.com/settings/api). The same token works for both APIs below. {% tabs %} {% tab title="REST API v1" %} @@ -113,7 +122,29 @@ result = requests.post( {% endtab %} {% endtabs %} -## What the SDK will look like +## Connect via MCP (AI agents) + +For Cursor, Claude, Windsurf, VS Code, or any MCP client, point at the hosted server with your personal token. This gives the agent 48 tools (44 Phase A Public API v2 ops + 4 MCP-native: `inspect_space`, `write_file`, `read_project`, and `list_automations`) that the v1 stdio wrapper does not expose. + +```json +{ + "mcpServers": { + "taskade": { + "type": "http", + "url": "https://www.taskade.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Get your token at [taskade.com/settings/api](https://www.taskade.com/settings/api). The hosted MCP is gated on Starter+ plans (`mcp.access` feature switch). For a local stdio wrapper that wraps the v1 API, see [Workspace MCP](workspace-mcp.md) (`@taskade/mcp-server` on npm). + +## Generated TypeScript client (preview, unmaintained) + +> The section below is a footnote for anyone who wants generated types. The SDK is not on public npm. For live integrations, use HTTP or MCP above. `@taskade/sdk` is a **generated client** for the [Action API v2](api-v2-reference.md). When it's published you'll construct an `HttpClient` (which carries your token) and a `TaskadePublicApi` instance whose methods map 1:1 to the v2 operations: @@ -140,7 +171,8 @@ Method names match the v2 operations exactly — `listSpaces`, `createProject`, | Resource | Description | | --- | --- | -| [REST API v1 Reference](comprehensive-api-guide/README.md) | Complete RESTful endpoint docs (full task CRUD) | +| [Hosted Taskade MCP (Beta)](genesis-app-mcp.md) | Orchestrate your workspace from any MCP client via `https://www.taskade.com/mcp` — 48 tools incl. app-file editing | | [Action API v2 Reference](api-v2-reference.md) | The action-based API the SDK wraps | +| [REST API v1 Reference (Legacy)](comprehensive-api-guide/README.md) | Complete RESTful endpoint docs (full task CRUD) | | [Authentication](developers/authentication.md) | Personal access tokens and OAuth 2.0 | -| [Workspace MCP](workspace-mcp.md) | Connect AI tools to your workspace | +| [Workspace MCP](workspace-mcp.md) | Local stdio wrapper (`@taskade/mcp-server`, v1 surface) | diff --git a/llms.txt b/llms.txt index b77e93d..e377497 100644 --- a/llms.txt +++ b/llms.txt @@ -85,28 +85,68 @@ Developers can build on the REST API v1, the action-based Public API v2, a TypeS ## Developers +Build apps, deploy AI agents, and automate workflows from one prompt. + +### Developer surface (in order of preference) + +1. Hosted MCP server: https://www.taskade.com/mcp + - Auth: Bearer `` from https://www.taskade.com/settings/api + - 48 tools: 44 Phase A Public API v2 ops + 4 MCP-native (`inspect_space`, `write_file`, `read_project`, `list_automations`) + - Gated on Starter+ plans (mcp.access feature switch) + - Docs: https://docs.taskade.com/developers/workspace-mcp/genesis-app-mcp + +2. OpenAPI v2 (interactive): https://www.taskade.com/api/documentation/v2 + - Auth: same Bearer token + - Full REST surface: projects, tasks, agents, bundles, media, webhooks + - Reference: https://docs.taskade.com/developers/api-v2-reference + +3. OpenAPI v1 (legacy, full task CRUD): https://www.taskade.com/api/documentation/v1 + - Reference: https://docs.taskade.com/developers/comprehensive-api-guide + +4. Stdio MCP fallback (local stdio): https://github.com/taskade/mcp + - npm: `@taskade/mcp-server` + - v1 surface only (no app file editing) + - Docs: https://docs.taskade.com/developers/workspace-mcp + +5. TypeScript SDK (preview, unmaintained): https://github.com/taskade/sdk + - Generated from v2 OpenAPI; not on public npm + - Docs: https://docs.taskade.com/developers/sdk-quickstart + +### Quick start + +```bash +curl https://www.taskade.com/api/v2/listSpaces \ + -H "Authorization: Bearer tskdp_YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +Get a token: https://www.taskade.com/settings/api + +### Reference + - [Developer Platform](https://docs.taskade.com/developers/developer-home): Everything you need to build on Taskade — REST API v1, Action API v2, MCP servers, OAuth 2.0, and webhooks. - [Developer Overview](https://docs.taskade.com/developers/developer-home/developers): The developer surface at a glance — APIs, tokens, MCP, webhooks, and Genesis app generation. - [Authentication](https://docs.taskade.com/developers/authentication): Personal Access Tokens for scripts and MCP; OAuth 2.0 with PKCE for third-party apps. - [Personal Tokens](https://docs.taskade.com/developers/authentication/personal-tokens): Generate a Personal Access Token and authenticate with the Authorization Bearer header. -- [REST API v1 Reference](https://docs.taskade.com/developers/comprehensive-api-guide): Manage workspaces, projects, tasks, agents, folders, and media with full CRUD and code examples. - [Action API v2 Reference](https://docs.taskade.com/developers/api-v2-reference): The action-based (RPC-over-HTTP) Public API v2 — every call is a POST to a named operation. +- [Action API v2 live OpenAPI spec](https://www.taskade.com/api/documentation/v2): Interactive reference (JSON: https://www.taskade.com/api/documentation/v2/json). +- [REST API v1 Reference (Legacy)](https://docs.taskade.com/developers/comprehensive-api-guide): Manage workspaces, projects, tasks, agents, folders, and media with full CRUD and code examples. +- [REST API v1 live OpenAPI spec](https://www.taskade.com/api/documentation/v1): Interactive reference (JSON: https://www.taskade.com/api/documentation/v1/json). - [TypeScript SDK (Preview)](https://docs.taskade.com/developers/sdk-quickstart): Call the API today with plain HTTP, and what the generated client will look like. - [SDK Cookbook](https://docs.taskade.com/developers/sdk-quickstart/sdk-cookbook): Integration patterns — agents, automations, projects, bundles, error handling, pagination, testing. - [Webhooks](https://docs.taskade.com/developers/webhooks): Inbound webhooks to trigger automations and signed outbound webhooks over the Public API v2. - [Bundles & App Kits](https://docs.taskade.com/developers/bundles): Export and import complete Genesis apps and workspaces as portable bundles via the Action API v2. - [Long-Term Memory](https://docs.taskade.com/developers/long-term-memory): Memory that lives as real Projects — editable, browsable, and API-addressable. - [Autonomous Agents](https://docs.taskade.com/developers/autonomous-agents): Agents that run without per-request prompting — automations, orchestration, and Autopilot patterns. -- [REST API v1 live OpenAPI spec](https://www.taskade.com/api/documentation/v1): Interactive reference (JSON: https://www.taskade.com/api/documentation/v1/json). -- [Action API v2 live OpenAPI spec](https://www.taskade.com/api/documentation/v2): Interactive reference (JSON: https://www.taskade.com/api/documentation/v2/json). ## MCP - [Which Taskade MCP do I want?](https://docs.taskade.com/developers/mcp-overview): Three MCP surfaces, one decision — Workspace MCP (@taskade/mcp-server) for task writes, the hosted Taskade MCP for orchestration, or MCP Connectors for agent tool access. +- [Hosted Taskade MCP (Beta)](https://docs.taskade.com/developers/workspace-mcp/genesis-app-mcp): Orchestrate your workspace from any MCP client via https://www.taskade.com/mcp (OAuth 2.0) — create projects, manage and prompt agents, and edit your Genesis app's source. - [Workspace MCP](https://docs.taskade.com/developers/workspace-mcp): Connect Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and more to your workspace via @taskade/mcp-server. - [Workspace MCP: Advanced](https://docs.taskade.com/developers/workspace-mcp/workspace-mcp-advanced): Rate limits, multi-client setup, troubleshooting, and security for production use. - [Run Your Live App by Talking to Claude](https://docs.taskade.com/developers/workspace-mcp/run-your-app-with-ai): Run your Genesis app's day-to-day data through conversation — no IDs, no API code. -- [Hosted Taskade MCP (Beta)](https://docs.taskade.com/developers/workspace-mcp/genesis-app-mcp): Orchestrate your workspace from any MCP client via https://www.taskade.com/mcp (OAuth 2.0) — create projects, manage and prompt agents, and edit your Genesis app's source. - [MCP Connectors](https://docs.taskade.com/developers/mcp-connectors): Connect Genesis apps and AI agents to 31+ external services using the Model Context Protocol. ## Changelog