Skip to main content
Source: Cross-reference guide — endpoint paths verified against equa-server/modules/api/src/endpoints/

​
SDK Guide

The Equa API is a standard REST API that can be consumed from any HTTP client. This guide covers common patterns using the browser fetch API.

​
Setup

Browser clients should use the same-origin API path exposed by the current SPA host: 
const API_BASE = '/api/v1'
If you need an absolute URL outside the browser, use https://app.equa.cc/api/v1 unless a direct API hostname has been freshly re-verified. Every request must include credentials: 'include' so the session cookie is sent automatically.

​
Helper Function

A reusable API helper simplifies repeated patterns: 
async function equaApi(path, options = {}) {
  const url = `${API_BASE}${path}`
  const response = await fetch(url, {
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
    ...options,
  })

  if (!response.ok) {
    const error = await response.json().catch(() => ({ error: response.statusText }))
    throw new Error(error.error || `HTTP ${response.status}`)
  }

  return response.json()
}

​
Authentication

​
Login

const user = await equaApi('/user/login', {
  method: 'POST',
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password',
  }),
})

console.log('Logged in as:', user.email)

​
Google OAuth Login

const user = await equaApi('/user/google-auth', {
  method: 'POST',
  body: JSON.stringify({
    token: googleIdToken,
  }),
})
Magic link endpoints (/user/magic-link and /user/magic-link/verify) are implemented in the auth module but not yet registered as REST endpoints. This example shows the planned usage.
// Step 1: Request magic link (planned)
await equaApi('/user/magic-link', {
  method: 'POST',
  body: JSON.stringify({ email: 'user@example.com' }),
})

// Step 2: Verify token from the email link (planned)
const user = await equaApi('/user/magic-link/verify', {
  method: 'POST',
  body: JSON.stringify({ token: tokenFromEmail }),
})

​
Get Current User

const currentUser = await equaApi('/user/current')

​
Logout

await equaApi('/user/logout', { method: 'POST' })

​
Organizations

​
List Organizations

const orgs = await equaApi('/organization')

​
Get Organization Details

const org = await equaApi(`/organization/${orgId}`)

​
Create Organization

const newOrg = await equaApi('/organization', {
  method: 'POST',
  body: JSON.stringify({
    name: 'My Company',
    type: 'corporation',
  }),
})

​
Cap Table

​
List Shareholdings

const shareholdings = await equaApi(`/organization/${orgId}/shareholding`)

​
Create a Shareholding

const shareholding = await equaApi(`/organization/${orgId}/shareholding`, {
  method: 'POST',
  body: JSON.stringify({
    member: memberId,
    security: securityId,
    shares: 10000,
    issueDate: '2025-01-15',
  }),
})

​
Get Securities

const securities = await equaApi(`/organization/${orgId}/security`)

​
Members

​
List Organization Members

const members = await equaApi(`/organization/${orgId}/member`)

​
Invite Members

await equaApi(`/organization/${orgId}/member/invite`, {
  method: 'POST',
  body: JSON.stringify({
    emails: ['alice@example.com', 'bob@example.com'],
  }),
})

​
Documents (Data Room)

​
List Documents

const docs = await equaApi(`/organization/${orgId}/document`)

​
Upload a Document

const formData = new FormData()
formData.append('file', fileInput.files[0])

const response = await fetch(`${API_BASE}/organization/${orgId}/document`, {
  method: 'POST',
  credentials: 'include',
  body: formData,
  // Do not set Content-Type header; the browser sets it with the boundary
})

​
Download a Document

const response = await fetch(
  `${API_BASE}/organization/${orgId}/document/${docId}/content`,
  { credentials: 'include' }
)
const blob = await response.blob()

​
Billing

​
Get Products

const products = await equaApi('/billing/product')

​
Get Organization Subscriptions

const subs = await equaApi(`/organization/${orgId}/subscription`)

​
Agent (Equanaut)

​
Chat with the Agent

const response = await equaApi('/agent/chat', {
  method: 'POST',
  body: JSON.stringify({
    organization: orgId,
    message: 'How many shareholders does this company have?',
    conversationId: conversationId,
  }),
})

​
Error Handling

See Error Codes for the complete list of status codes. A common pattern: 
try {
  const data = await equaApi('/organization')
  // handle success
} catch (err) {
  if (err.message.includes('401')) {
    // Session expired, redirect to login
  } else {
    // Display error to user
    console.error('API error:', err.message)
  }
}