Skip to main content

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.

A security represents a single equity instrument issued to a stakeholder. Launchboard supports four security types: STOCK (direct share ownership), STOCK_OPTION (the right to purchase shares at a fixed exercise price), WARRANT (similar to options but typically issued to investors or service providers), and CONVERTIBLE (instruments that convert to equity on a future event such as a priced round). Each security links a stakeholder, a share class or equity plan, optional vesting terms, and a valuation.

​
Endpoints

MethodPathDescription
GET/api/v1/securitiesList securities (cursor-paginated)
POST/api/v1/securitiesIssue a new security
GET/api/v1/securities/{id}Get a single security
PATCH/api/v1/securities/{id}Partially update a security
DELETE/api/v1/securities/{id}Delete a security

​
List securities

Returns a cursor-paginated list of securities for your organization. Filter by security type or stakeholderId to narrow results. 
curl https://launchboard.xyz/api/v1/securities \
  -H "Authorization: Bearer pg_live_your_key"

​
Query parameters

​
query.type
string
Filter by security type. One of STOCK, STOCK_OPTION, WARRANT, or CONVERTIBLE.
​
query.stakeholderId
string
Return only securities belonging to this stakeholder UUID.
​
query.limit
number
default:"25"
Maximum results per page. Capped at 100.
​
query.cursor
string
Opaque cursor from the previous response’s nextCursor field.

​
Response

​
items
object[]
Array of security objects.
​
nextCursor
string | null
Cursor for the next page. null on the last page.

​
Issue a security

Creates a new security and records the issuance on the cap table ledger. Supports the Idempotency-Key header for safe retries. 
curl -X POST https://launchboard.xyz/api/v1/securities \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: grant-abc123-2024" \
  -d '{
    "certificateId": "OPT-0042",
    "type": "STOCK_OPTION",
    "status": "ACTIVE",
    "stakeholderId": "stk_abc123",
    "stockClassId": "sc_common01",
    "stockPlanId": "ep_2020plan",
    "quantity": "50000",
    "exercisePrice": "1.25",
    "optionType": "ISO",
    "grantDate": "2024-01-15",
    "expirationDate": "2034-01-15",
    "vestingTermsId": "vt_4yr1yr"
  }'

​
Request body

​
certificateId
string
required
Your internal certificate or grant identifier. Maximum 50 characters (e.g., "CS-0001", "OPT-0042").
​
type
string
required
Security type: STOCK, STOCK_OPTION, WARRANT, or CONVERTIBLE.
​
status
string
default:"ACTIVE"
Initial lifecycle status. One of ACTIVE, CANCELLED, EXERCISED, CONVERTED, REPURCHASED, TRANSFERRED.
​
stakeholderId
string
required
UUID of the stakeholder receiving this security.
​
stockClassId
string
UUID of the share class this security belongs to.
​
stockPlanId
string
UUID of the equity plan this security is issued under. Required for options and RSUs.
​
quantity
string
required
Number of shares or units as a positive numeric string.
​
pricePerShare
string
Per-share price at issuance, as a numeric string.
​
exercisePrice
string
Strike price for options and warrants, as a numeric string.
​
totalConsideration
string
Total purchase price paid, as a numeric string.
​
optionType
string
Option tax treatment: ISO (incentive) or NSO (non-qualified). Required when type is STOCK_OPTION.
​
grantDate
string
required
Date the security was granted, in YYYY-MM-DD format.
​
expirationDate
string
Expiry date for options and warrants, in YYYY-MM-DD format.
​
vestingTermsId
string
UUID of the vesting terms to apply.
​
vestingStartDate
string
Vesting commencement date, in YYYY-MM-DD format. Defaults to grantDate if omitted.
​
valuationId
string
UUID of the 409A or board valuation in effect at grant date.
​
boardApprovalDate
string
Date the board approved this grant, in YYYY-MM-DD format.
​
comments
string
Free-text notes. Maximum 2000 characters.
​
sourceDocumentId
string
UUID of the grant agreement or other source document.

​
Response

Returns 201 Created with the full security object and a Location header.

​
Get a security

curl https://launchboard.xyz/api/v1/securities/abc123 \
  -H "Authorization: Bearer pg_live_your_key"
Returns the security object. Field schema is identical to the list response items.

​
Update a security

Partial update — include only the fields you want to change. 
curl -X PATCH https://launchboard.xyz/api/v1/securities/abc123 \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CANCELLED",
    "comments": "Cancelled upon employee departure."
  }'

​
Request body

All fields from the create request body are accepted (except sourceDocumentId); all are optional for PATCH. Returns 200 OK with the updated security object.

​
Delete a security

curl -X DELETE https://launchboard.xyz/api/v1/securities/abc123 \
  -H "Authorization: Bearer pg_live_your_key"
Returns 204 No Content on success.

​
Common errors

StatusWhen it occurs
400Malformed JSON in the request body.
401Missing or invalid Authorization header.
403The API key role does not have EDITOR permission. Required for POST, PATCH, and DELETE.
404No security with the given id exists, or a referenced stakeholderId, stockClassId, or stockPlanId does not exist.
422Request body failed schema validation. The response includes a field-level errors array.
Decimal amounts (quantity, pricePerShare, exercisePrice, etc.) are always serialized as strings in both requests and responses to preserve numeric precision.