> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Equity plans API reference

> Create and manage equity incentive plans that define the authorized share pool for option grants, RSUs, and other equity awards for employees.

An equity plan (internally called a stock plan) defines a pool of shares reserved for equity compensation. Plans are associated with one or more share classes and track how many shares have been reserved versus how many remain available for future grants. You link individual securities — options, RSUs, and similar awards — to a plan when you issue them. Launchboard automatically adjusts `currentSharesReserved` as grants are issued and cancelled.

## Endpoints

| Method   | Path                        | Description                          |
| -------- | --------------------------- | ------------------------------------ |
| `GET`    | `/api/v1/equity-plans`      | List equity plans (cursor-paginated) |
| `POST`   | `/api/v1/equity-plans`      | Create an equity plan                |
| `GET`    | `/api/v1/equity-plans/{id}` | Get a single equity plan             |
| `PATCH`  | `/api/v1/equity-plans/{id}` | Partially update an equity plan      |
| `DELETE` | `/api/v1/equity-plans/{id}` | Delete an equity plan                |

***

## List equity plans

Returns a cursor-paginated list of all equity plans for your organization.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/equity-plans \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

### Query parameters

<ParamField path="query.limit" type="number" default="25">
  Maximum results per page. Capped at 100.
</ParamField>

<ParamField path="query.cursor" type="string">
  Opaque cursor from the previous response's `nextCursor` field.
</ParamField>

### Response

<ResponseField name="items" type="object[]">
  Array of equity plan objects.

  <Expandable title="Equity plan fields">
    <ResponseField name="id" type="string">UUID of the equity plan.</ResponseField>
    <ResponseField name="orgId" type="string">UUID of the owning organization.</ResponseField>
    <ResponseField name="name" type="string">Plan name (e.g., `"2020 Equity Incentive Plan"`).</ResponseField>
    <ResponseField name="planType" type="string">Plan type label (e.g., `"ISO"`, `"NSO"`, `"RSU"`).</ResponseField>
    <ResponseField name="initialSharesReserved" type="string">Shares reserved at plan adoption, as a decimal string.</ResponseField>
    <ResponseField name="currentSharesReserved" type="string">Current available share pool (adjusted as grants are issued and cancelled), as a decimal string.</ResponseField>
    <ResponseField name="stockClassIds" type="string[]">Array of share class UUIDs this plan draws from.</ResponseField>
    <ResponseField name="adoptedDate" type="string">Date the plan was adopted, in `YYYY-MM-DD` format.</ResponseField>
    <ResponseField name="expirationDate" type="string | null">Date the plan expires, in `YYYY-MM-DD` format.</ResponseField>
    <ResponseField name="comments" type="string | null">Free-text notes.</ResponseField>
    <ResponseField name="verificationStatus" type="string">`UNVERIFIED` or `VERIFIED`.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO-8601 timestamp with timezone offset.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO-8601 timestamp with timezone offset.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Cursor for the next page. `null` on the last page.
</ResponseField>

***

## Create an equity plan

Creates a new equity incentive plan. Supports the `Idempotency-Key` header for safe retries.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/equity-plans \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-2020-plan" \
    -d '{
      "planName": "2020 Equity Incentive Plan",
      "initialSharesReserved": "10000000",
      "stockClassIds": ["sc_common01"],
      "defaultCancellationBehavior": "RETURN_TO_POOL",
      "boardApprovalDate": "2020-06-01",
      "stockholderApprovalDate": "2020-06-15"
    }'
  ```
</CodeGroup>

### Request body

<ParamField body="planName" type="string" required>
  Human-readable name for the plan. Maximum 100 characters.
</ParamField>

<ParamField body="initialSharesReserved" type="string" required>
  Number of shares reserved in the pool at adoption, as a positive numeric string.
</ParamField>

<ParamField body="stockClassIds" type="string[]" default="[]">
  Array of share class UUIDs this plan draws from. Typically a single common stock class.
</ParamField>

<ParamField body="defaultCancellationBehavior" type="string" default="RETURN_TO_POOL">
  How cancelled grants are treated: `RETURN_TO_POOL` (shares revert to the available pool) or `RETIRE` (shares are permanently retired).
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Date the board approved the plan, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="stockholderApprovalDate" type="string">
  Date stockholders approved the plan, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="comments" type="string">
  Free-text notes. Maximum 2000 characters.
</ParamField>

<ParamField body="sourceDocumentId" type="string">
  UUID of the plan document to associate with this equity plan.
</ParamField>

### Response

Returns `201 Created` with the full equity plan object and a `Location` header.

***

## Get an equity plan

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/equity-plans/abc123 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

Returns the equity plan object. Field schema is identical to the list response items.

***

## Update an equity plan

Partial update — include only the fields you want to change.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/equity-plans/abc123 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "planName": "2020 Equity Incentive Plan (as Amended)",
      "initialSharesReserved": "15000000",
      "comments": "Pool increased by 5M shares per board resolution dated 2024-03-01."
    }'
  ```
</CodeGroup>

### Request body

All fields from the [create request body](#request-body-1) are accepted; all are optional for `PATCH`.

Returns `200 OK` with the updated equity plan object.

***

## Delete an equity plan

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://launchboard.xyz/api/v1/equity-plans/abc123 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

Returns `204 No Content` on success.

***

## Common errors

| Status | When it occurs                                                                                  |
| ------ | ----------------------------------------------------------------------------------------------- |
| `400`  | Malformed JSON in the request body.                                                             |
| `401`  | Missing or invalid `Authorization` header.                                                      |
| `403`  | The API key role does not have `EDITOR` permission. Required for `POST`, `PATCH`, and `DELETE`. |
| `404`  | No equity plan with the given `id` exists, or a referenced `stockClassId` does not exist.       |
| `422`  | Request body failed schema validation. The response includes a field-level `errors` array.      |

<Note>
  `currentSharesReserved` is computed automatically by Launchboard as grants are issued and cancelled. Do not attempt to set it directly — update `initialSharesReserved` instead to reflect a board-approved pool increase.
</Note>