# WebWork Time Tracker API V2 Documentation

## Welcome to WebWork API V2 Documentation

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

## What is API V2?

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:** WebWork 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)