API Documentation

This documentation outlines how to interact with the Really Focus REST API.

Authentication

The Pulse API uses API tokens for authentication. All API requests must include an Authorization header with a Bearer token.

Authorization: Bearer <YOUR_API_TOKEN>

You can generate and manage your API tokens from your user profile settings page.

All API requests must be made over HTTPS.

Base URL

All API endpoints are relative to the following base URL:

https://reallyfocus.com/api

---

Clients API

Endpoints for managing client records.

List Clients

GET /clients

Returns a list of all clients accessible by the authenticated user's team.

Response (200 OK)

{
    "data": [
        {
            "id": 1,
            "name": "Example Client Inc.",
            "email": "contact@example.com",
            "description": "Description of the client.",
            "phone": "555-1234",
            "is_archived": false,
            "logo_path": null,
            "created_at": "2023-10-27T10:00:00.000000Z",
            "updated_at": "2023-10-27T10:00:00.000000Z"
            // ClientResource fields...
        },
        // ... more clients
    ]
}
    

Get Client

GET /clients/{client_id}

Returns the details for a specific client.

Parameters

• client_id (int, required): The ID of the client to retrieve.

Response (200 OK)

{
    "data": {
        "id": 1,
        "name": "Example Client Inc.",
        "email": "contact@example.com",
        "description": "Description of the client.",
        "phone": "555-1234",
        "is_archived": false,
        "logo_path": null,
        "created_at": "2023-10-27T10:00:00.000000Z",
        "updated_at": "2023-10-27T10:00:00.000000Z"
        // ClientResource fields...
    }
}
    

Responses

• 404 Not Found: If the client does not exist.
• 403 Forbidden: If the client does not belong to the user's team.

Create Client

POST /clients

Creates a new client record.

Request Body (JSON)

{
    "name": "New Client Co.",
    "email": "new@client.co",
    "description": "A promising new client.",
    "phone": "555-5678"
}
    

Fields

• name (string, required): Name of the client.
• email (string, nullable, email): Client's email address.
• description (string, required): Description of the client.
• phone (string, nullable): Client's phone number.
• logo (file, nullable, image): Client logo (omitted in example, standard file upload).

Response (201 Created)

Returns the newly created client object (similar structure to Get Client response).

Responses

• 422 Unprocessable Entity: If validation fails (e.g., missing required fields, plan limits reached).

Update Client

PUT /clients/{client_id} or PATCH /clients/{client_id}

Updates an existing client record.

Parameters

• client_id (int, required): The ID of the client to update.

Request Body (JSON)

Include only the fields you want to update.

{
    "name": "Updated Client Name",
    "phone": "555-9999",
    "is_archived": true
}
    

Fields

• name (string, required): Name of the client.
• email (string, nullable, email): Client's email address.
• description (string, required): Description of the client.
• phone (string, nullable): Client's phone number.
• is_archived (boolean, nullable): Set to true to archive the client.
• logo (file, nullable, image): New client logo (omitted in example).

Response (200 OK)

Returns the updated client object.

Responses

• 404 Not Found: If the client does not exist.
• 403 Forbidden: If the client does not belong to the user's team.
• 422 Unprocessable Entity: If validation fails.

Delete Client

DELETE /clients/{client_id}

Deletes a client record. Note: This currently performs a hard delete. Consider implications for related projects and tasks.

Parameters

• client_id (int, required): The ID of the client to delete.

Response (204 No Content)

An empty response indicates successful deletion.

Responses

• 404 Not Found: If the client does not exist.
• 403 Forbidden: If the client does not belong to the user's team.

---

Projects API

Endpoints for managing projects.

List Projects

GET /projects

Returns a list of all projects accessible by the authenticated user's team.

Response (200 OK)

{
    "data": [
        {
            "id": 1,
            "name": "Project Alpha",
            "description": "First project for client.",
            "client_id": 1,
            "is_archived": false,
            "created_at": "2023-10-27T10:05:00.000000Z",
            "updated_at": "2023-10-27T10:05:00.000000Z",
            "client": {
                // Embedded ClientResource data...
            }
            // ProjectResource fields...
        },
        // ... more projects
    ]
}
    

Get Project

GET /projects/{project_id}

Returns the details for a specific project.

Parameters

• project_id (int, required): The ID of the project to retrieve.

Response (200 OK)

{
    "data": {
        "id": 1,
        "name": "Project Alpha",
        "description": "First project for client.",
        "client_id": 1,
        "is_archived": false,
        "created_at": "2023-10-27T10:05:00.000000Z",
        "updated_at": "2023-10-27T10:05:00.000000Z",
        "client": {
             // Embedded ClientResource data...
        }
        // ProjectResource fields...
    }
}
    

Responses

• 404 Not Found: If the project does not exist.
• 403 Forbidden: If the project does not belong to the user's team.

Create Project

POST /projects

Creates a new project.

Request Body (JSON)

{
    "name": "Project Beta",
    "description": "Second project.",
    "client_id": 1
}
    

Fields

• name (string, required): Name of the project.
• description (string, nullable): Project description.
• client_id (int, required): The ID of the client this project belongs to (must belong to user's team).

Response (201 Created)

Returns the newly created project object.

Responses

• 422 Unprocessable Entity: If validation fails (e.g., invalid client_id).
• 403 Forbidden: If the specified client_id does not belong to the user's team.

Update Project

PUT /projects/{project_id} or PATCH /projects/{project_id}

Updates an existing project.

Parameters

• project_id (int, required): The ID of the project to update.

Request Body (JSON)

Include only the fields you want to update.

{
    "name": "Project Beta Renamed",
    "is_archived": true
}
    

Fields

• name (string, required): Name of the project.
• description (string, nullable): Project description.
• is_archived (boolean, sometimes): Set to true to archive the project.

Response (200 OK)

Returns the updated project object.

Responses

• 404 Not Found: If the project does not exist.
• 403 Forbidden: If the project does not belong to the user's team.
• 422 Unprocessable Entity: If validation fails.

Delete Project

DELETE /projects/{project_id}

Deletes a project record. Note: This currently performs a hard delete.

Parameters

• project_id (int, required): The ID of the project to delete.

Response (204 No Content)

An empty response indicates successful deletion.

Responses

• 404 Not Found: If the project does not exist.
• 403 Forbidden: If the project does not belong to the user's team.

---

Tasks API

Endpoints for managing tasks.

List Tasks

GET /tasks

Returns a list of tasks for the authenticated user's team. Can be filtered by project.

Query Parameters

• project_id (int, optional): Filter tasks by a specific project ID.

Response (200 OK)

{
    "data": [
        {
            "id": 1,
            "name": "Design Mockups",
            "description": "Create initial designs.",
            "status": 1, // 1: Open, 2: In Progress, 3: Closed
            "priority": 2, // Refer to Priority Enum
            "weight": null, // Refer to TaskWeight Enum
            "project_id": 1,
            "due_date": "2023-11-15",
            "start_date": "2023-11-01",
            "assignment_id": 1,
            // ... other TaskResource fields
            "project": { /* Embedded ProjectResource */ },
            "assignedTo": { /* Embedded UserResource */ }
        },
        // ... more tasks
    ]
}
    

Responses

• 403 Forbidden: If filtering by a `project_id` that doesn't belong to the user's team.

Get Task

GET /tasks/{task_id}

Returns the details for a specific task.

Parameters

• task_id (int, required): The ID of the task to retrieve.

Response (200 OK)

{
    "data": {
        "id": 1,
        "name": "Design Mockups",
        // ... other TaskResource fields
        "project": { /* Embedded ProjectResource */ },
        "assignedTo": { /* Embedded UserResource */ },
        "parent": null,
        "children": []
    }
}
    

Responses

• 404 Not Found: If the task does not exist.
• 403 Forbidden: If the task does not belong to the user's team.

Create Task

POST /tasks

Creates a new task.

Request Body (JSON)

{
    "name": "Implement Feature X",
    "description": "Code the main logic for Feature X.",
    "project_id": 1,
    "priority": 3,
    "due_date": "2023-11-30",
    "assignment_id": 2 // User ID of the assignee (must be in team)
}
    

Fields

• name (string, required): Task name.
• description (string, required): Task description.
• status (int, optional, default: 1): Task status (1: Open, 2: In Progress, 3: Closed).
• priority (int, required): Task priority (refer to Enum).
• weight (int, nullable): Task weight (refer to Enum).
• project_id (int, required): ID of the project this task belongs to.
• due_date (date, required): Due date (YYYY-MM-DD).
• start_date (date, nullable): Start date (YYYY-MM-DD). Must be before or equal to due_date.
• assignment_id (int, nullable): ID of the user assigned to the task (must be in the same team).
• parent_id (int, nullable): ID of the parent task (must be in same project, cannot be a subtask itself).
• estimated_duration / actual_duration (numeric, nullable): Duration value.
• estimated_duration_unit / actual_duration_unit (string, nullable): Unit ('hours', 'days', 'weeks').
• currently_working_on (boolean, nullable): Is the assignee actively working on this?

Response (201 Created)

Returns the newly created task object.

Responses

• 422 Unprocessable Entity: If validation fails.
• 403 Forbidden: If the specified `project_id` or `assignment_id` is invalid or not accessible by the user's team.

Update Task

PUT /tasks/{task_id} or PATCH /tasks/{task_id}

Updates an existing task.

Parameters

• task_id (int, required): The ID of the task to update.

Request Body (JSON)

Include only the fields you want to update.

{
    "status": 2,
    "assignment_id": 1,
    "priority": 1
}
    

Fields

Same fields as Create Task, but all are optional ('sometimes' validation rule applies).

Response (200 OK)

Returns the updated task object.

Responses

• 404 Not Found: If the task does not exist.
• 403 Forbidden: If the task does not belong to the user's team or if attempting to move to a project not in the user's team.
• 422 Unprocessable Entity: If validation fails.

Delete Task

DELETE /tasks/{task_id}

Deletes a task record.

Parameters

• task_id (int, required): The ID of the task to delete.

Response (204 No Content)

An empty response indicates successful deletion.

Responses

• 404 Not Found: If the task does not exist.
• 403 Forbidden: If the task does not belong to the user's team.