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)
| --- | ||
| title: Unlink work item from customer | ||
| description: Unlinks a work item (issue) from a customer | ||
| api: DELETE /api/v1/workspaces/{workspace-slug}/customers/{customer_id}/issues/{issue_id}/ | ||
| --- |
There was a problem hiding this comment.
🧩 Analysis chain
Terminology inconsistency: title uses "work item" but endpoint uses "issue".
The documentation title and description reference "work item" (per PR objectives), but the endpoint path uses /issues/{issue_id}/. This conflicts with the PR goal to "ensure consistent 'Work Item' terminology across all docs."
Either update the endpoint path/parameter to use work-item terminology, or update the title and description to align with the actual "issue" terminology in the URL.
🏁 Script executed:
#!/bin/bash
# Verify the actual endpoint path for unlinking work items in the API
# Search for similar issue/work-item endpoints in docs to understand naming convention
rg -i "issues|work.item" api-reference/customer/ -A 2 -B 2 | head -50Length of output: 2936
Terminology inconsistency confirmed: documentation titles reference "work item" but actual API paths use "issues".
The inconsistency extends beyond this file. All customer work-item API reference files (link-work-items-to-customer.mdx, list-customer-work-items.mdx, and overview.mdx) follow the same pattern: titles and descriptions use "work item" terminology, but all endpoint paths and parameter names still reference "issues" and "issue_id". The overview.mdx file explicitly lists the endpoints as /customers/{customer_id}/issues/ and /issues/{issue_id}/.
This creates a mismatch where documentation talks about "work items" but the actual API routes contain "issues". To resolve this consistently across all docs per the PR objectives, either:
- Update the backend endpoint paths to use
/work-items/terminology, or - Revert all documentation titles and descriptions to use "issue" terminology to match the actual API URLs
🤖 Prompt for AI Agents
In api-reference/customer/unlink-work-item-from-customer.mdx around lines 1 to 5
there is a terminology mismatch: the file title/description use "work item"
while the API path and parameters use "issues"; update this file and the related
customer files (link-work-items-to-customer.mdx, list-customer-work-items.mdx,
and overview.mdx) to consistently use "issue" terminology to match the actual
endpoints—replace titles, descriptions, and any "work item" occurrences with
"issue", ensure parameter names remain issue_id, and verify the overview lists
the endpoints as /customers/{customer_id}/issues/ and /issues/{issue_id}/ so the
docs align with the backend routes.
|
|
||
| - `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).
| <ParamField query="issue" type="string"> | ||
| Filter by work item UUID |
There was a problem hiding this comment.
Clarify query parameter naming to match actual API field semantics.
The query parameter is named issue (the actual API field name), but the description says "Filter by work item UUID." This creates confusion—the parameter name and description don't align.
Options:
- Update description to: "Filter by issue UUID (work item)" to acknowledge the field name is issue-based
- Or: "Filter by work item UUID (API field: issue)" to be explicit about the field
Choose whichever matches your API documentation style guide for backward-compatibility field names.
🤖 Prompt for AI Agents
In api-reference/issue-attachments/get-attachments.mdx around lines 18-19, the
ParamField for query="issue" says "Filter by work item UUID" which conflicts
with the actual API field name; update the description to be explicit about both
the field name and semantics — e.g. change it to "Filter by work item UUID (API
field: issue)" so readers see the API parameter name and its meaning and
preserve backward-compatibility.
| --- | ||
| 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).
| <ParamField body="description_html" type="string"> | ||
| HTML description of the work item | ||
| </ParamField> | ||
|
|
||
| <ParamField body="state" type="string"> | ||
| UUID of the state for the work item | ||
| </ParamField> | ||
|
|
||
| <ParamField body="assignees" type="string[]"> | ||
| Array of user UUIDs assigned to the work item | ||
| </ParamField> | ||
|
|
||
| <ParamField body="labels" type="string[]"> | ||
| Array of label UUIDs for the work item | ||
| </ParamField> | ||
|
|
||
| <ParamField body="parent" type="string"> | ||
| UUID of the parent work item | ||
| </ParamField> | ||
|
|
||
| <ParamField body="estimate_point" type="string"> | ||
| Estimate point for the work item (value between 0-7) | ||
| </ParamField> | ||
|
|
||
| <ParamField body="type" type="string"> | ||
| UUID of the work item type | ||
| </ParamField> | ||
|
|
||
| <ParamField body="module" type="string"> | ||
| UUID of the module the work item belongs to | ||
| </ParamField> | ||
|
|
||
| <ParamField body="target_date" type="string"> | ||
| Target date of the work item in YYYY-MM-DD format | ||
| </ParamField> | ||
|
|
||
| <ParamField body="start_date" type="string"> | ||
| Start date of the work item in YYYY-MM-DD format | ||
| </ParamField> | ||
|
|
||
| <ParamField body="priority" type="string"> | ||
| Priority of the work item. Can be: none, urgent, high, medium, low | ||
| </ParamField> |
There was a problem hiding this comment.
🧩 Analysis chain
Verify all new body parameters are supported by the backend API.
The documentation significantly expands the supported request body from just name to 14 fields. Ensure that:
- All these parameters are actually supported by the backend endpoint
- The field names and types match the backend implementation
- The descriptions accurately reflect behavior (e.g.,
estimate_pointrange "0-7", date formats) - This documentation expansion is consistent with other similar endpoints in your API
🏁 Script executed:
#!/bin/bash
# Description: Verify consistency of endpoint documentation updates across related files
# Check for other issue/work-item update endpoints to ensure consistency
fd -e mdx 'issue|work.item' --type f | xargs grep -l "PATCH.*issues" | head -10
# Look for other update endpoints to compare parameter patterns
fd -e mdx --type f | xargs grep -l "target_date\|estimate_point" | head -5Length of output: 398
Continuing verification. I need to examine the related update endpoints and search for backend implementation details.
Also searching for backend implementation clues:
🏁 Script executed:
#!/bin/bash
# Extract body parameters from related update endpoints for comparison
echo "=== update-inbox-issue-detail.mdx body parameters ==="
grep -A 2 'body=' api-reference/inbox-issue/update-inbox-issue-detail.mdx | head -20
echo ""
echo "=== update-intake-issue-detail.mdx body parameters ==="
grep -A 2 'body=' api-reference/intake-issue/update-intake-issue-detail.mdx | head -20
echo ""
echo "=== Searching for OpenAPI/API schema definitions ==="
fd -e json -e yaml -e yml 'openapi|api|schema' --type f | head -10Length of output: 379
🏁 Script executed:
#!/bin/bash
# Look for backend code that might define the issue update endpoint
fd -e py -e js -e ts -e go 'issue' --type f | grep -i 'update\|patch' | head -10
# Check for any README or documentation about API structure
find . -maxdepth 3 -name 'README*' -o -name 'SCHEMA*' -o -name 'API*' | head -10Length of output: 11
I found a significant inconsistency. Let me examine the full context of the file under review and check the README.
---
🏁 Script executed:
```shell
#!/bin/bash
# View the complete update-issue-detail.mdx file
cat api-reference/issue/update-issue-detail.mdx
echo ""
echo "=== README content (first 100 lines) ==="
head -100 README.md
Length of output: 3263
This is a documentation-only repository. I need to search for the actual Plane backend to verify if these parameters are truly supported, since the backend code isn't in this repo.
---
🌐 Web query:
```web
Plane API update issue endpoint documentation supported parameters
💡 Result:
According to Plane's API reference, the PATCH update-issue endpoint is:
PATCH /api/v1/workspaces/{workspace-slug}/projects/{project_id}/issues/{issue_id}
Path parameters (required):
- workspace-slug
- project_id
- issue_id
Request body (documented):
- name (string) — required. [1]
(Other issue-related endpoints — e.g., updating comments or issue-properties — have their own bodies/parameters in the Plane docs.) [1][2]
Sources:
[1] Plane API — Update issue details.
[2] Plane API — Update issue comment details.
Remove unsupported body parameters from the documentation.
According to Plane's official API reference, the PATCH update-issue endpoint only supports the name parameter in the request body. The documented parameters at lines 21-63 (description_html, state, assignees, labels, parent, estimate_point, type, module, target_date, start_date, priority) are not currently supported by the backend API. Remove these parameters from the documentation to match the actual API contract. This aligns with the related endpoints (update-inbox-issue-detail.mdx and update-intake-issue-detail.mdx), which correctly document only the name parameter.
🤖 Prompt for AI Agents
In api-reference/issue/update-issue-detail.mdx around lines 21 to 63, the
documentation lists unsupported body parameters (description_html, state,
assignees, labels, parent, estimate_point, type, module, target_date,
start_date, priority); remove those ParamField entries and leave only the
supported `name` parameter in the PATCH request body so the doc matches the
actual API contract and mirrors the other update-* issue docs.
| ```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 -->
| ```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.
Description
Type of Change
Summary by CodeRabbit