docs: restructure API docs and update Work Item terminology #163
Conversation
- Add Users and Stickies API documentation - Add Initiatives, Teamspaces and Pages API documentation - Add Customers, Customer Requests and Properties API documentation - Update WorkItemTypes: replace "Issue" with "Work Item", fix endpoints - Reorganize navigation: nest related APIs under parent groups - Ensure consistent "Work Item" terminology across all docs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughA large-scale API reference documentation update introducing new endpoint documentation for customer, initiative, page, and sticky management features, while systematically renaming issue-related terminology to work item terminology across cycle, module, and issue documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Areas requiring attention:
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api-reference/cycle/overview.mdx (1)
88-107: Response example is missing newly documented Cycle Object attributes.The Cycle Object schema now includes
archived_at,timezone, andversion(lines 76-86), but the response example doesn't include these fields. Either update the example to include all attributes or clarify if these are optional response fields.
♻️ Duplicate comments (1)
api-reference/page/get-project-page.mdx (1)
1-14: Add response documentation to GET endpoints.Like the workspace page GET endpoint, this also lacks response structure and examples. See comment on get-workspace-page.mdx for suggested fix pattern.
🧹 Nitpick comments (17)
api-reference/issue/add-issue.mdx (2)
23-25: Add guidance on valid UUID values forstateandtypefields.The
stateandtypefields are described as UUIDs but offer no guidance on where to find or how to discover valid values. Consider adding a reference to:
- An endpoint or documentation that lists available states and work item types
- A link to a related API reference (e.g., "Work Item Types" or "Work Item States" endpoints)
This will improve usability for developers consuming the API.
Also applies to: 43-45
39-41: Clarify constraints onestimate_pointfield.The description states "value between 0-7" but does not specify:
- Whether the range is inclusive or exclusive
- Whether the field accepts only integers or also decimals
- What error occurs if an out-of-range value is provided
Consider updating the description to be more explicit (e.g., "Integer estimate point from 0 to 7 (inclusive)").
api-reference/issue/get-issue-sequence-id.mdx (1)
4-4: Clarify relationship between identifier-based and UUID-based endpoint retrieval.This endpoint retrieves work items by identifier (e.g., PROJ-123), while
get-issue-detail.mdxretrieves byissue_id(UUID). Document both patterns clearly to help users understand when to use each approach. Consider adding a note explaining the difference.Also applies to: 11-13
api-reference/issue-activity/list-issue-activities.mdx (1)
2-3: Terminology-documentation alignment gap: title uses "work item" but endpoint uses "issues".The documentation title and description refer to "work item activities," but the underlying API endpoint path still uses
/issues/. While this is a documentation-layer change, consider clarifying in the content whether the endpoint slug/issues/represents work items or if this warrants a separate API version. This helps prevent user confusion.api-reference/issue-types/types/overview.mdx (1)
54-54: Minor grammar improvement: use hyphens for compound adjectives.Lines 54 and 58 use "auto generated" where "auto-generated" would be grammatically correct when used as a compound adjective modifying a noun.
Apply this diff:
- The workspace which the work item type is part of (auto generated from backend) + The workspace which the work item type is part of (auto-generated from backend)- The project which the work item type is part of (auto generated from backend) + The project which the work item type is part of (auto-generated from backend)Also applies to: 58-58
api-reference/page/get-workspace-page.mdx (1)
1-12: Add response documentation to GET endpoints.The GET endpoint documentation lacks response structure, examples, and status codes. Developers need to understand what data is returned.
Consider adding a "Response" section referencing or repeating the Page Object schema from overview.mdx, and include a ResponseExample block (see overview.mdx lines 55-67 for the schema):
<ParamField path="page_id" type="string" required></ParamField> +### Response + +Returns a Page object. See [Page Object](#page-object) in the overview for schema details. + +<ResponseExample> +```json JSON +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "created_at": "2023-11-19T11:56:55.176802Z", + "updated_at": "2023-11-19T11:56:55.176809Z", + "name": "Getting Started", + "description_html": "<h1>Welcome</h1><p>This is a getting started guide.</p>", + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430" +} +``` +</ResponseExample>api-reference/page/overview.mdx (1)
55-67: Cross-reference the response example from individual GET endpoints.The ResponseExample here is valuable for developers. Consider documenting that the individual GET endpoint files (get-workspace-page.mdx and get-project-page.mdx) should reference this schema, or duplicate the example in those files for completeness.
This will help developers understand the response structure immediately when reading the individual GET endpoint documentation.
api-reference/issue/search-issues.mdx (1)
9-9: Add description for theworkspace-slugpath parameter.The
workspace-slugparameter lacks a description of its expected format and purpose. Provide clarity on whether it's a human-readable slug or UUID, and what workspace it refers to.Apply this diff to add a description:
-<ParamField path="workspace-slug" type="string" required></ParamField> +<ParamField path="workspace-slug" type="string" required> +The workspace's URL slug (unique workspace identifier) +</ParamField>api-reference/sticky/get-sticky-detail.mdx (1)
1-12: Add response documentation.This endpoint file lacks response schema and example. Most endpoint documentation should include a response section showing the sticky object structure or indicating a 2xx success status code with relevant data.
api-reference/sticky/delete-sticky.mdx (1)
1-12: Document the DELETE response.DELETE endpoints should document the expected response (e.g., 204 No Content, 200 OK, or the deleted object structure).
api-reference/sticky/add-sticky.mdx (1)
13-31: Clarify parameter optionality and add response documentation.The body parameters (name, description_html, logo_props, color, background_color) lack
requiredattributes, making it unclear which fields are mandatory. Additionally, the POST response should document the created sticky object structure and HTTP status code (likely 201 Created).api-reference/sticky/list-stickies.mdx (1)
1-19: Add response documentation for list endpoint.The GET list endpoint should document the response structure (e.g., array of sticky objects, pagination metadata, HTTP 200 status) and provide an example response showing the list format and any pagination indicators.
api-reference/issue-attachments/overview.mdx (2)
55-57: Acknowledge theISSUE_ATTACHMENTenum value alongside work item terminology.Line 55–57 states: "Always
ISSUE_ATTACHMENTfor work item attachments." This correctly notes that the enum value is immutable for backward compatibility. The wording is clear, but consider adding a brief comment (e.g., "for backward compatibility") to explain why the enum hasn't been renamed.Example: "Always
ISSUE_ATTACHMENTfor work item attachments (for backward compatibility)."
135-149: Add type hints to clarify the new optional reference fields.The new fields (
user,draft_issue,comment,page) at lines 135–149 are documented as_string_IDs. For consistency and clarity, consider:
- Adding clarification that these are UUIDs/IDs (matching the pattern of
workspace,project,issue)- Or, explicitly state these are foreign key references to other entities
This improves developer understanding without adding substantial documentation burden.
api-reference/customer/add-customer-property.mdx (1)
1-72: Comprehensive parameter documentation.The endpoint documentation is well-structured with all relevant parameters documented. However, consider adding
requiredattributes to body parameters that are mandatory (e.g., ifnameorproperty_typeare required), to match the clarity of path parameters marked as required. This helps API consumers understand which fields are optional.api-reference/customer/update-customer-property-detail.mdx (1)
1-74: LGTM!PATCH endpoint documentation is clear. Note: For PATCH semantics, all body parameters should typically be optional, allowing partial updates. Consider adding this clarification or optional markers if not documented at the schema level.
api-reference/initiative/add-initiative.mdx (1)
45-47: Add type details for logo_props object.The
logo_propsfield (lines 45-47) is documented as typeobjectwith minimal description. Consider documenting its expected structure (e.g., properties, constraints) to help API consumers construct valid payloads.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (107)
api-reference/customer/add-customer-property.mdx(1 hunks)api-reference/customer/add-customer-request.mdx(1 hunks)api-reference/customer/add-customer.mdx(1 hunks)api-reference/customer/delete-customer-property.mdx(1 hunks)api-reference/customer/delete-customer-request.mdx(1 hunks)api-reference/customer/delete-customer.mdx(1 hunks)api-reference/customer/get-customer-detail.mdx(1 hunks)api-reference/customer/get-customer-property-detail.mdx(1 hunks)api-reference/customer/get-customer-property-value.mdx(1 hunks)api-reference/customer/get-customer-request-detail.mdx(1 hunks)api-reference/customer/link-work-items-to-customer.mdx(1 hunks)api-reference/customer/list-customer-properties.mdx(1 hunks)api-reference/customer/list-customer-property-values.mdx(1 hunks)api-reference/customer/list-customer-requests.mdx(1 hunks)api-reference/customer/list-customer-work-items.mdx(1 hunks)api-reference/customer/list-customers.mdx(1 hunks)api-reference/customer/overview.mdx(1 hunks)api-reference/customer/unlink-work-item-from-customer.mdx(1 hunks)api-reference/customer/update-customer-detail.mdx(1 hunks)api-reference/customer/update-customer-property-detail.mdx(1 hunks)api-reference/customer/update-customer-property-value.mdx(1 hunks)api-reference/customer/update-customer-request-detail.mdx(1 hunks)api-reference/cycle-issue/overview.mdx(0 hunks)api-reference/cycle/add-cycle-work-items.mdx(2 hunks)api-reference/cycle/add-cycle.mdx(1 hunks)api-reference/cycle/archive-cycle.mdx(1 hunks)api-reference/cycle/delete-cycle.mdx(1 hunks)api-reference/cycle/get-cycle-detail.mdx(1 hunks)api-reference/cycle/list-archived-cycles.mdx(1 hunks)api-reference/cycle/list-cycle-work-items.mdx(2 hunks)api-reference/cycle/overview.mdx(3 hunks)api-reference/cycle/remove-cycle-work-item.mdx(2 hunks)api-reference/cycle/transfer-cycle-work-items.mdx(1 hunks)api-reference/cycle/unarchive-cycle.mdx(1 hunks)api-reference/cycle/update-cycle-detail.mdx(2 hunks)api-reference/initiative/add-epics-to-initiative.mdx(1 hunks)api-reference/initiative/add-initiative-label.mdx(1 hunks)api-reference/initiative/add-initiative.mdx(1 hunks)api-reference/initiative/add-labels-to-initiative.mdx(1 hunks)api-reference/initiative/add-projects-to-initiative.mdx(1 hunks)api-reference/initiative/delete-initiative-label.mdx(1 hunks)api-reference/initiative/delete-initiative.mdx(1 hunks)api-reference/initiative/get-initiative-detail.mdx(1 hunks)api-reference/initiative/get-initiative-label-detail.mdx(1 hunks)api-reference/initiative/list-initiative-epics.mdx(1 hunks)api-reference/initiative/list-initiative-labels-for-initiative.mdx(1 hunks)api-reference/initiative/list-initiative-labels.mdx(1 hunks)api-reference/initiative/list-initiative-projects.mdx(1 hunks)api-reference/initiative/list-initiatives.mdx(1 hunks)api-reference/initiative/overview.mdx(1 hunks)api-reference/initiative/remove-epics-from-initiative.mdx(1 hunks)api-reference/initiative/remove-labels-from-initiative.mdx(1 hunks)api-reference/initiative/remove-projects-from-initiative.mdx(1 hunks)api-reference/initiative/update-initiative-detail.mdx(1 hunks)api-reference/initiative/update-initiative-label-detail.mdx(1 hunks)api-reference/issue-activity/get-issue-activity-detail.mdx(1 hunks)api-reference/issue-activity/list-issue-activities.mdx(1 hunks)api-reference/issue-activity/overview.mdx(3 hunks)api-reference/issue-attachments/complete-upload.mdx(1 hunks)api-reference/issue-attachments/delete-attachment.mdx(1 hunks)api-reference/issue-attachments/get-attachment-detail.mdx(1 hunks)api-reference/issue-attachments/get-attachments.mdx(2 hunks)api-reference/issue-attachments/get-upload-credentials.mdx(1 hunks)api-reference/issue-attachments/overview.mdx(4 hunks)api-reference/issue-attachments/update-attachment.mdx(1 hunks)api-reference/issue-comment/add-issue-comment.mdx(2 hunks)api-reference/issue-comment/delete-issue-comment.mdx(1 hunks)api-reference/issue-comment/get-issue-comment-detail.mdx(1 hunks)api-reference/issue-comment/list-issue-comments.mdx(2 hunks)api-reference/issue-comment/overview.mdx(2 hunks)api-reference/issue-comment/update-issue-comment-detail.mdx(2 hunks)api-reference/issue-types/types/add-issue-type.mdx(1 hunks)api-reference/issue-types/types/delete-issue-type.mdx(1 hunks)api-reference/issue-types/types/get-issue-type-details.mdx(1 hunks)api-reference/issue-types/types/list-issue-types.mdx(1 hunks)api-reference/issue-types/types/overview.mdx(1 hunks)api-reference/issue-types/types/update-issue-types.mdx(1 hunks)api-reference/issue/add-issue.mdx(2 hunks)api-reference/issue/delete-issue.mdx(1 hunks)api-reference/issue/get-issue-detail.mdx(2 hunks)api-reference/issue/get-issue-sequence-id.mdx(1 hunks)api-reference/issue/list-issues.mdx(1 hunks)api-reference/issue/overview.mdx(3 hunks)api-reference/issue/search-issues.mdx(1 hunks)api-reference/issue/update-issue-detail.mdx(2 hunks)api-reference/module-issue/overview.mdx(0 hunks)api-reference/module/add-module-work-items.mdx(2 hunks)api-reference/module/add-module.mdx(1 hunks)api-reference/module/archive-module.mdx(1 hunks)api-reference/module/delete-module.mdx(1 hunks)api-reference/module/get-module-detail.mdx(1 hunks)api-reference/module/list-archived-modules.mdx(1 hunks)api-reference/module/list-module-work-items.mdx(2 hunks)api-reference/module/overview.mdx(2 hunks)api-reference/module/remove-module-work-item.mdx(2 hunks)api-reference/module/unarchive-module.mdx(1 hunks)api-reference/module/update-module-detail.mdx(2 hunks)api-reference/page/add-project-page.mdx(1 hunks)api-reference/page/add-workspace-page.mdx(1 hunks)api-reference/page/get-project-page.mdx(1 hunks)api-reference/page/get-workspace-page.mdx(1 hunks)api-reference/page/overview.mdx(1 hunks)api-reference/sticky/add-sticky.mdx(1 hunks)api-reference/sticky/delete-sticky.mdx(1 hunks)api-reference/sticky/get-sticky-detail.mdx(1 hunks)api-reference/sticky/list-stickies.mdx(1 hunks)api-reference/sticky/overview.mdx(1 hunks)
⛔ Files not processed due to max files limit (16)
- api-reference/sticky/update-sticky-detail.mdx
- api-reference/teamspace/add-projects-to-teamspace.mdx
- api-reference/teamspace/add-teamspace-members.mdx
- api-reference/teamspace/add-teamspace.mdx
- api-reference/teamspace/delete-teamspace.mdx
- api-reference/teamspace/get-teamspace-detail.mdx
- api-reference/teamspace/list-teamspace-members.mdx
- api-reference/teamspace/list-teamspace-projects.mdx
- api-reference/teamspace/list-teamspaces.mdx
- api-reference/teamspace/overview.mdx
- api-reference/teamspace/remove-projects-from-teamspace.mdx
- api-reference/teamspace/remove-teamspace-members.mdx
- api-reference/teamspace/update-teamspace-detail.mdx
- api-reference/user/get-current-user.mdx
- api-reference/user/overview.mdx
- mint.json
💤 Files with no reviewable changes (2)
- api-reference/cycle-issue/overview.mdx
- api-reference/module-issue/overview.mdx
🧰 Additional context used
🪛 LanguageTool
api-reference/issue-comment/list-issue-comments.mdx
[grammar] ~15-~15:
Context: ...pe="string" required> ### Query parameters Filter by work item UUID Filter by project UUID Filter by workspace UUID Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/initiative/list-initiative-epics.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/initiative/overview.mdx
[style] ~94-~94: To form a complete sentence, be sure to include a subject.
Context: ...e` string State of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, ...
(MISSING_IT_THERE)
api-reference/issue/search-issues.mdx
[grammar] ~1-~1: Dit kan een fout zijn.
Context: --- title: Search work items description: Searches for work items across a workspace api: GET /api/v1/workspaces/{workspace-slug}/issues/search/ --- ### Path parameters <ParamField path="works...
(QB_NEW_NL)
[grammar] ~7-~7: Dit kan een fout zijn.
Context: .../issues/search/ --- ### Path parameters ### Query parameters <ParamField query="sea...
(QB_NEW_NL)
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Search query string Filter by project UUID
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/initiative/list-initiative-labels-for-initiative.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/customer/list-customers.mdx
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Filter by workspace UUID Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/initiative/list-initiative-labels.mdx
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/issue-types/types/overview.mdx
[grammar] ~54-~54: Use a hyphen to join words.
Context: ...hich the work item type is part of (auto generated from backend) - project _uu...
(QB_NEW_EN_HYPHEN)
[grammar] ~58-~58: Use a hyphen to join words.
Context: ...hich the work item type is part of (auto generated from backend) - created_at ...
(QB_NEW_EN_HYPHEN)
api-reference/issue-comment/overview.mdx
[grammar] ~78-~78: Use a hyphen to join words.
Context: ...ated_by` uuid These values are auto saved and represent the id of the user t...
(QB_NEW_EN_HYPHEN)
api-reference/initiative/list-initiatives.mdx
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/issue/list-issues.mdx
[grammar] ~12-~12:
Context: ...pe="string" required> ### Query parameters Filter by project UUID Filter by state UUID Filter by assignee user UUID Number of results to return Number of results to skip Comma-separated list of fields to expand. Can include: type, module, labels, assignees, state, project
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/initiative/list-initiative-projects.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/sticky/list-stickies.mdx
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/customer/list-customer-property-values.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Filter by customer UUID Filter by property UUID Filter by workspace UUID Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/issue-types/types/list-issue-types.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Project UUID to filter work item types Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/customer/list-customer-requests.mdx
[grammar] ~13-~13:
Context: ...pe="string" required> ### Query parameters Filter by customer UUID Filter by workspace UUID Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
api-reference/customer/list-customer-properties.mdx
[grammar] ~11-~11:
Context: ...pe="string" required> ### Query parameters Filter by workspace UUID Number of results to return Number of results to skip
(QB_NEW_NL_OTHER_ERROR_IDS_UNNECESSARY_ORTHOGRAPHY_SPACE)
|
|
||
| - `state` _string_ | ||
|
|
||
| State of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED |
There was a problem hiding this comment.
Fix incomplete sentence in state attribute description.
The description for the state attribute is a sentence fragment. Complete the sentence for grammatical correctness.
Apply this diff to fix the grammar:
- State of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED
+ The state of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| State of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED | |
| The state of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED |
🧰 Tools
🪛 LanguageTool
[style] ~94-~94: To form a complete sentence, be sure to include a subject.
Context: ...e` string State of the initiative. Can be: DRAFT, PLANNED, ACTIVE, COMPLETED, ...
(MISSING_IT_THERE)
🤖 Prompt for AI Agents
In api-reference/initiative/overview.mdx around line 94, the "state" attribute
description is a sentence fragment; replace the fragment with a complete
sentence such as "State of the initiative. Possible values are: DRAFT, PLANNED,
ACTIVE, COMPLETED, and CLOSED." to correct the grammar and clarify the allowed
values.
| --- | ||
| title: Delete attachment | ||
| description: Deletes an attachment from a work item | ||
| api: DELETE /api/v1/workspaces/{workspace-slug}/projects/{project_id}/issues/{issue_id}/issue-attachments/{attachment_id}/ | ||
| --- | ||
|
|
||
| ### Path parameters | ||
|
|
||
| <ParamField path="workspace-slug" type="string" required> | ||
| 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`. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="project_id" type="string" required>The unique identifier of the project</ParamField> | ||
|
|
||
| <ParamField path="issue_id" type="string" required>The unique identifier of the work item</ParamField> | ||
|
|
||
| <ParamField path="attachment_id" type="string" required>The unique identifier of the attachment</ParamField> | ||
|
|
There was a problem hiding this comment.
Add Response section documenting success/error behavior.
DELETE endpoints require documentation of the expected HTTP status code (e.g., 204 No Content) and any response body or error states. This helps clients understand what to expect and how to handle different outcomes.
Document what success looks like (status code, response body if any) and possible error responses.
🤖 Prompt for AI Agents
In api-reference/issue-attachments/delete-attachment.mdx lines 1-18, add a
"Responses" section describing the expected HTTP status codes and bodies:
specify the success response (204 No Content for successful deletion and note
that the body is empty) and list common error responses (e.g., 401 Unauthorized,
403 Forbidden, 404 Not Found when workspace/project/issue/attachment doesn't
exist, 400 Bad Request for malformed params, and 500 Internal Server Error),
include short descriptions of each and any JSON error shape the API returns
(error code/message), and provide one brief example for success and one for an
error to illustrate handling.
| --- | ||
| title: Get attachment details | ||
| description: Gets the details of a specific attachment | ||
| api: GET /api/v1/workspaces/{workspace-slug}/projects/{project_id}/issues/{issue_id}/issue-attachments/{attachment_id}/ | ||
| --- | ||
|
|
||
| ### Path parameters | ||
|
|
||
| <ParamField path="workspace-slug" type="string" required> | ||
| 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`. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="project_id" type="string" required>The unique identifier of the project</ParamField> | ||
|
|
||
| <ParamField path="issue_id" type="string" required>The unique identifier of the work item</ParamField> | ||
|
|
||
| <ParamField path="attachment_id" type="string" required>The unique identifier of the attachment</ParamField> | ||
|
|
There was a problem hiding this comment.
Add Response section documenting the endpoint's return structure.
The documentation lacks a Response section showing what this GET endpoint returns. Developers need to see the response schema and/or an example to use the endpoint effectively. This should document the Work Item Attachment Object structure as defined in the overview.
Reference the Response sections in get-attachments.mdx or get-upload-credentials.mdx as models for the response format to include here.
🤖 Prompt for AI Agents
In api-reference/issue-attachments/get-attachment-detail.mdx around lines 1 to
18, the doc is missing a Response section; add a Response heading that documents
the GET endpoint's return structure by including the Work Item Attachment Object
schema and an example JSON response (modeled after the Response sections in
get-attachments.mdx or get-upload-credentials.mdx). List and describe each
top-level field (id, filename, url, content_type, size, created_at, etc.)
consistent with the overview definition, and provide at least one concrete
example response body and the response HTTP status (200).
| --- | ||
| title: Update attachment | ||
| description: Updates the details of an attachment | ||
| api: PATCH /api/v1/workspaces/{workspace-slug}/projects/{project_id}/issues/{issue_id}/issue-attachments/{attachment_id}/ | ||
| --- | ||
|
|
||
| ### Path parameters | ||
|
|
||
| <ParamField path="workspace-slug" type="string" required> | ||
| 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`. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="project_id" type="string" required>The unique identifier of the project</ParamField> | ||
|
|
||
| <ParamField path="issue_id" type="string" required>The unique identifier of the work item</ParamField> | ||
|
|
||
| <ParamField path="attachment_id" type="string" required>The unique identifier of the attachment</ParamField> | ||
|
|
||
| ### Body | ||
|
|
||
| <ParamField body="attributes" type="object"> | ||
| File metadata object containing name, size, and type | ||
| </ParamField> | ||
|
|
||
| <ParamField body="asset" type="string"> | ||
| Storage path/identifier for the attachment file | ||
| </ParamField> | ||
|
|
||
| <ParamField body="entity_type" type="string"> | ||
| Entity type of the attachment | ||
| </ParamField> | ||
|
|
||
| <ParamField body="entity_identifier" type="string"> | ||
| Entity identifier for the attachment | ||
| </ParamField> | ||
|
|
||
| <ParamField body="is_deleted" type="boolean"> | ||
| Whether the attachment has been deleted | ||
| </ParamField> | ||
|
|
||
| <ParamField body="is_archived" type="boolean"> | ||
| Whether the attachment has been archived | ||
| </ParamField> | ||
|
|
||
| <ParamField body="external_id" type="string"> | ||
| External identifier if the attachment is imported to Plane | ||
| </ParamField> | ||
|
|
||
| <ParamField body="external_source" type="string"> | ||
| Name of the source if the attachment is imported to Plane | ||
| </ParamField> | ||
|
|
||
| <ParamField body="size" type="number"> | ||
| File size in bytes | ||
| </ParamField> | ||
|
|
||
| <ParamField body="is_uploaded" type="boolean"> | ||
| Whether the file has been successfully uploaded | ||
| </ParamField> | ||
|
|
||
| <ParamField body="storage_metadata" type="object"> | ||
| Cloud storage metadata | ||
| </ParamField> | ||
|
|
There was a problem hiding this comment.
Add Response section and clarify which fields are mutable in PATCH request.
The endpoint documents body parameters (lines 19–63) but lacks:
- A Response section showing the updated attachment object structure
- Guidance on which fields are actually mutable (vs read-only metadata)
Without this, developers won't know what PATCH requests should do or what to expect in responses. Add a Response section following the pattern in get-upload-credentials.mdx.
| - `created_by` , `updated_by` _uuid_ | ||
|
|
||
| These values are auto saved and represent the id of the user that created or updated the comment |
There was a problem hiding this comment.
Fix grammar: use hyphenated "auto-saved" for compound adjective.
Line 78 should use the hyphenated form to correctly modify the noun. Apply this fix:
- These values are auto saved and represent the id of the user that created or updated the comment
+ These values are auto-saved and represent the id of the user that created or updated the comment🧰 Tools
🪛 LanguageTool
[grammar] ~78-~78: Use a hyphen to join words.
Context: ...ated_by` uuid These values are auto saved and represent the id of the user t...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In api-reference/issue-comment/overview.mdx around lines 76 to 78, the phrase
"These values are auto saved and represent the id of the user..." should use the
hyphenated compound adjective "auto-saved"; update the sentence to read "These
values are auto-saved and represent the id of the user that created or updated
the comment" (keep punctuation and surrounding formatting intact).
api-reference/page/overview.mdx
Outdated
| ```http | ||
| POST /api/v1/workspaces/:workspace-slug/pages/ | ||
| GET /api/v1/workspaces/:workspace-slug/pages/:page_id/ | ||
| ``` | ||
|
|
||
| ### Project Pages | ||
|
|
||
| ```http | ||
| POST /api/v1/workspaces/:workspace-slug/projects/:project_id/pages/ | ||
| GET /api/v1/workspaces/:workspace-slug/projects/:project_id/pages/:page_id/ | ||
| ``` |
There was a problem hiding this comment.
Fix path parameter notation inconsistency.
The code blocks in this overview use :param notation (e.g., :workspace-slug, :page_id), but the individual endpoint files use {param} notation in their frontmatter (e.g., {workspace-slug}, {page_id}). Standardize to one format for consistency.
Apply this diff to match the frontmatter format used in individual endpoint files:
### Workspace Pages
```http
-POST /api/v1/workspaces/:workspace-slug/pages/
-GET /api/v1/workspaces/:workspace-slug/pages/:page_id/
+POST /api/v1/workspaces/{workspace-slug}/pages/
+GET /api/v1/workspaces/{workspace-slug}/pages/{page_id}/Project Pages
-POST /api/v1/workspaces/:workspace-slug/projects/:project_id/pages/
-GET /api/v1/workspaces/:workspace-slug/projects/:project_id/pages/:page_id/
+POST /api/v1/workspaces/{workspace-slug}/projects/{project_id}/pages/
+GET /api/v1/workspaces/{workspace-slug}/projects/{project_id}/pages/{page_id}/
<details>
<summary>🤖 Prompt for AI Agents</summary>
In api-reference/page/overview.mdx around lines 11 to 21, the HTTP path examples
use colon-style parameters (e.g., :workspace-slug, :page_id) but the rest of the
docs use brace-style parameters; update the two code blocks so all path params
use curly-brace notation: replace :workspace-slug with {workspace-slug},
:page_id with {page_id}, and :project_id with {project_id} in the POST/GET lines
shown so they match the frontmatter format used by the individual endpoint
files.
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
api-reference/sticky/overview.mdx
Outdated
| ```http | ||
| POST /api/v1/workspaces/:workspace-slug/stickies/ | ||
| GET /api/v1/workspaces/:workspace-slug/stickies/ | ||
| GET /api/v1/workspaces/:workspace-slug/stickies/:sticky_id/ | ||
| PATCH /api/v1/workspaces/:workspace-slug/stickies/:sticky_id/ | ||
| DELETE /api/v1/workspaces/:workspace-slug/stickies/:sticky_id/ | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
Standardize path parameter syntax across API documentation.
The API endpoints listed in the overview use colon-style syntax (:workspace-slug, :sticky_id), while the individual endpoint documentation files use brace-style syntax ({workspace-slug}, {sticky_id}). Ensure consistent notation throughout the API reference for clarity. Typically, OpenAPI/Swagger docs use braces, while some custom formats use colons.
🏁 Script executed:
#!/bin/bash
# Search for the overview file and endpoint documentation
echo "=== Finding sticky API documentation files ==="
fd -e mdx -e md . api-reference/sticky/ 2>/dev/null | head -20
echo -e "\n=== Examining overview.mdx content ==="
if [ -f "api-reference/sticky/overview.mdx" ]; then
cat "api-reference/sticky/overview.mdx"
fi
echo -e "\n=== Searching for endpoint documentation files ==="
fd -e mdx -e md . api-reference/ | grep -E "(sticky|endpoint)" | head -20Length of output: 2582
🏁 Script executed:
#!/bin/bash
# Examine each endpoint file for parameter syntax patterns
echo "=== Examining add-sticky.mdx ==="
cat api-reference/sticky/add-sticky.mdx | head -50
echo -e "\n=== Examining list-stickies.mdx ==="
cat api-reference/sticky/list-stickies.mdx | head -50
echo -e "\n=== Examining get-sticky-detail.mdx ==="
cat api-reference/sticky/get-sticky-detail.mdx | head -50
echo -e "\n=== Examining update-sticky-detail.mdx ==="
cat api-reference/sticky/update-sticky-detail.mdx | head -50
echo -e "\n=== Examining delete-sticky.mdx ==="
cat api-reference/sticky/delete-sticky.mdx | head -50
echo -e "\n=== Searching for parameter syntax patterns ==="
echo "Colon-style occurrences (:workspace-slug, :sticky_id):"
rg -n ':[a-z_-]+' api-reference/sticky/ | head -20
echo -e "\nBrace-style occurrences ({workspace-slug}, {sticky_id}):"
rg -n '\{[a-z_-]+\}' api-reference/sticky/ | head -20Length of output: 3795
Update overview.mdx to use brace-style syntax ({workspace-slug}, {sticky_id}) for consistency with all individual endpoint documentation.
The inconsistency is confirmed. The overview.mdx uses colon-style (:workspace-slug, :sticky_id) on lines 10–14, while all five endpoint files (add-sticky.mdx, list-stickies.mdx, get-sticky-detail.mdx, update-sticky-detail.mdx, delete-sticky.mdx) use brace-style ({workspace-slug}, {sticky_id}) in their api: frontmatter fields. Standardize on braces to match the individual endpoint documentation and align with OpenAPI/Swagger conventions.
🤖 Prompt for AI Agents
In api-reference/sticky/overview.mdx around lines 9 to 15, the route examples
use colon-style parameters (e.g. :workspace-slug, :sticky_id) which are
inconsistent with the individual endpoint docs; update each route to use
brace-style parameters ({workspace-slug}, {sticky_id}) so all five lines (POST,
GET list, GET detail, PATCH, DELETE) match the other endpoint files and
OpenAPI-style conventions.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
This is the final PR Bugbot will review for you during this billing cycle
Your free Bugbot reviews will reset on December 20
Details
Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.
To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.
|
|
||
| <ParamField query="limit" type="number"> | ||
| Number of results to skip for pagination. | ||
| </ParamField> |
There was a problem hiding this comment.
Bug: Duplicate query parameter named limit in epics endpoint
The query parameters section defines limit twice. The second parameter should be offset for pagination to work correctly. Line 23-24 defines limit, and line 23-25 redefines limit with a description that says "skip for pagination", which indicates it should be offset.
| <ParamField path="intake_id" type="string" required></ParamField> | ||
|
|
||
| <ParamField path="issue_id" type="string" required></ParamField> | ||
| <ParamField path="intake_id" type="string" required>The unique identifier for the intake work item.</ParamField> |
There was a problem hiding this comment.
Bug: Inconsistent parameter names in intake-issue endpoints
The URL path specifies {issue_id} but the parameter documentation defines both work_item_id and intake_id parameters. This mismatch will cause confusion for API users and is likely a result of incomplete terminology updates. The documented parameter name must match the actual URL placeholder.
Additional Locations (2)
|
|
||
| <ParamField body="issue_ids" type="string[]" required> | ||
| Array of work item IDs to link to the customer. | ||
| </ParamField> |
There was a problem hiding this comment.
Bug: Deprecated parameter name issue_ids in customer linking
The body parameter is named issue_ids, which uses the old terminology. Given the PR's goal to replace "Issue" with "Work Item" terminology, this should be consistent with how similar endpoints name their parameters. However, the actual API endpoint may still use issue_ids, so this could be a documentation-only issue if the backend hasn't been updated. The parameter naming should be verified against the actual API implementation.
|
|
||
| <ParamField body="name" type="string"> | ||
| Name of the work item type. | ||
| </ParamField> |
There was a problem hiding this comment.
Bug: Missing required attribute on name in add-issue-type
The name body parameter is not marked as required, but based on consistent patterns in similar "create" endpoints (add-cycle, add-module) where name is required, this appears to be a bug introduced during the refactoring. The name field should have the required attribute to match API expectations and documentation consistency.
Description
Type of Change
Summary by CodeRabbit
Note
Overhauls API docs with new resources (Customers, Initiatives, Teamspaces, Pages, Stickies, Worklogs), standardizes from “issues” to “work-items” with updated endpoints, expands cycles/modules, and reorganizes navigation with redirects.
customers(properties, requests, link/unlink work items),initiatives(labels, projects, epics),teamspaces(members, projects),pages(workspace/project),stickies,users,members,worklogs.issues→work-itemsacross links/comments/attachments/activity/types/properties/values; add search; documentfields/expandand cursor pagination./issuesand/inbox-issues; examples updated towork-items.mint.jsonnavigation/grouping; add redirects fromcycle-issue/module-issueto new paths; enable interactive API playground.Written by Cursor Bugbot for commit 2d3a0d6. This will update automatically on new commits. Configure here.