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.

Approvals are governance records that capture the decision chain required before a cap table action is finalized. Every approval moves through a defined lifecycle: it starts as a Draft, is submitted for review (Submitted), advances as each step is decided (Approved once all steps pass), and is finally locked (Locked) to make it immutable. An approval must be in the Locked state before it can gate token minting through the Securities table. You can attach multiple sequential steps to an approval — for example, a legal review step followed by a board vote step. Each step carries its own PENDING → APPROVED / REJECTED status. The parent approval transitions to Approved only when every step resolves to APPROVED.

​
List approvals

Returns a cursor-paginated list of approval requests for your organization. Filter by status or entityType to narrow results. GET /api/v1/approvals
Query paramTypeDescription
statusstringFilter by status: Draft, Submitted, Approved, Rejected, or Locked.
entityTypestringFilter by entity type (e.g. Stock Issuance, Option Grant).
limitintegerPage size. Defaults to 25, maximum 100.
cursorstringOpaque cursor from the previous page’s nextCursor.
curl "https://launchboard.xyz/api/v1/approvals?status=Approved" \
  -H "Authorization: Bearer pg_live_your_key"
Response 
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440050",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Series A — common stock issuance to Alice Chen",
      "entityType": "Stock Issuance",
      "state": "Approved",
      "dueDate": "2024-03-31",
      "notes": "Board approved at March meeting.",
      "lockedAt": null,
      "createdAt": "2024-03-01T09:00:00.000Z",
      "updatedAt": "2024-03-15T16:00:00.000Z"
    }
  ],
  "nextCursor": null
}

​
Create an approval

Creates a new approval request in Draft state. You can optionally provide initial steps in the same request. POST /api/v1/approvals Requires role: EDITOR. Idempotent with an Idempotency-Key header.
​
title
string
required
Human-readable title for the approval (e.g. "Q1 option grants — engineering cohort"). Maximum 200 characters.
​
entityType
string
required
The type of equity event this approval covers. One of: Stock Issuance, Option Grant, RSU Grant, Warrant Issuance, Convertible Issuance, Stock Transfer, Exercise, Conversion, Cancellation, Repurchase, Valuation, Equity Plan, Stock Split, Other.
​
dueDate
string
Deadline for completing this approval (YYYY-MM-DD).
​
notes
string
Free-text context or instructions. Maximum 2000 characters.
​
steps
array
Initial steps to create alongside the approval. Each element requires a name (string, max 100 chars). Steps can also be added later via POST /approvals/{id}/steps.
curl -X POST https://launchboard.xyz/api/v1/approvals \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approval-series-a-issuance-2024" \
  -d '{
    "title": "Series A — common stock issuance to Alice Chen",
    "entityType": "Stock Issuance",
    "dueDate": "2024-03-31",
    "notes": "Requires legal review and board vote.",
    "steps": [
      { "name": "Legal review" },
      { "name": "Board vote" }
    ]
  }'
Response — 201 Created 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440050",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Series A — common stock issuance to Alice Chen",
    "state": "Draft",
    "lockedAt": null,
    "createdAt": "2024-03-01T09:00:00.000Z",
    "updatedAt": "2024-03-01T09:00:00.000Z"
  }
}

​
Get an approval

Retrieves a single approval by ID. GET /api/v1/approvals/{id} Requires role: VIEWER. 
curl https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050 \
  -H "Authorization: Bearer pg_live_your_key"

​
Update an approval

Updates a Draft approval’s metadata. You cannot update an approval that has been submitted or locked. PATCH /api/v1/approvals/{id} Requires role: EDITOR. Returns 409 Conflict if the approval is not in Draft state.
​
title
string
Updated title. Maximum 200 characters.
​
entityType
string
Updated entity type.
​
dueDate
string
Updated deadline (YYYY-MM-DD).
​
notes
string
Updated notes. Maximum 2000 characters.
curl -X PATCH https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050 \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2024-04-15",
    "notes": "Extended deadline — awaiting legal sign-off."
  }'

​
Delete an approval

Permanently deletes a Draft approval and all its steps. Returns 409 Conflict if the approval has been submitted. DELETE /api/v1/approvals/{id} Requires role: EDITOR. 
curl -X DELETE https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050 \
  -H "Authorization: Bearer pg_live_your_key"
Response — 204 No Content

​
Submit for review

Moves a Draft approval to Submitted, signalling that it is ready for step decisions. Returns 409 Conflict if the approval is already past Draft state. POST /api/v1/approvals/{id}/submit Requires role: EDITOR. No request body. 
curl -X POST https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050/submit \
  -H "Authorization: Bearer pg_live_your_key"
Response — 200 OK Returns the updated approval object with state: "Submitted".

​
Add a step

Appends a new approval step to an existing approval. Steps can only be added while the approval is in Draft or Submitted state. POST /api/v1/approvals/{id}/steps Requires role: EDITOR. Returns 409 Conflict if the approval is locked.
​
name
string
required
Display name for the step (e.g. "CFO sign-off"). Maximum 100 characters.
curl -X POST https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050/steps \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CFO sign-off"
  }'
Response — 201 Created 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440060",
    "approvalId": "550e8400-e29b-41d4-a716-446655440050",
    "status": "PENDING",
    "order": 3,
    "decidedAt": null,
    "comment": null,
    "createdAt": "2024-03-02T11:00:00.000Z"
  }
}
​
data.id
string (uuid)
Unique step ID. Reference this as {stepId} when updating or deleting the step.
​
data.status
string
PENDING, APPROVED, or REJECTED.
​
data.order
integer
1-based position of this step in the approval sequence.

​
Lock an approval

Locks an Approved approval, making it immutable and eligible to gate token minting. Returns 409 Conflict if the approval is not in Approved state (i.e. all steps must be approved first). POST /api/v1/approvals/{id}/lock Requires role: EDITOR. No request body. 
curl -X POST https://launchboard.xyz/api/v1/approvals/550e8400-e29b-41d4-a716-446655440050/lock \
  -H "Authorization: Bearer pg_live_your_key"
Response — 200 OK Returns the updated approval object with state: "Locked" and lockedAt set to the current timestamp.
Locking is irreversible. Once an approval is Locked, its state and steps cannot be modified. Create a new approval if you need to re-authorize the same action.

​
Approval lifecycle

The diagram below shows the valid state transitions:
From stateTransitionTo state
DraftPOST /{id}/submitSubmitted
SubmittedAll steps approvedApproved
SubmittedAny step rejectedRejected
ApprovedPOST /{id}/lockLocked
An approval must reach Locked status before it can authorize token minting in the Securities table. Approvals in Draft, Submitted, or Approved state are not yet eligible.

​
Error codes

StatusWhen it occurs
401Missing or invalid API key.
403Key role is below the required level.
404Approval or step not found, or does not belong to your organization.
409State transition is not permitted (e.g. trying to submit a Locked approval, or delete a non-Draft approval).
422Request body failed validation.