API Overview

Vulcan exposes RESTful APIs through independent microservices. Each capability has its own API with consistent patterns.

Base URLs

Environment	Base URL
Production	https://api.vulcan.hantverksdata.se
Staging	https://api.staging.vulcan.hantverksdata.se
Local	http://localhost:5000

API Capabilities

Capability	Base Path	Description
Core Setup	/api/coresetup	Users, Groups, Settings
Leads	/api/leads	CRM, Leads, Customers
Quotation	/api/quotation	Quotes, Work packages
Contracts	/api/contracts	Contracts, E-signing
Projects	/api/projects	Projects, Timelines
Invoicing	/api/invoicing	Invoices, Payments
Documents	/api/documents	Document storage
AI	/api/ai	AI services, Embeddings
Planning	/api/planning	Planning, Scheduling

Response Format

All API responses follow a consistent envelope format:

{
  "data": { /* response payload */ },
  "error": null,
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "abc-123"
  }
}

Success Response

{
  "data": {
    "id": 1,
    "email": "user@example.com",
    "createdAt": "2026-01-01T00:00:00Z"
  },
  "error": null,
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "abc-123"
  }
}

Error Response

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Email already exists" }
    ]
  },
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "ghi-789"
  }
}

Paginated Response

{
  "data": [
    { "id": 1, "name": "Item 1" },
    { "id": 2, "name": "Item 2" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "xyz-789"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request (validation error)
401	Unauthorized (not authenticated)
403	Forbidden (not authorized)
404	Not Found
409	Conflict (resource already exists)
500	Internal Server Error

Common Headers

Request Headers

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
X-Request-ID: <unique-id>

Response Headers

Content-Type: application/json
X-Request-ID: <unique-id>
X-Response-Time: 45ms

Sections

• Authentication - Login, tokens, refresh
• Users - User management
• Leads - CRM and leads
• Quotation - Quotes and work packages