Merge branch 'v2-more' into v2

aheckmann · aheckmann · commit 0933c52ad7be · 2025-08-01T07:23:04.000-07:00
diff --git a/api/schema.yaml b/api/schema.yaml
diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx
@@ -0,0 +1,287 @@
+---
+title: Plane API Documentation
+sidebar_label: Introduction
+description: Use the Plane API to programatically read and write changes to your Workspaces, Projects, Work Items and much more.
+sidebar_position: 0
+---
+
+{frontMatter.description && <h3 className="description">{frontMatter.description}</h3>}
+
+:::info
+The Plane cloud API is available at `https://api.plane.so/`
+:::
+
+## Quick start
+
+### 1. Get your API key
+
+To make requests to the Plane API, you'll need an API key.  This key is used to
+verify your client's identity and permissions.  The key must be passed as the
+value of the `X-API-Key` header.
+
+Enough talk. Let's get you an API key!
+
+:::tip
+You must have a Plane account or be registered to your instance to generate a key.
+:::
+
+1. Log into your Plane account and go to **Profile Settings**
+  ![Profile Settings](/images/api-reference/profile-settings.png#center)
+2. Go to **Personal Access Tokens**
+  ![API Tokens](/images/api-reference/api-tokens-plane.png#center)
+3. Click **Add personal access token**
+  ![Add API key](/images/api-reference/add-api-key-plane.png#center)
+4. Enter a title and description to help you remember why you created this key
+5. Optionally set an expiry date for the key, after which time the key will no longer be valid
+
+:::danger
+Treat your API key like a password. Keep it secret. Keep it safe. It is
+important to store your API key securely and keep it confidential to prevent
+unauthorized access to your account. Do not share it or expose it in
+client-side code.
+:::
+
+### 2. Execute an HTTP request 🔄
+
+When issuing HTTP requests to the API, you'll always set the `x-api-key`
+request header to your API key.  For example, if using `curl` this looks like:
+
+```bash
+curl -L 'https://api.plane.so/api/v1/workspaces/:slug/projects/:project_id/issues/' \
+-H 'Accept: application/json' \
+-H 'X-API-Key: <X-API-Key>'
+```
+
+Run the above command to receive your first response from the Plane API.
+
+### 3. Congratulations 🥳
+
+Congratulations! You've successfully run your first HTTP request using the
+[Plane](https://plane.so) API. Next, browse the rest of our documentation for
+more examples of how you can integrate your project! 😎
+
+___
+
+## General API usage
+
+### Base URL
+
+All requests to the Plane Cloud API must be made to the following base URL:
+
+```
+https://api.plane.so/
+```
+
+:::info
+If you're using a self-hosted instance of Plane, your API base URL will differ based on your custom domain and setup.
+:::
+
+### Security recommendations
+
+- **Keep the API Key Secret**: Treat your API key like a password. Do not share it or expose it in client-side code.
+- **Regenerate Key If Compromised**: If you suspect that your API key has been compromised, generate a new one immediately and update your applications.
+
+### API key errors
+
+- If the **`X-API-Key`** header is not included, the API will return an error indicating that authentication is required.
+- If the provided API key is invalid or expired, the API will return an error message indicating an authentication failure.
+
+### HTTP methods
+
+HTTP defines a set of request methods, also known as HTTP verbs, to indicate the desired action for a given resource.
+
+Given below is the list of methods commonly adopted by Plane's API:
+
+|Verb  |Description                                        |Example                            |
+|------|---------------------------------------------------|-----------------------------------|
+|GET   |Requests a representation of the specified resource|Fetch all work items from a project|
+|POST  |Submits an entity to the specified resource        |Create a project                   |
+|DELETE|Deletes the specified resource                     |Delete a work item                 |
+|PATCH |Applies partial modifications to a resource        |Edit a module                      |
+
+### Status codes
+
+Given below is the list of the most commonly encountered success responses:
+
+| Status Code    | Description                                                                            |
+|----------------|----------------------------------------------------------------------------------------|
+| 200 OK         | The request succeeded. Generally used in GET or PATCH requests.     |
+| 201 Created    | The request succeeded and a new resource was created. Generally used in POST requests. |
+| 204 No Content | The request succeeded and no body is returned. Generally used in DELETE requests.      |
+
+### Error responses
+
+Given below is the list of the most commonly encountered error responses:
+
+| Status Code               | Description                                                                                                                                                                           |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 400 Bad Request           | The server cannot or will not process the request due to something that is perceived to be a client error.                                                                            |
+| 401 Unauthorized          | Although the HTTP standard specifies "unauthorized", semantically, this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. |
+| 404 Not Found             | The server cannot find the requested resource. This means the URL is not recognized.                                                                                                  |
+| 429 Throttling Error      | The server has received too many requests from your client within a short period of time. Retry the request later. You can read more in our [rate-limiting](#rate-limiting) section.                  |
+| 500 Internal Server Error | The server has encountered a situation it does not know how to handle, and failed to process the request.                                                                                                                |
+| 502 Bad Gateway           | The server received an invalid response from another service which was required to handle the request.                                          |
+| 503 Service Unavailable   | The server is not ready to handle the request. Common causes are a server that is down for maintenance or overloaded.                                                              |
+| 504 Gateway Timeout       | The server was unable to receive a timely response from a downstream service.
+
+
+---
+
+## Pagination
+
+The Plane API implements a cursor-based pagination system, allowing clients to
+efficiently navigate through large datasets. The system uses a cursor parameter
+to manage the position and direction of pagination.
+
+### Querystring parameters
+
+Paging is controlled by clients via the following querystring parameters.
+
+- **`per_page` (optional)**: Number of items to display per page. Defaults to 100. The maximum allowed value is 100.
+- **`cursor` (optional)**: Cursor string (see below) to navigate to a specific page. If not provided, pagination starts from the first page.
+
+### Cursor string format
+
+The cursor string is formatted as **`value:offset:is_prev`**, where:
+
+- **`value`** represents the page size (number of items per page)
+- **`offset`** is the current page number (starting from 0)
+- **`is_prev`** indicates whether the cursor is moving to the previous page (**`1`**) or to the next page (**`0`**)
+
+### Example: Fetching the first page
+
+```
+GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?per_page=20
+```
+
+#### Pagination response
+
+The paginated response includes the following fields:
+
+- **`next_cursor`**: Cursor string for the next page
+- **`prev_cursor`**: Cursor string for the previous page
+- **`next_page_results`**: Boolean indicating if there are more results after the current page
+- **`prev_page_results`**: Boolean indicating if there are results before the current page
+- **`count`**: Total number of items on the current page
+- **`total_pages`**: Estimated total number of pages
+- **`total_results`**: Total number of items across all pages
+- **`extra_stats`**: Additional statistics, if any
+- **`results`**: Array of items for the current page
+
+Here's an example response for the first page of results:
+
+```json
+{
+  "next_cursor": "20:1:0",
+  "prev_cursor": "",
+  "next_page_results": true,
+  "prev_page_results": false,
+  "count": 20,
+  "total_pages": 50,
+  "total_results": 1000,
+  "extra_stats": {},
+  "results": [ ... items ... ]
+}
+```
+
+### Example: Fetching the next page
+
+```
+GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues?per_page=20&cursor=20:1:0
+```
+
+#### Pagination next page response
+
+```json
+{
+  "next_cursor": "20:2:0",
+  "prev_cursor": "20:0:1",
+  "next_page_results": true,
+  "prev_page_results": true,
+  "count": 20,
+  "total_pages": 50,
+  "total_results": 1000,
+  "extra_stats": {},
+  "results": [ ... items ... ]
+}
+```
+
+### Pagination errors
+
+- **Invalid Cursor Format**: If the provided cursor string is not in the correct format, the API will respond with an error message indicating an invalid cursor format.
+- **Pagination Limits**: Requests exceeding the maximum **`per_page`** limit will receive an error response detailing the maximum allowed value.
+
+---
+
+## Rate limiting
+
+To ensure fair usage and maintain the overall quality of service for the
+community, the Plane API implements rate limiting. Rate limiting restricts the
+number of requests a client can make within a certain time frame.
+
+### Rate limit details
+
+- **Limit**: Each client is limited to 60 requests per minute
+- **Reset Interval**: The rate limit counter resets every minute
+- **Scope of Limitation**: The rate limit applies to all requests made with a given API key
+
+### Identifying your rate limit status
+
+Your current rate limit status is communicated in the response headers of each API request:
+
+- **`X-RateLimit-Remaining`**: The number of requests remaining in the current rate limit window
+- **`X-RateLimit-Reset`**: The time at which the current rate limit window resets (in UTC epoch seconds)
+
+```
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1700327957
+```
+
+---
+
+## Fine tuning response fields
+
+The Plane API provides flexible data retrieval capabilities through two powerful query
+parameters: `fields` and `expand`. These parameters allow clients to tailor the
+response data to their specific needs, optimizing both the payload size and the
+clarity of the response.
+
+### Fields parameter
+
+The `fields` parameter enables clients to selectively retrieve only a subset of
+fields for a given resource.
+
+:::tip
+The `fields` parameter is particularly useful for reducing response time, size
+and bandwidth, especially when your client requires only specific pieces of data.
+:::
+
+The **`fields`** parameter accepts a comma-separated list of field names that
+the client wants to be included in the response. For example, to include only
+the `id`, `name`, and `description` fields, send the following querystring parameters:
+
+```
+GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?fields=id,name,description
+```
+
+#### Fields parameter error handling
+
+Invalid or unrecognized field names passed in the **`fields`** parameter will
+result in an error response, indicating which fields are invalid.
+
+### Expand parameter
+
+The `expand` parameter allows clients to request additional related information to
+be included in the response. This is useful for retrieving detailed information
+about nested resources without making separate API calls.
+
+For example, to return the resource data along with expanded information about
+the `assignees` and `state`, send the following querystring parameters:
+
+```
+GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?expand=assignees,state
+```
+
+#### Expand parameter error handling
+
+If **`expand`** is used on fields that cannot be expanded, an appropriate error message will be returned.
diff --git a/docs/api/the-plane-rest-api.info.mdx b/docs/api/the-plane-rest-api.info.mdx
@@ -2,8 +2,6 @@
 id: the-plane-rest-api
 title: "The Plane REST API"
 description: "The Plane REST API"
-sidebar_label: Introduction
-sidebar_position: 0
 hide_title: true
 custom_edit_url: null
 ---
@@ -49,10 +47,10 @@ Visit our quick start guide and full API documentation at [developers.plane.so](
       label={"API Key: ApiKeyAuthentication"}
       value={"ApiKeyAuthentication"}
     >
-      
-      
+
+
       API key authentication. Provide your API key in the X-API-Key header.
-      
+
       <div>
         <table>
           <tbody>
@@ -76,10 +74,10 @@ Visit our quick start guide and full API documentation at [developers.plane.so](
       label={"OAuth 2.0: OAuth2Authentication"}
       value={"OAuth2Authentication"}
     >
-      
-      
+
+
       OAuth2 authentication supporting both authorization code flow and client credentials flow. For client credentials flow, include 'app_installation_id' parameter in the token request payload to receive a bot token for workspace app installations.
-      
+
       <div>
         <table>
           <tbody>
@@ -154,4 +152,3 @@ Visit our quick start guide and full API documentation at [developers.plane.so](
     GNU AGPLv3
   </a>
 </div>
-      
diff --git a/docs/intro.md b/docs/intro.md
@@ -28,7 +28,7 @@ import { CardGroup } from '@site/src/components/CardGroup';
   <Card title="Self-Hosting" icon="FaDocker" href="/self-hosting/overview">
     Learn how to self-host Plane.
   </Card>
-  <Card title="API Reference" icon="FaCog" href="/api/the-plane-rest-api">
+  <Card title="API Reference" icon="FaCog" href="/api/introduction">
     Use our API reference to build a custom integration.
   </Card>
   <Card title="Webhooks" icon="FaCog" href="/webhooks/overview">
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -339,7 +339,7 @@ const config: Config = {
         docsPluginId: 'classic', // configured for preset-classic
         config: {
           plane: {
-            specPath: 'api-spec/schema.yaml',
+            specPath: 'api/schema.yaml',
             outputDir: 'docs/api',
             sidebarOptions: {
               groupPathsBy: 'tag',
diff --git a/sidebars.ts b/sidebars.ts
@@ -3,6 +3,13 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
 import apiSidebar from './docs/api/sidebar.js';
 
+// Substitute our custom intro page b/c it's nicer than the generated one.
+const indexPage = apiSidebar[0]
+if (!(indexPage.type === 'doc' && indexPage.id === 'api/the-plane-rest-api')) {
+  throw new Error('Could not find API index page. Aborting.');
+}
+apiSidebar[0].id = 'api/introduction';
+
 const sidebars: SidebarsConfig = {
   sidebar: [
     {
