---
title: "REST API Reference"
description: "Complete endpoint reference for the OpenCap Stack REST API"
canonical: "https://docs.ainative.studio/docs/opencapstack/rest-api"
last-updated: "2026-10-03T21:47:10.764Z"
---

# REST API Reference

Source: https://docs.ainative.studio/docs/opencapstack/rest-api

> Complete endpoint reference for the OpenCap Stack REST API

# REST API Reference

**Base URL:** `https://api.opencapstack.com/api/v1`  
**OpenAPI Spec:** [`/openapi.json`](https://api.opencapstack.com/openapi.json)  
**Interactive Docs:** [`/api-docs`](https://api.opencapstack.com/api-docs) (Swagger UI)

All requests require:
```
Authorization: Bearer <token>
Content-Type: application/json
```

---

## Authentication

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/auth/register` | Create account, returns JWT |
| `POST` | `/auth/login` | Email/password login |
| `POST` | `/auth/ainative-login` | AINative SSO login (server-side) |
| `POST` | `/auth/refresh` | Refresh JWT using refresh token |
| `POST` | `/agents/onboard` | Zero-friction agent registration |
| `GET` | `/auth/me` | Get current user profile |

---

## Stakeholders

Cap table participants — founders, investors, employees, advisors.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/stakeholders` | List all stakeholders |
| `POST` | `/stakeholders` | Create a stakeholder |
| `GET` | `/stakeholders/:id` | Get stakeholder by ID |
| `PUT` | `/stakeholders/:id` | Update stakeholder |
| `DELETE` | `/stakeholders/:id` | Delete stakeholder |

### Create a Stakeholder

```bash
curl -X POST https://api.opencapstack.com/api/v1/stakeholders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@startup.com",
    "type": "EMPLOYEE",
    "title": "CTO"
  }'
```

**Stakeholder types:** `FOUNDER` `INVESTOR` `EMPLOYEE` `ADVISOR` `BOARD_MEMBER`

**Response:**
```json
{
  "id": "stakeholder_abc123",
  "name": "Jane Doe",
  "email": "jane@startup.com",
  "type": "EMPLOYEE",
  "title": "CTO",
  "companyId": "co_xyz789",
  "createdAt": "2026-05-13T00:00:00Z"
}
```

---

## Share Classes

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/share-classes` | List all share classes |
| `POST` | `/share-classes` | Create a share class |
| `GET` | `/share-classes/:id` | Get share class by ID |
| `PUT` | `/share-classes/:id` | Update share class |

### Create a Share Class

```bash
curl -X POST https://api.opencapstack.com/api/v1/share-classes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Series A Preferred",
    "type": "PREFERRED",
    "totalShares": 10000000,
    "pricePerShare": 1.00,
    "liquidationPreference": 1.0,
    "conversionRatio": 1.0
  }'
```

**Share class types:** `COMMON` `PREFERRED` `OPTIONS_POOL` `WARRANT`

---

## Equity Grants

Stock options, RSUs, and warrants issued to stakeholders.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/equity-grants` | List all grants |
| `POST` | `/equity-grants` | Issue a new grant |
| `GET` | `/equity-grants/:id` | Get grant by ID |
| `PUT` | `/equity-grants/:id` | Update grant |
| `GET` | `/equity-grants/:id/vesting` | Get vesting schedule |

### Issue an Equity Grant

```bash
curl -X POST https://api.opencapstack.com/api/v1/equity-grants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stakeholderId": "stakeholder_abc123",
    "shareClassId": "sc_options_pool",
    "quantity": 100000,
    "grantType": "OPTION",
    "strikePrice": 0.10,
    "vestingSchedule": "4_YEAR_1_YEAR_CLIFF",
    "grantDate": "2026-05-13"
  }'
```

**Grant types:** `OPTION` `RSU` `WARRANT` `RESTRICTED_STOCK`

**Vesting schedules:** `4_YEAR_1_YEAR_CLIFF` `3_YEAR_MONTHLY` `IMMEDIATE` `CUSTOM`

**Response:**
```json
{
  "id": "grant_def456",
  "grantNumber": "GRANT-MP34648T-FF2DB6F9",
  "stakeholderId": "stakeholder_abc123",
  "quantity": 100000,
  "grantType": "OPTION",
  "strikePrice": 0.10,
  "status": "PENDING",
  "vestingStartDate": "2026-05-13",
  "fullyVestedDate": "2030-05-13"
}
```

---

## SAFE Notes

Simple Agreements for Future Equity.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/safes` | List all SAFEs |
| `POST` | `/safes` | Create a SAFE |
| `GET` | `/safes/:id` | Get SAFE by ID |
| `PUT` | `/safes/:id` | Update SAFE |

### Create a SAFE

```bash
curl -X POST https://api.opencapstack.com/api/v1/safes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "investorId": "stakeholder_investor1",
    "investmentAmount": 500000,
    "valuationCap": 10000000,
    "discountRate": 0.20,
    "safeType": "POST_MONEY",
    "issueDate": "2026-05-13"
  }'
```

**SAFE types:** `PRE_MONEY` `POST_MONEY` `MFN`

---

## 409A Valuations

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/valuations` | List valuations |
| `POST` | `/valuations` | Request a new 409A valuation |
| `GET` | `/valuations/latest` | Get most recent valuation |
| `GET` | `/valuations/:id` | Get valuation by ID |

### Request a Valuation

```bash
curl -X POST https://api.opencapstack.com/api/v1/valuations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "valuationDate": "2026-05-13",
    "methodology": "INCOME_APPROACH",
    "notes": "Pre-Series A valuation"
  }'
```

---

## Cap Table

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/cap-table` | Full cap table summary |
| `GET` | `/cap-table/fully-diluted` | Fully diluted share count |
| `POST` | `/cap-table/dilution` | Model dilution for a new round |
| `POST` | `/cap-table/waterfall` | Run liquidation waterfall analysis |

### Cap Table Summary

```bash
curl https://api.opencapstack.com/api/v1/cap-table \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "companyId": "co_xyz789",
  "asOfDate": "2026-05-13",
  "totalAuthorizedShares": 20000000,
  "totalIssuedShares": 12500000,
  "fullyDilutedShares": 14000000,
  "shareClasses": [
    {
      "name": "Common Stock",
      "shares": 8000000,
      "ownership": 0.571
    },
    {
      "name": "Series A Preferred",
      "shares": 4500000,
      "ownership": 0.321
    }
  ],
  "topStakeholders": [
    { "name": "Jane Doe (Founder)", "shares": 5000000, "ownership": 0.357 },
    { "name": "Acme Ventures", "shares": 4500000, "ownership": 0.321 }
  ]
}
```

### Dilution Modeling

```bash
curl -X POST https://api.opencapstack.com/api/v1/cap-table/dilution \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roundSize": 5000000,
    "preMoneyValuation": 20000000,
    "newShareClassName": "Series B Preferred"
  }'
```

---

## Documents

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/documents` | List documents |
| `POST` | `/documents` | Upload a document |
| `GET` | `/documents/:id` | Get document metadata |
| `GET` | `/documents/:id/download` | Download document |
| `DELETE` | `/documents/:id` | Delete document |

### Upload a Document

```bash
curl -X POST https://api.opencapstack.com/api/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@grant_agreement.pdf" \
  -F "type=GRANT_AGREEMENT" \
  -F "stakeholderId=stakeholder_abc123" \
  -F "grantId=grant_def456"
```

---

## Financial Reports

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/financial-reports` | List reports |
| `POST` | `/financial-reports` | Generate a report |
| `GET` | `/financial-reports/:id` | Get report |

### Generate an Investor Report

```bash
curl -X POST https://api.opencapstack.com/api/v1/financial-reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INVESTOR_UPDATE",
    "format": "json",
    "asOfDate": "2026-05-13"
  }'
```

**Report types:** `INVESTOR_UPDATE` `CAP_TABLE_SUMMARY` `EQUITY_LEDGER` `TAX_SUMMARY` `AUDIT_READY`

---

## Pagination

All list endpoints support cursor-based pagination:

```bash
GET /api/v1/stakeholders?page=1&limit=50
```

**Response envelope:**
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 142,
    "hasMore": true
  }
}
```

---

## Error Codes

| Status | Code | Meaning |
|--------|------|---------|
| `400` | `VALIDATION_ERROR` | Invalid request body |
| `401` | `UNAUTHORIZED` | Missing or expired token |
| `403` | `FORBIDDEN` | Valid token but insufficient scope |
| `404` | `NOT_FOUND` | Resource does not exist |
| `409` | `CONFLICT` | Duplicate resource (e.g. same email) |
| `429` | `RATE_LIMITED` | Too many requests — see [rate limits](#rate-limits) |
| `500` | `INTERNAL_ERROR` | Server error |

**Error response shape:**
```json
{
  "error": "VALIDATION_ERROR",
  "message": "stakeholderId is required",
  "field": "stakeholderId",
  "statusCode": 400
}
```

---

## Rate Limits

| Plan | API calls/month | Burst |
|------|:--------------:|:-----:|
| Free | 1,000 | 10/min |
| Starter | 10,000 | 60/min |
| Professional | 100,000 | 300/min |
| Enterprise | Unlimited | 1,000/min |

Rate limit headers are included on every response:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1715000000
```