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

# Share classes API reference

> Create and manage common and preferred stock classes on your cap table, with built-in on-chain tokenization to Solana for each share class.

Share classes define the authorized share structures on your cap table — common stock for founders and employees, and preferred stock for investors. Each class carries attributes such as votes per share, par value, liquidation preference, and participation rights. When you create or update a share class on Launchboard, the platform asynchronously tokenizes it on-chain via the OASIS protocol. You can poll `tokenizationStatus` to track progress, and use the retokenize endpoint to retry a failed attempt.

## Endpoints

| Method   | Path                                    | Description                           |
| -------- | --------------------------------------- | ------------------------------------- |
| `GET`    | `/api/v1/share-classes`                 | List share classes (cursor-paginated) |
| `POST`   | `/api/v1/share-classes`                 | Create a share class                  |
| `GET`    | `/api/v1/share-classes/{id}`            | Get a single share class              |
| `PATCH`  | `/api/v1/share-classes/{id}`            | Partially update a share class        |
| `DELETE` | `/api/v1/share-classes/{id}`            | Delete a share class                  |
| `POST`   | `/api/v1/share-classes/{id}/retokenize` | Retry failed OASIS tokenization       |

***

## List share classes

Returns a cursor-paginated list of all share classes for your organization. Filter by `classType` to narrow results to common or preferred stock.

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

  ```bash Filter by class type theme={null}
  curl "https://launchboard.xyz/api/v1/share-classes?classType=PREFERRED" \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

### Query parameters

<ParamField path="query.classType" type="string">
  Filter to `COMMON` or `PREFERRED` stock classes only.
</ParamField>

<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 share class objects.

  <Expandable title="Share class fields">
    <ResponseField name="id" type="string">UUID of the share class.</ResponseField>
    <ResponseField name="orgId" type="string">UUID of the owning organization.</ResponseField>
    <ResponseField name="name" type="string">Human-readable name (e.g., `"Series A Preferred"`).</ResponseField>
    <ResponseField name="classType" type="string">`COMMON` or `PREFERRED`.</ResponseField>
    <ResponseField name="defaultIdPrefix" type="string">Prefix used when auto-generating certificate IDs for securities in this class.</ResponseField>
    <ResponseField name="initialSharesAuthorized" type="string">Total shares authorized at creation, as a decimal string.</ResponseField>
    <ResponseField name="currentSharesAuthorized" type="string">Current authorized share count (may change after amendments), as a decimal string.</ResponseField>
    <ResponseField name="votesPerShare" type="string">Votes each share carries, as a decimal string.</ResponseField>
    <ResponseField name="parValue" type="string | null">Par value per share, as a decimal string.</ResponseField>
    <ResponseField name="seniority" type="number">Liquidation seniority rank. Lower numbers are senior. Integers only.</ResponseField>
    <ResponseField name="liquidationPreferenceMultiple" type="string | null">Liquidation preference multiplier, as a decimal string.</ResponseField>
    <ResponseField name="participationCapMultiple" type="string | null">Cap on participation rights, as a decimal string.</ResponseField>
    <ResponseField name="isParticipating" type="boolean">Whether preferred holders participate beyond their liquidation preference.</ResponseField>
    <ResponseField name="tokenizationStatus" type="string">`NOT_STARTED`, `PENDING`, `DEPLOYED`, or `FAILED`.</ResponseField>
    <ResponseField name="tokenAddress" type="string | null">On-chain contract address once tokenization reaches `DEPLOYED`.</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 a share class

Creates a new share class. OASIS tokenization starts automatically in the background — the class is immediately available in Launchboard but its `tokenizationStatus` will transition from `NOT_STARTED` → `PENDING` → `DEPLOYED` (or `FAILED`) asynchronously over \~60–90 seconds.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/share-classes \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-series-a-2024" \
    -d '{
      "name": "Series A Preferred",
      "classType": "PREFERRED",
      "defaultIdPrefix": "PS-A",
      "initialSharesAuthorized": "10000000",
      "votesPerShare": "1",
      "seniority": 1,
      "parValue": "0.0001",
      "liquidationPreferenceMultiple": "1",
      "isParticipating": false
    }'
  ```
</CodeGroup>

### Request body

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

<ParamField body="classType" type="string" required>
  `COMMON` or `PREFERRED`.
</ParamField>

<ParamField body="defaultIdPrefix" type="string" required>
  Prefix for auto-generated certificate IDs. Maximum 20 characters (e.g., `"CS"`, `"PS-A"`).
</ParamField>

<ParamField body="initialSharesAuthorized" type="string" required>
  Number of authorized shares as a numeric string (e.g., `"10000000"`).
</ParamField>

<ParamField body="votesPerShare" type="string" required>
  Votes per share as a numeric string. Use `"0"` for non-voting shares.
</ParamField>

<ParamField body="seniority" type="number" required>
  Liquidation seniority rank. Must be a positive integer. `1` is the most senior.
</ParamField>

<ParamField body="parValue" type="string">
  Par value per share as a numeric string (e.g., `"0.0001"`).
</ParamField>

<ParamField body="pricePerShare" type="string">
  Issuance price per share as a numeric string.
</ParamField>

<ParamField body="liquidationPreferenceMultiple" type="string">
  Liquidation preference multiplier (e.g., `"1"` for 1×). Preferred classes only.
</ParamField>

<ParamField body="participationCapMultiple" type="string">
  Cap on participation beyond the liquidation preference, as a numeric string.
</ParamField>

<ParamField body="isParticipating" type="boolean" default="false">
  Whether preferred holders also participate in residual distributions.
</ParamField>

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

<ParamField body="stockholderApprovalDate" type="string">
  Date stockholders approved this class, 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 a source document to link to this share class.
</ParamField>

### Response

Returns `201 Created` with the full share class object and a `Location` header.

<Tip>
  Poll `GET /api/v1/share-classes/{id}` and check `tokenizationStatus` to determine when the on-chain contract is live. The transition from `PENDING` to `DEPLOYED` typically takes 60–90 seconds.
</Tip>

***

## Get a share class

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

Returns the share class object. Field schema is identical to the list response items.

***

## Update a share class

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/share-classes/abc123 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Series A-1 Preferred",
      "comments": "Amended after Series A-1 close."
    }'
  ```
</CodeGroup>

### Request body

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

Returns `200 OK` with the updated share class object.

***

## Delete a share class

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

Returns `204 No Content` on success.

<Warning>
  This request fails with `409 Conflict` if the share class has active securities or issued shares. Cancel or transfer those securities before deleting the class.
</Warning>

***

## Retry tokenization

Use this endpoint to retry OASIS tokenization for a share class whose previous attempt failed (`tokenizationStatus: "FAILED"`). The status transitions to `PENDING` immediately and the background mint job restarts.

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

Returns `200 OK` with the updated share class object (status will be `PENDING`). Poll `GET /api/v1/share-classes/{id}` to track progress.

***

## 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 write operations.         |
| `404`  | No share class with the given `id` exists in your organization.                            |
| `409`  | Delete attempted on a class with active securities or issued shares.                       |
| `422`  | Request body failed schema validation. The response includes a field-level `errors` array. |