Stages API

The Stages API provides read-only access to project stages and their tasks. Use it to list stages in a project or get a specific stage with its full task tree.

Capability required: stages:read

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// List stages in a project
const stages = await rp.stages.list("project-id-123");
// -> [{ id: "abc", title: "Sprint 1", slug: "sprint-1", totalTasks: 12, doneTasks: 5, ... }]

// Get a specific stage with tasks
const stage = await rp.stages.get("project-id-123", "stage-id-abc");
// -> { id: "abc", title: "Sprint 1", tasks: [{ id: "t1", title: "Fix bug", status: "done", ... }] }

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    getProjectProgress: async (_params, { rp }) => {
      const stages = await rp.stages.list("project-id");
      return stages.map(s => ({
        title: s.title,
        progress: s.totalTasks > 0 ? s.doneTasks / s.totalTasks : 0,
      }));
    },
  },
});

server.start();

API Reference

rp.stages.list(projectId)

Returns all stages in a project.

Parameter	Type	Description
projectId	string	The project ID
Returns	Promise<StageSummary[]>	List of stage summaries

rp.stages.get(projectId, stageId)

Returns a specific stage with its full task tree.

Parameter	Type	Description
projectId	string	The project ID
stageId	string	The stage ID
Returns	Promise<StageDetail | null>	The stage with tasks, or null

StageSummary

Field	Type	Description
id	string	Stage ID
title	string	Stage title
slug	string	URL-safe slug
projectId	string	Owning project ID
totalTasks	number	Total task count
doneTasks	number	Completed task count
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)

StageDetail

Field	Type	Description
id	string	Stage ID
title	string	Stage title
description	string | null	Optional description
slug	string	URL-safe slug
version	number	Data version
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)
tasks	StageTask[]	Task tree

StageTask

Field	Type	Description
id	string	Task ID
title	string	Task title
content	string | null	Task body/description
status	string	Status (e.g. “todo”, “doing”, “done”)
labels	string[]	Assigned label IDs
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)
children	StageTask[]	Nested sub-tasks

Manifest Configuration

{
  "capabilities": [
    "stages:read"
  ]
}

Notes

• This API is read-only. Resources cannot create, update, or delete stages or tasks.
• Stages are stored as JSON files in the project’s rightplace/stages/ directory.
• The task tree can be nested (tasks with children).