# WebWork Tracker REST API V2 Documentation

## Welcome to WebWork Tracker REST API V2

WebWork Tracker REST API V2 provides programmatic access to your workspace data, allowing you to integrate WebWork Tracker functionality into your own applications, scripts, and workflows. This is the official, current version of the WebWork Tracker REST API.

## What is the REST API V2?

The REST API V2 is a modern, RESTful API that enables you to:

- **Manage Workspaces** - Access and manage workspace information
- **Manage Members** - Invite, update, and manage team members
- **Manage Projects** - Create, update, and organize projects
- **Manage Tasks** - Create and manage tasks within projects
- **Manage Project Viewers** - Manage project viewers (clients) with read-only access to specific projects
- **Manage Contracts** - Handle project-member assignments with rates, hours limits, and screenshot modes
- **Track Time** - Start, stop, and manage time entries
- **Manage Timesheets** - View, approve, reject, submit, and unsubmit timesheets
- **Manage Time Requests** - Create, approve, and reject manual time requests
- **Manage Leaves** - Handle leave requests, view leave balances and policies
- **Manage Expenses** - Track and manage expenses and expense categories
- **Manage Webhooks** - Register callback URLs to receive real-time event notifications from the platform
- **Generate Reports** - Retrieve tracked hours, timeline, activity descriptions, tasks, and activity level reports


## API Overview

### Base URL

All API requests should be made to:

- **Production**: `https://api.webwork-tracker.com/api/v2`


**Important:** All endpoints use the `/api/v2/` prefix. For example:

- `/api/v2/workspaces`
- `/api/v2/projects`
- `/api/v2/members`


### Response Format

All API responses are in **JSON format** and follow a consistent structure:


```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "api_version": "2.0.0",
    "timestamp": "2024-01-15T10:30:00Z",
    "pagination": { ... }
  }
}
```

### HTTP Methods

The API uses standard HTTP methods:

- **GET** - Retrieve resources
- **POST** - Create new resources
- **PUT** - Update existing resources
- **DELETE** - Remove resources


### Authentication

The API supports two authentication methods:

- **OAuth2** - For applications requiring user authorization
- **Personal Access Tokens** - For simple integrations and scripts


For detailed authentication instructions, see the [Authorization page](/authorization).

### Rate Limiting

API requests are rate-limited to ensure fair usage:

- **Rate Limit**: 60 requests per minute per authenticated user
- Rate limit information is included in response headers


### Pagination

Many endpoints support pagination for efficient data retrieval:

- **page**: The current page number (default: 1)
- **per_page**: Number of items per page (default: 20, max: 100)
- **total**: Total number of available records
- **last_page**: Total number of pages


### Error Handling

The API uses standard HTTP status codes and returns error responses in JSON format. All error responses follow a consistent structure:


```json
{
  "success": false,
  "message": "Error message describing what went wrong",
  "meta": {
    "api_version": "2.0.0",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

**Common HTTP Status Codes:**

- **400 Bad Request** - Invalid parameters or missing required fields
- **401 Unauthorized** - Invalid or missing authentication token
- **403 Forbidden** - Insufficient permissions (not a workspace owner or executive manager)
- **404 Not Found** - Resource not found
- **409 Conflict** - Resource already exists or duplicate data
- **422 Unprocessable Entity** - Validation failed (includes field-specific error details)
- **500 Internal Server Error** - Unexpected server error


For validation errors (422), the response includes field-specific error details:


```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."],
    "role": ["The selected role is invalid."]
  },
  "meta": {
    "api_version": "2.0.0",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Access Requirements

**Important:** REST API V2 access is restricted to:

- **Workspace Owners**
- **Executive Managers**


Only users with these roles can access the API. If you don't have the required role, contact your workspace owner or administrator.

### Webhooks

The API supports webhooks for real-time event notifications. You can register callback URLs to receive notifications when events occur in your workspace, such as:

- Data updates
- Member actions
- System alerts
- Time tracking events
- Task updates
- And more


Webhooks allow you to build integrations that respond immediately to changes in your workspace without polling the API. See the **Webhooks** section in the sidebar for details on creating and managing webhooks.

## Getting Started

1. **Set up Authentication** - Create an OAuth2 app or Personal Access Token (see [Authorization](/authorization))
2. **Explore Endpoints** - Browse the available endpoints in the sidebar
3. **Make Your First Request** - Start with the `/api/v2/workspaces` endpoint to get your workspace IDs
4. **Use Workspace IDs** - Use workspace IDs in subsequent requests to access workspace-specific data
5. **Set up Webhooks (Optional)** - Register webhooks to receive real-time event notifications


## Need Help?

- **API Documentation**: Browse endpoints in the sidebar for detailed information
- **Support**: Contact [api-support@webwork-tracker.com](mailto:api-support@webwork-tracker.com)
- **Terms of Service**: [https://www.webwork-tracker.com/terms-of-service](https://www.webwork-tracker.com/terms-of-service)