Traballa API Documentation

Introduction

Welcome to the Traballa API. This API allows you to interact with the Traballa system programmatically.

All API requests require authentication using a Bearer token, which you can obtain through the /api/auth endpoint.

Base URL

https://traballa.me/api

Authentication

POST /api/auth

Authenticates a user and returns an access token.

Request Body:
{
  "email": "[email protected]",
  "password": "your_password"
}
Response:
{
  "status": "success",
  "data": {
    "token": "your_access_token",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "role": "user"
    }
  }
}

Users Endpoints

GET /api/users

Returns a list of all users (admin only).

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "users": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]",
        "role": "user",
        "created_at": "2025-01-01 12:00:00"
      },
      ...
    ]
  }
}

GET /api/users/{id}

Returns details for a specific user (admin or self only).

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "role": "user",
      "created_at": "2025-01-01 12:00:00"
    }
  }
}

Projects Endpoints

GET /api/projects

Returns a list of projects the authenticated user has access to.

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "projects": [
      {
        "id": 1,
        "name": "Project Name",
        "description": "Project description",
        "status": "active",
        "organization_name": "Organization Name",
        "is_manager": 1
      },
      ...
    ]
  }
}

GET /api/projects/{id}

Returns details for a specific project.

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "project": {
      "id": 1,
      "name": "Project Name",
      "description": "Project description",
      "status": "active",
      "organization_id": 1,
      "organization_name": "Organization Name"
    }
  }
}

Organizations Endpoints

GET /api/organizations

Returns a list of organizations the authenticated user is a member of.

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "organizations": [
      {
        "id": 1,
        "name": "Organization Name",
        "description": "Organization description",
        "is_admin": 1
      },
      ...
    ]
  }
}

GET /api/organizations/{id}

Returns details for a specific organization.

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "organization": {
      "id": 1,
      "name": "Organization Name",
      "description": "Organization description"
    }
  }
}

Work Hours Endpoints

GET /api/work-hours

Returns work hours for the authenticated user with optional filters.

Headers:
Authorization: Bearer your_access_token
Query Parameters:
  • start_date - Start date (format: YYYY-MM-DD)
  • end_date - End date (format: YYYY-MM-DD)
  • project_id - Filter by project ID
  • organization_id - Filter by organization ID
Response:
{
  "status": "success",
  "data": {
    "work_hours": [
      {
        "id": 1,
        "user_id": 1,
        "project_id": 1,
        "clock_in": "2025-06-15 09:00:00",
        "clock_out": "2025-06-15 17:00:00",
        "status": "completed",
        "total_hours": 8.00,
        "project_name": "Project Name",
        "organization_name": "Organization Name"
      },
      ...
    ]
  }
}

POST /api/work-hours

Clock in to a project.

Headers:
Authorization: Bearer your_access_token
Request Body:
{
  "project_id": 1
}
Response:
{
  "status": "success",
  "data": {
    "message": "Successfully clocked in",
    "work_hour_id": 1,
    "clock_in": "2025-06-15 09:00:00"
  }
}

PUT /api/work-hours/{id}

Clock out from a work session.

Headers:
Authorization: Bearer your_access_token
Response:
{
  "status": "success",
  "data": {
    "message": "Successfully clocked out",
    "work_hour_id": 1,
    "clock_out": "2025-06-15 17:00:00",
    "total_hours": 8.00
  }
}

Error Responses

When errors occur, the API will return an appropriate HTTP status code along with a JSON error message:

{
  "status": "error",
  "message": "Error description"
}

Common Error Codes:

  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 405 Method Not Allowed - HTTP method not supported for this endpoint
  • 500 Internal Server Error - Server-side error

Workly Assistant

💼
Workly