# API Overview {#api-overview}


The Ever Gauzy API is a RESTful HTTP API built with NestJS. It provides comprehensive endpoints for all platform features, with auto-generated OpenAPI (Swagger) documentation.


## Base URL {#base-url}


| Environment           | API Base URL                    | Swagger UI                      | API Docs                        |
| --------------------- | ------------------------------- | ------------------------------- | ------------------------------- |
| **Local Development** | `http://localhost:3000/api`     | `http://localhost:3000/swg`     | `http://localhost:3000/docs`    |
| **Demo**              | `https://apidemo.gauzy.co/api`  | `https://apidemo.gauzy.co/swg`  | `https://apidemo.gauzy.co/docs` |
| **Staging**           | `https://apistage.gauzy.co/api` | `https://apistage.gauzy.co/swg` | —                               |
| **Production**        | `https://api.gauzy.co/api`      | `https://api.gauzy.co/swg`      | `https://api.gauzy.co/docs`     |

All endpoints are prefixed with `/api/`.


## Authentication {#authentication}


Most API endpoints require a valid JWT token. Obtain one via the login endpoint:

```bash
# Login
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@ever.co",
  "password": "admin"
}
```

Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "admin@ever.co",
    "tenantId": "...",
    "role": { "name": "SUPER_ADMIN" }
  }
}
```

Use the token in subsequent requests:

```bash
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```


### Public Endpoints {#public-endpoints}


Endpoints decorated with `@Public()` bypass authentication:

| Endpoint                        | Method | Purpose                  |
| ------------------------------- | ------ | ------------------------ |
| `/api/auth/login`               | POST   | User login               |
| `/api/auth/register`            | POST   | Public user registration |
| `/api/auth/reset-password`      | POST   | Password reset           |
| `/api/auth/request-password`    | POST   | Password reset request   |
| `/api/auth/{provider}/callback` | GET    | Social OAuth callbacks   |
| `/api/health`                   | GET    | Health check             |


## Request Format {#request-format}



### Content Type {#content-type}


All request and response bodies use JSON:

```
Content-Type: application/json
Accept: application/json
```


### Request Headers {#request-headers}


| Header            | Required             | Description                                 |
| ----------------- | -------------------- | ------------------------------------------- |
| `Authorization`   | Yes (most endpoints) | `Bearer {jwt_token}`                        |
| `Content-Type`    | Yes (POST/PUT/PATCH) | `application/json`                          |
| `Tenant-Id`       | Optional             | Override tenant for cross-tenant operations |
| `Organization-Id` | Optional             | Specify organization context                |
| `Language`        | Optional             | Preferred language for i18n responses       |


## Response Format {#response-format}



### Success Responses {#success-responses}


```json
// Single entity
{
  "id": "uuid",
  "name": "Example",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

// Paginated collection
{
  "items": [...],
  "total": 100
}
```


### Error Responses {#error-responses}


```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```


## HTTP Status Codes {#http-status-codes}


| Code  | Description           | When Used                       |
| ----- | --------------------- | ------------------------------- |
| `200` | OK                    | Successful GET, PUT, PATCH      |
| `201` | Created               | Successful POST                 |
| `204` | No Content            | Successful DELETE               |
| `400` | Bad Request           | Validation error, invalid input |
| `401` | Unauthorized          | Missing or invalid JWT token    |
| `403` | Forbidden             | Insufficient permissions        |
| `404` | Not Found             | Resource not found              |
| `409` | Conflict              | Duplicate resource              |
| `429` | Too Many Requests     | Rate limit exceeded             |
| `500` | Internal Server Error | Unexpected server error         |


## API Modules {#api-modules}


The API is organized into the following endpoint groups:


### Core {#core}


| Module                                       | Base Path           | Description                    |
| -------------------------------------------- | ------------------- | ------------------------------ |
| [Authentication](https://sourcey-gauzy.pages.dev/api/authentication-endpoints/index.md) | `/api/auth`         | Login, register, OAuth, tokens |
| [User](https://sourcey-gauzy.pages.dev/api/employee-endpoints/index.md)                 | `/api/user`         | User profile and settings      |
| [Employee](https://sourcey-gauzy.pages.dev/api/employee-endpoints/index.md)             | `/api/employee`     | Employee management            |
| [Organization](https://sourcey-gauzy.pages.dev/api/organization-endpoints/index.md)     | `/api/organization` | Organization CRUD              |


### HRM {#hrm}


| Module                                     | Base Path               | Description                       |
| ------------------------------------------ | ----------------------- | --------------------------------- |
| [Time Tracking](https://sourcey-gauzy.pages.dev/api/time-tracking-endpoints/index.md) | `/api/timesheet`        | Time logs, timesheets, activities |
| [Time Off](https://sourcey-gauzy.pages.dev/api/employee-endpoints/index.md)           | `/api/time-off-request` | Leave requests                    |
| [Employee Awards](https://sourcey-gauzy.pages.dev/api/employee-endpoints/index.md)    | `/api/employee-award`   | Employee awards                   |
| [Employee Levels](https://sourcey-gauzy.pages.dev/api/employee-endpoints/index.md)    | `/api/employee-level`   | Employee levels                   |


### ERP {#erp}


| Module                          | Base Path       | Description        |
| ------------------------------- | --------------- | ------------------ |
| [Invoices](https://sourcey-gauzy.pages.dev/api/invoice-endpoints/index.md) | `/api/invoices` | Invoice management |
| [Expenses](https://sourcey-gauzy.pages.dev/api/expense-endpoints/index.md) | `/api/expense`  | Expense tracking   |
| [Payments](https://sourcey-gauzy.pages.dev/api/invoice-endpoints/index.md) | `/api/payment`  | Payment records    |
| [Income](https://sourcey-gauzy.pages.dev/api/expense-endpoints/index.md)   | `/api/income`   | Income tracking    |


### PM {#pm}


| Module                          | Base Path                    | Description        |
| ------------------------------- | ---------------------------- | ------------------ |
| [Tasks](https://sourcey-gauzy.pages.dev/api/task-endpoints/index.md)       | `/api/tasks`                 | Task management    |
| [Projects](https://sourcey-gauzy.pages.dev/api/project-endpoints/index.md) | `/api/organization-projects` | Project management |
| [Sprints](https://sourcey-gauzy.pages.dev/api/project-endpoints/index.md)  | `/api/organization-sprint`   | Sprint management  |
| [Goals](https://sourcey-gauzy.pages.dev/api/task-endpoints/index.md)       | `/api/goals`                 | Goals and KPIs     |


### CRM {#crm}


| Module                             | Base Path                   | Description        |
| ---------------------------------- | --------------------------- | ------------------ |
| [Contacts](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md)  | `/api/organization-contact` | Contact management |
| [Pipelines](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md) | `/api/pipelines`            | Sales pipelines    |
| [Deals](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md)     | `/api/deals`                | Deal management    |


### ATS {#ats}


| Module                              | Base Path                  | Description                |
| ----------------------------------- | -------------------------- | -------------------------- |
| [Candidates](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md) | `/api/candidate`           | Candidate management       |
| [Interviews](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md) | `/api/candidate-interview` | Interview scheduling       |
| [Invite](https://sourcey-gauzy.pages.dev/api/candidate-endpoints/index.md)     | `/api/invite`              | User/candidate invitations |


### Integrations {#integrations}


| Module                                  | Base Path                  | Description            |
| --------------------------------------- | -------------------------- | ---------------------- |
| [Integrations](https://sourcey-gauzy.pages.dev/api/integration-endpoints/index.md) | `/api/integration`         | Integration management |
| [GitHub](https://sourcey-gauzy.pages.dev/api/integration-endpoints/index.md)       | `/api/integration/github`  | GitHub integration     |
| [Upwork](https://sourcey-gauzy.pages.dev/api/integration-endpoints/index.md)       | `/api/integrations/upwork` | Upwork integration     |


## Rate Limiting {#rate-limiting}


The API enforces rate limiting to prevent abuse:

```bash
# Default configuration
THROTTLE_ENABLED=true
THROTTLE_TTL=60000      # 1 minute window
THROTTLE_LIMIT=60000    # Max requests per window
```

When rate limited, the API returns `429 Too Many Requests`.


## CORS {#cors}


Cross-Origin Resource Sharing is configured to allow:

- Localhost ports (development)
- Production domains (`*.gauzy.co`, `*.ever.co`)
- Custom domains via CORS configuration


## Swagger / OpenAPI {#swagger--openapi}


The interactive Swagger UI at `/swg` allows you to:

1. Browse all available endpoints
2. View request/response schemas
3. Try endpoints directly (with authentication)
4. Download the OpenAPI spec as JSON (`/swg-json`)


### Importing into API Tools {#importing-into-api-tools}


- **Postman**: Import from `http://localhost:3000/swg-json`
- **Insomnia**: Import OpenAPI spec from Swagger JSON
- **VS Code REST Client**: Use Swagger-generated examples


## Related Pages {#related-pages}


- [REST API](https://sourcey-gauzy.pages.dev/api/rest-api/index.md) — detailed REST conventions
- [GraphQL API](https://sourcey-gauzy.pages.dev/api/graphql-api/index.md) — GraphQL endpoint
- [Pagination & Filtering](https://sourcey-gauzy.pages.dev/api/pagination-and-filtering/index.md) — query patterns
- [Error Handling](https://sourcey-gauzy.pages.dev/api/error-handling/index.md) — error response details
- [Authentication Endpoints](https://sourcey-gauzy.pages.dev/api/authentication-endpoints/index.md) — login and auth flows