---
slug: developer-api-read-workspace
title: List and read your Tasks, Docs, and Skills
category: capability
status: published
tags: [tasks, list tasks, docs, skills, read, cursor, pagination, ownership, messages, thread, body, 任务列表, 知识库, 技能, 文档, 分页]
aliases: []
lastEditAt: 2026-08-09
---
These endpoints return what your workspace authored. Platform-authored
Skills that ship with Tycoon, and Skills your workspace subscribes to
from another workspace, appear in the Skills list where relevant but
their bodies are never returned. Docs marked internal are never returned.

### List Tasks

`tasks:read` scope. Returns Tasks created through this API key, newest
first. Optional query parameters: `status` (one of `queued`, `running`,
`requires_action`, `waiting`, `completed`, `canceled`), `limit` (1–200,
default 50), and `cursor` (opaque string from a previous `next_cursor`).

```bash
curl -sS \
  "https://tycoon.us/api/public/tasks?status=completed&limit=20" \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "tasks": [
    {
      "task": {
        "id": "cm...",
        "reference": "growth-42",
        "title": "Competitor research",
        "status": "completed",
        "created_at": "2026-08-01T12:00:00.000Z",
        "started_at": "2026-08-01T12:00:03.000Z",
        "completed_at": "2026-08-01T12:04:21.000Z",
        "updated_at": "2026-08-01T12:04:21.000Z"
      },
      "outcome": null,
      "playbook": null,
      "result": null,
      "required_actions": [],
      "usage": null,
      "poll_after_ms": null
    }
  ],
  "next_cursor": "eyJjcmVhdGVkQXQiOi..."
}
```

The list omits `result`, `outcome`, and `usage`. Call `GET /tasks/{id}`
to read the accepted result text and cost data for a specific Task.

### Read a Task's message thread

`tasks:read` scope. Returns the Task's Comment thread in ascending
sequence order. This is the read side of `POST /tasks/:id/messages`; a
message sent to a running Task appears here once accepted. It is not a
separate comment system. Optional query parameters: `limit` (1–500,
default 100) and `after_sequence` (non-negative integer).

```bash
curl -sS "https://tycoon.us/api/public/tasks/cm.../messages" \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "messages": [
    {
      "id": "cm...",
      "body": "Prioritize competitors under 50 employees.",
      "created_at": "2026-08-01T12:02:00.000Z",
      "sequence": 1,
      "author": { "kind": "human" }
    },
    {
      "id": "cm...",
      "body": "Understood. Focusing on the SMB segment...",
      "created_at": "2026-08-01T12:02:04.000Z",
      "sequence": 2,
      "author": { "kind": "agent", "slug": "astra" }
    }
  ],
  "next_cursor": 2
}
```

`next_cursor` is the sequence number of the last returned message. Pass
it as `after_sequence` to read messages that arrived later. `null` means
this response reached the current end of the thread.

### List and read Docs

`docs:read` scope. The list omits the body; fetch `GET /docs/{id}` to
read it. Both endpoints accept `limit` (1–200, default 50) and `cursor`
(opaque string from `next_cursor`).

```bash
curl -sS https://tycoon.us/api/public/docs \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "docs": [
    {
      "id": "doc...",
      "title": "Organic growth playbook",
      "tags": ["growth", "seo"],
      "created_at": "2026-07-01T09:00:00.000Z",
      "updated_at": "2026-08-01T11:00:00.000Z"
    }
  ],
  "next_cursor": null
}
```

To read a Doc with its body:

```bash
curl -sS https://tycoon.us/api/public/docs/doc... \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "id": "doc...",
  "title": "Organic growth playbook",
  "tags": ["growth", "seo"],
  "body": "# Organic growth playbook\n\n...",
  "created_at": "2026-07-01T09:00:00.000Z",
  "updated_at": "2026-08-01T11:00:00.000Z"
}
```

### List and read Skills

`skills:read` scope. The list includes every workspace-scoped Skill in
your working set, including ones your workspace subscribes to from
another workspace. Subscribed Skills carry `body_exportable: false`; the
body endpoint returns `404` for them. Both endpoints accept `limit`
(1–200, default 50) and `cursor` (opaque string from `next_cursor`).

```bash
curl -sS https://tycoon.us/api/public/skills \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "skills": [
    {
      "id": "sk...",
      "slug": "seo-experiment-method",
      "name": "SEO experiment method",
      "description": "Operating method for organic-growth experiments.",
      "tags": ["seo", "experiment"],
      "source_type": "LOCAL",
      "updated_at": "2026-08-01T10:00:00.000Z",
      "body_exportable": true
    },
    {
      "id": "sk...",
      "slug": "software-team",
      "name": "Software Team",
      "description": "Tycoon coding and delivery method.",
      "tags": ["engineering"],
      "source_type": "WORKSPACE",
      "updated_at": "2026-08-01T09:00:00.000Z",
      "body_exportable": false
    }
  ],
  "next_cursor": null
}
```

To read a Skill body:

```bash
curl -sS \
  https://tycoon.us/api/public/skills/seo-experiment-method \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "id": "sk...",
  "slug": "seo-experiment-method",
  "name": "SEO experiment method",
  "description": "Operating method for organic-growth experiments.",
  "tags": ["seo", "experiment"],
  "source_type": "LOCAL",
  "markdown": "# SEO experiment method\n\n...",
  "updated_at": "2026-08-01T10:00:00.000Z"
}
```

Fetching a Skill whose body is not yours returns `404`. That response is
indistinguishable from a missing Skill: the endpoint never discloses the
existence of platform or other-workspace content.

## Next steps

- [Create and read Tasks](/docs/create-read-tasks)
- [Messages, actions, and approvals](/docs/actions-approvals)
- [Idempotency and errors](/docs/reliability-errors)