Skip to content

API Reference — dot-cOS

  • Base URL: https://cos-api.dotevolve.net/api/v1
  • Auth: Authorization: Bearer <supabase_jwt>
  • Tenant context: Resolved from JWT app_metadata.activeTenantId — no separate tenant header needed from the client

Standard Response Format

{ "status": "success", "data": { ... } }
{ "status": "error", "message": "Human readable description" }

Public Endpoints (No Auth)

Method Path Description
GET /plans List subscription plans
POST /tenants/signup Self-signup — create tenant + user atomically
GET /mca/form-mappings MCA form field mappings (used by browser extension)
GET /health Health check

Tenant Endpoints

Method Path Auth Description
GET /tenants super-admin List all tenants
POST /tenants super-admin Create tenant
GET /tenants/:id admin Get single tenant
PATCH /tenants/:id super-admin Update tenant

Entity Endpoints

All routes require authentication. All queries are tenant-scoped.

Method Path Description
GET /entities List all entities for the active tenant
POST /entities Create an entity
GET /entities/:id Get a single entity
PATCH /entities/:id Update entity profile data
DELETE /entities/:id Delete an entity

Entity Object

{
  "id": "uuid",
  "tenantId": "uuid",
  "name": "Acme Corp Pvt Ltd",
  "registrationNumber": "U72900MH2023PTC123456",
  "industry": "Technology",
  "profileData": {
    "cin": "U72900MH2023PTC123456",
    "pan": "ABCDE1234F",
    "registeredAddress": "...",
    "authorizedCapital": "1000000",
    "directors": [...]
  }
}

Workflow Template Endpoints

Method Path Description
GET /workflows/templates List all templates (global + tenant-specific)
GET /workflows/templates/:id Get a single template
POST /workflows/templates Create a tenant-specific template

Workflow Instance Endpoints

Method Path Description
GET /workflows List all workflow instances for the active tenant
POST /workflows Create a workflow instance from a template
GET /workflows/:id Get a single workflow instance with current state
PATCH /workflows/:id Update workflow state (complete a task, advance a phase)
DELETE /workflows/:id Delete a workflow instance

Create Workflow Instance

{
  "templateId": "uuid",
  "entityId": "uuid",
  "financialYear": "2024-2025",
  "customLabel": "AGM 2024"
}

Document Template Endpoints

Method Path Description
GET /document-templates List all document templates
GET /document-templates/:id Get a single template
POST /documents/generate Generate a document from a template

Generate Document

{
  "templateId": "uuid",
  "entityId": "uuid",
  "variables": {
    "directorName": "John Smith",
    "appointmentDate": "2024-04-01"
  }
}

MCA Form Mapping Endpoints

Method Path Description
GET /mca/form-mappings List all form mappings (public)
GET /mca/form-mappings/:formType Get mapping for a specific form
POST /mca/autofill Generate autofill data for a form + entity

Audit Log Endpoints

Method Path Description
GET /audit List audit log entries for the active tenant
GET /audit/:workflowId Audit trail for a specific workflow instance

Error Codes

Status Meaning
401 Missing or invalid JWT, or no activeTenantId in JWT
402 Tenant status is pending_payment
403 Tenant status is suspended, or insufficient role
404 Resource not found
409 Conflict (duplicate)
500 Internal server error