API Reference

This section documents the Anvil REST API for developers integrating with or extending the platform.

Base URL

Environment	URL
Production	https://api.anvil.app
Development	http://localhost:3001

Authentication

All API endpoints require authentication via JWT tokens:

Authorization: Bearer <your-jwt-token>

Additional headers for enhanced security:

• X-Session-ID - Session identifier
• X-Device-Fingerprint - Client device fingerprint

See Authentication for details on obtaining tokens.

Interactive Documentation

When running the Anvil server locally, interactive Swagger UI is available at:

http://localhost:3001/api/docs

You can:

• Browse all endpoints
• View request/response schemas
• Try out API calls directly
• Download OpenAPI specification

OpenAPI Specification

Download the full OpenAPI 3.0 specification:

• JSON: GET /api/docs/openapi.json
• YAML: GET /api/docs/openapi.yaml

API Sections

Core Resources

Section	Description
Authentication	Login, logout, MFA, sessions
Work Orders	Job/work order management
Tasks	Work order task management
Contacts	Client and vendor management

Operations

Section	Description
Time Tracking	Clock in/out, time entries
Inventory	Material catalog, stock levels
Payroll	Payroll periods and processing

Administration

Section	Description
Roles	Role and permission management
Users	User management
Organization	Organization settings

Common Patterns

Response Format

Successful responses:

{
  "ok": true,
  "data": { ... }
}

Error responses:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": { ... }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request (validation error)
401	Unauthorized (invalid/missing token)
403	Forbidden (insufficient permissions)
404	Not Found
429	Rate Limited
500	Internal Server Error

Pagination

List endpoints support pagination:

GET /api/work-orders?page=1&limit=20

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Filtering

Most list endpoints support filtering via query parameters:

GET /api/work-orders?status=pending&priority=high&employee_id=5

Multi-Tenancy

All data is automatically scoped to the authenticated user's organization. Cross-tenant access is blocked at multiple layers.

Superadmins can specify a target organization:

GET /api/work-orders?organization_id=123

Rate Limiting

User Type	Limit
Authenticated	100 requests/minute
Unauthenticated	20 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703001600

SDKs & Libraries

Currently available:

• JavaScript/TypeScript: Coming soon
• Python: Coming soon

For now, use any HTTP client with the REST API directly.

Support

• 📧 Email: api-support@simplexdev.app
• 🐛 Issues: GitHub Issues