Skip to content

docs: add create project with template API endpoint #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pushya22 wants to merge 2 commits into
base: master
Choose a base branch
from
+183 −0
Open

docs: add create project with template API endpoint #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff7984a
docs: add create project with template API endpoint
pushya22 Jun 20, 2026
c54516c
docs: add template_id attribute to project overview
pushya22 Jun 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -501,6 +501,10 @@ export default extendConfig(
items: [
{ text: "Overview", link: "/api-reference/project/overview" },
{ text: "Create Project", link: "/api-reference/project/add-project" },
{
text: "Create Project with Template",
link: "/api-reference/project/create-project-with-template",
},
{ text: "List Projects", link: "/api-reference/project/list-projects" },
{ text: "Get Project", link: "/api-reference/project/get-project-detail" },
{ text: "Update Project", link: "/api-reference/project/update-project-detail" },
Expand Down
175 changes: 175 additions & 0 deletions docs/api-reference/project/create-project-with-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
---
title: Create project with template
description: Create a project from an existing project template via Plane API. HTTP request format, parameters, scopes, and example responses for create project with template.
keywords: plane, plane api, rest api, api integration, project, create project with template, project template
---

# Create project with template

<div class="api-endpoint-badge">
<span class="method post">POST</span>
<span class="path">/api/v1/workspaces/{workspace_slug}/projects/templates/use/</span>
</div>

<div class="api-two-column">
<div class="api-left">

Create a new project from an existing project template. The template's states, labels, estimates, modules, and work items are copied into the new project. Fields provided in the request body override the template defaults.

<div class="params-section">

### Path Parameters

@coderabbitai coderabbitai Bot Jun 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix heading hierarchy: use h2 instead of h3 for main sections.

The document jumps from h1 (# Create project with template) directly to h3 (### Path Parameters), skipping the h2 level. Per markdown best practices and the static analysis flag (MD001), section headings should increment by one level at a time.

Change ### Path Parameters, ### Body Parameters, and ### Scopes to ## Path Parameters, ## Body Parameters, and ## Scopes.

Also applies to: 36-36, 81-81

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 21-21: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/api-reference/project/create-project-with-template.md` at line 21, The
markdown document has incorrect heading hierarchy, jumping from h1 directly to
h3 and skipping the h2 level. Change the heading level for the main section
headings "Path Parameters", "Body Parameters", and "Scopes" from h3 (###) to h2
(##) to ensure proper hierarchical progression and comply with markdown best
practices.

Source: Linters/SAST tools


<div class="params-list">

<ApiParam name="workspace_slug" type="string" :required="true">

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`.

</ApiParam>

</div>
</div>

<div class="params-section">

### Body Parameters

<div class="params-list">

<ApiParam name="template_id" type="string" :required="true">

The ID of the project template to instantiate. Must belong to the same workspace.

</ApiParam>

<ApiParam name="name" type="string" :required="false">

Name of the new project. Overrides the template default.

</ApiParam>

<ApiParam name="identifier" type="string" :required="false">

Short identifier for the project (e.g. `MAR`). Overrides the template default.

</ApiParam>

<ApiParam name="description" type="string" :required="false">

Description of the new project. Overrides the template default.

</ApiParam>

<ApiParam name="network" type="integer" :required="false">

Network visibility of the project. `0` for secret, `2` for public. Overrides the template default.

</ApiParam>

<ApiParam name="project_lead" type="string" :required="false">

User ID of the project lead. The lead is added as a project admin. Overrides the template default.

</ApiParam>

</div>
</div>

<div class="params-section">

### Scopes

`write` or `projects:write`

</div>

</div>

<div class="api-right">

<CodePanel title="Create project with template" :languages="['cURL', 'Python', 'JavaScript']">
<template #curl>

```bash
curl -X POST \
"https://api.plane.so/api/v1/workspaces/my-workspace/projects/templates/use/" \
-H "X-API-Key: $PLANE_API_KEY" \
# Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_id": "7a2d3972-80a5-4ac5-8bb5-03026671826a",
"name": "Mobile App Revamp",
"identifier": "MAR",
"description": "Project created from the Agile Project Setup template",
"network": 2,
"project_lead": "0d8d8869-3ed1-4fb4-b5c4-ff672888f5e2"
}'
```

</template>
<template #python>

```python
import requests

response = requests.post(
"https://api.plane.so/api/v1/workspaces/my-workspace/projects/templates/use/",
headers={"X-API-Key": "your-api-key"},
json={
"template_id": "7a2d3972-80a5-4ac5-8bb5-03026671826a",
"name": "Mobile App Revamp",
"identifier": "MAR",
"description": "Project created from the Agile Project Setup template",
"network": 2,
"project_lead": "0d8d8869-3ed1-4fb4-b5c4-ff672888f5e2"
}
)
print(response.json())
```

</template>
<template #javascript>

```javascript
const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/projects/templates/use/", {
method: "POST",
headers: {
"X-API-Key": "your-api-key",
"Content-Type": "application/json",
},
body: JSON.stringify({
template_id: "7a2d3972-80a5-4ac5-8bb5-03026671826a",
name: "Mobile App Revamp",
identifier: "MAR",
description: "Project created from the Agile Project Setup template",
network: 2,
project_lead: "0d8d8869-3ed1-4fb4-b5c4-ff672888f5e2",
}),
});
const data = await response.json();
```
Comment on lines +134 to +151

@coderabbitai coderabbitai Bot Jun 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Wrap long JavaScript fetch URL to stay within 120-character line width.

Line 135 exceeds the 120-character limit per Prettier guidelines. The fetch URL + opening brace should be split onto multiple lines.

✨ Proposed fix for line wrapping 
 <template `#javascript`>

 ```javascript
-const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/projects/templates/use/", {
+const response = await fetch(
+  "https://api.plane.so/api/v1/workspaces/my-workspace/projects/templates/use/",
+  {
   method: "POST",
   headers: {
     "X-API-Key": "your-api-key",
     "Content-Type": "application/json",
   },
   body: JSON.stringify({
     template_id: "7a2d3972-80a5-4ac5-8bb5-03026671826a",
     name: "Mobile App Revamp",
     identifier: "MAR",
     description: "Project created from the Agile Project Setup template",
     network: 2,
     project_lead: "0d8d8869-3ed1-4fb4-b5c4-ff672888f5e2",
   }),
-});
+  },
+);
 const data = await response.json();

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/api-reference/project/create-project-with-template.md around lines 134

  • 151, The fetch function call with the long URL exceeds the 120-character line
    width limit. Refactor the const response await fetch statement by breaking it
    across multiple lines: place the fetch opening on the first line, move the URL
    string to the next line with proper indentation, move the options object
    (containing method, headers, and body properties) to the next line, and place
    the closing parentheses and semicolon on the final line to conform to the
    120-character line width requirement.

</details>

<!-- fingerprinting:phantom:triton:mongoose -->

<!-- cr-comment:v1:fecfd93224ce5bd563fd781d -->

_Source: Coding guidelines_

<!-- This is an auto-generated comment by CodeRabbit -->


</template>
</CodePanel>

<ResponsePanel status="201">

```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Mobile App Revamp",
"description": "Project created from the Agile Project Setup template",
"identifier": "MAR",
"network": 2,
"project_lead": "0d8d8869-3ed1-4fb4-b5c4-ff672888f5e2",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
```

</ResponsePanel>

</div>

</div>
4 changes: 4 additions & 0 deletions docs/api-reference/project/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,10 @@ Projects organize your team's work within a workspace. Each project contains wor

Default state which will be used when the issues will be auto closed

- `template_id` _uuid_

UUID of the project template used to create this project.

</div>
<div class="api-right">

Expand Down
Loading