Skip to content

Commit 216e4bc

Browse files
danciaclaradanciaclara
committed
Epics endpoint and other minor fixes
1 parent 0122729 commit 216e4bc

File tree

15 files changed

+264
-6
lines changed

15 files changed

+264
-6
lines changed

‎api-reference/epics/get-epic-detail.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Retrieve an epic
3+
description: Retrieves the details of an existing epic by its ID.
4+
api: GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/epics/{epic_id}/
5+
---
6+
7+
## Path parameters
8+
9+
<ParamField path="workspace_slug" type="string" required>
10+
The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`.
11+
</ParamField>
12+
13+
<ParamField path="project_id" type="string" required>
14+
The unique identifier for the project.
15+
</ParamField>
16+
17+
<ParamField path="epic_id" type="string" required>
18+
The unique identifier for the epic.
19+
</ParamField>
20+

‎api-reference/epics/list-epics.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: List all epics
3+
description: Returns a list of all epics in a project.
4+
api: GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/epics/
5+
---
6+
7+
## Path parameters
8+
9+
<ParamField path="workspace_slug" type="string" required>
10+
The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`.
11+
</ParamField>
12+
13+
<ParamField path="project_id" type="string" required>
14+
The unique identifier for the project.
15+
</ParamField>
16+
17+
## Query parameters
18+
19+
<ParamField query="limit" type="number">
20+
Number of results to return per page.
21+
</ParamField>
22+
23+
<ParamField query="offset" type="number">
24+
Number of results to skip for pagination.
25+
</ParamField>
26+

‎api-reference/epics/overview.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Overview
3+
---
4+
5+
Epics help you group related tasks into a larger work item, providing a hierarchical structure for managing complex projects. Use epics to break down major objectives into smaller, manageable pieces while keeping everything organized.
6+
[Learn more about Epics](https://docs.plane.so/core-concepts/issues/epics).
7+
8+
## The Epics object
9+
**Attributes**
10+
11+
- `id` string
12+
13+
Unique identifier for the epic.
14+
15+
- `name` string
16+
17+
Name of the epic.
18+
19+
- `description` object
20+
21+
JSON representation of the epic description.
22+
23+
- `description_html` string
24+
25+
HTML-formatted description of the epic.
26+
27+
- `description_stripped` string
28+
29+
Plain text version of the description.
30+
31+
- `description_binary` string
32+
33+
Binary representation of the description.
34+
35+
- `state` string
36+
37+
ID of the state (status) of the epic.
38+
39+
- `priority` string
40+
41+
Priority level. Possible values: `none`, `urgent`, `high`, `medium`, `low`.
42+
43+
- `assignees` array
44+
45+
Array of user IDs assigned to the epic.
46+
47+
- `labels` array
48+
49+
Array of label IDs applied to the epic.
50+
51+
- `type` string
52+
53+
ID of the work item type for the epic.
54+
55+
- `estimate_point` string
56+
57+
ID of the estimate point, or null if not estimated.
58+
59+
- `point` integer
60+
61+
Point value for the epic, or null.
62+
63+
- `start_date` string
64+
65+
Start date of the epic in YYYY-MM-DD format.
66+
67+
- `target_date` string
68+
69+
Target completion date in YYYY-MM-DD format.
70+
71+
- `parent` string
72+
73+
ID of the parent work item, or null if no parent.
74+
75+
- `sequence_id` integer
76+
77+
Auto-generated sequential identifier for the epic within the project.
78+
79+
- `sort_order` number
80+
81+
Auto-generated sort order for display purposes.
82+
83+
- `is_draft` boolean
84+
85+
Whether the epic is a draft.
86+
87+
- `completed_at` timestamp
88+
89+
Time at which the epic was completed, or null if not completed.
90+
91+
- `archived_at` timestamp
92+
93+
Time at which the epic was archived, or null if not archived.
94+
95+
- `project` string
96+
97+
ID of the project containing this epic.
98+
99+
- `workspace` string
100+
101+
ID of the workspace containing this epic.
102+
103+
- `external_id` string
104+
105+
External identifier if imported from another system, or null.
106+
107+
- `external_source` string
108+
109+
Name of the source system if imported, or null.
110+
111+
- `deleted_at` timestamp
112+
113+
Time at which the epic was deleted, or null if not deleted.
114+
115+
- `created_at` timestamp
116+
117+
Time at which the epic was created.
118+
119+
- `updated_at` timestamp
120+
121+
Time at which the epic was last updated.
122+
123+
- `created_by` string
124+
125+
ID of the user who created the epic.
126+
127+
- `updated_by` string
128+
129+
ID of the user who last updated the epic.
130+
131+
<ResponseExample>
132+
```json EPICS OBJECT
133+
{
134+
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
135+
"name": "Develop Mobile Application Framework",
136+
"description": {},
137+
"description_html": "<p class=\"editor-paragraph-block\">Create a cross-platform mobile application framework that supports all core system functionalities with native-like performance and user experience</p>",
138+
"description_stripped": "Create a cross-platform mobile application framework that supports all core system functionalities with native-like performance and user experience",
139+
"description_binary": null,
140+
"state": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
141+
"priority": "medium",
142+
"assignees": [],
143+
"labels": [
144+
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
145+
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
146+
],
147+
"type": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
148+
"estimate_point": null,
149+
"point": null,
150+
"start_date": "2025-02-28",
151+
"target_date": "2025-06-20",
152+
"parent": null,
153+
"sequence_id": 57,
154+
"sort_order": 605535.0,
155+
"is_draft": false,
156+
"completed_at": null,
157+
"archived_at": null,
158+
"project": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
159+
"workspace": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
160+
"external_id": null,
161+
"external_source": null,
162+
"deleted_at": null,
163+
"created_at": "2025-03-01T21:23:54.645263+05:30",
164+
"updated_at": "2025-03-03T10:38:44.667276+05:30",
165+
"created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
166+
"updated_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
167+
}
168+
```
169+
</ResponseExample>

‎api-reference/initiative/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Initiatives are high-level strategic goals that help organize and track work acr
66

77
[Learn more about Initiatives](https://docs.plane.so/core-concepts/projects/initiatives)
88

9-
## The Initiative object
9+
## The Initiatives object
1010

1111
**Attributes**
1212

‎mint.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -358,6 +358,14 @@
358358
"api-reference/worklogs/delete-worklog"
359359
]
360360
},
361+
{
362+
"group": "Epics",
363+
"pages": [
364+
"api-reference/epics/overview",
365+
"api-reference/epics/list-epics",
366+
"api-reference/epics/get-epic-detail"
367+
]
368+
},
361369
{
362370
"group": "Initiatives",
363371
"pages": [

‎self-hosting/govern/database-and-storage.mdx‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@ sidebarTitle: External database and storage
66

77
The Prime CLI lets you easily configure your Commercial Edition instance, providing options to customize the PostgreSQL database, Redis, external storage, and other advanced settings.
88

9-
1. Run the Prime CLI with ↓:
9+
<Warning>
10+
**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`.
11+
</Warning>
12+
13+
1. Run the Prime CLI with ↓:
14+
1015
```sudo prime-cli```
1116

1217
2. Once the CLI is running, enter `configure`, which will guide you through a step-by-step form where you can specify the following:

‎self-hosting/govern/oidc-sso.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Go to `/god-mode/authentication/oidc` on your Plane app and find the configs ↓
4848

4949
- Copy the `User info URL` from your IdP and paste it into the field for it on `/god-mode/authentication/oidc/`.
5050

51-
Used to get an authenticating user's `email`, `first_name` and the `last_name` values from the IdP, this too can be copied over from the `.well-known/` directory.
51+
Used to get an authenticating user's information from the IdP. Plane requires the `email` field for user authentication. The `first_name` and `last_name` fields are optional but recommended for a complete user profile. This URL can be copied from the `.well-known/` directory.
5252

5353
- Copy the `Authorize URL` over from the `.well-known/` directory and paste it into the field for it on Plane's `/god-mode/authentication/oidc/`.\
5454
This is the URL that Plane's login screen redirects to when your users click `Sign up with <name of IDP>` or `Login with <name of IdP>`.

‎self-hosting/govern/reverse-proxy.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ Make sure to update the following environment variables in your plane.env file.
2525
```bash
2626
sudo prime-cli restart
2727
```
28+
29+
<Warning>
30+
**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`.
31+
</Warning>
2832

2933
## Proxy setup
3034

‎self-hosting/govern/saml-sso.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ By default, your IdP will send the value listed under `Property`. You have to ma
4343
| user.lastName | last_name |
4444
| user.email | email |
4545

46+
<Note>
47+
**first_name** and **last_name** are optional but recommended for complete user profiles. If these are not provided, Plane will create the user account with just the email address.
48+
49+
</Note>
50+
4651
<Tip>
4752
Depending on your IdP, you will have to find both the `Name ID format` and the three other user identification properties on different screens. Please refer to your IdP's documentation when configuring these up on your IdP. Additionally, you may have to configure the IdP to sign assertions. Irrespective of that, you have to copy the signing certificate from the IdP.
4853
</Tip>

‎self-hosting/manage/backup-restore.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ Backing up your data regularly helps prevent data loss and allows you to restore
77

88
## Backup data
99

10+
<Warning>
11+
**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`.
12+
</Warning>
13+
1014
Create a backup of your Plane data with ↓:
1115
```bash
1216
sudo prime-cli backup

0 commit comments

Comments
 (0)