How to Integrate Bolt.new with Everhour

Everhour API authentication uses a simple API token passed as the X-Api-Key header on every request. There is no OAuth flow, no token refresh, and no complex signature generation — just a static token that identifies your account. To find your API token, log into Everhour and click your profile picture or name in the top-right corner to open the profile dropdown. Select Profile from the menu. On your profile page, scroll down to the API Token section — it is usually near the bottom of the page. Your API token is displayed there as a long alphanumeric string. Click the copy button or select and copy the token manually. If the API Token section is not visible, your Everhour account may be on a plan that does not include API access, or you may need to enable API access in your account settings. Everhour's free plan includes API access for accounts with up to 5 members. Paid plans have no API restrictions. Add the token to your Bolt project's .env file as EVERHOUR_API_KEY. This must not have the NEXT_PUBLIC_ prefix — the API key grants full account access and must only be used server-side in API routes, never bundled into client-side JavaScript. Also note your user ID if you plan to filter time records by specific team members. Your user ID appears in the profile URL when you view your own profile, or you can fetch it via GET /users/me from the Everhour API. Add it as EVERHOUR_USER_ID if needed. The Everhour API base URL is https://api.everhour.com. Every request must include two headers: X-Api-Key: YOUR_TOKEN and Content-Type: application/json. The API returns JSON for all responses and uses standard HTTP status codes.

1// lib/everhour.ts
2const EVERHOUR_BASE_URL = 'https://api.everhour.com';
3
4function getHeaders() {
5  const apiKey = process.env.EVERHOUR_API_KEY;
6  if (!apiKey) throw new Error('EVERHOUR_API_KEY must be set in .env');
7
8  return {
9    'X-Api-Key': apiKey,
10    'Content-Type': 'application/json',
11  };
12}
13
14export async function everhourFetch<T = unknown>(
15  path: string,
16  params?: Record<string, string | number>
17): Promise<T> {
18  const url = new URL(`${EVERHOUR_BASE_URL}${path}`);
19  if (params) {
20    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));
21  }
22
23  const response = await fetch(url.toString(), { headers: getHeaders() });
24
25  if (!response.ok) {
26    const err = await response.json().catch(() => ({ message: response.statusText })) as { message?: string; error?: string };
27    throw new Error(err.message || err.error || `Everhour API error: ${response.status}`);
28  }
29
30  return response.json() as Promise<T>;
31}
32
33export async function everhourPost<T = unknown>(path: string, body: unknown): Promise<T> {
34  const response = await fetch(`${EVERHOUR_BASE_URL}${path}`, {
35    method: 'POST',
36    headers: getHeaders(),
37    body: JSON.stringify(body),
38  });
39
40  if (!response.ok) {
41    const err = await response.json().catch(() => ({ message: response.statusText })) as { message?: string };
42    throw new Error(err.message || `Everhour POST error: ${response.status}`);
43  }
44
45  return response.json() as Promise<T>;
46}

The core Everhour API resources for dashboard building are time records and projects. Understanding the response structure for each helps you design efficient API routes that return clean data to your React components. The time records endpoint (GET /time-records) accepts date range parameters: from and to in YYYY-MM-DD format. Without date parameters, it defaults to returning today's records. Always provide explicit date ranges for dashboard queries. Optional filter parameters include user_id (filter to one team member) and limit/offset for pagination (default is 50 records per request, maximum 50). Each time record in the response includes: id, time (integer seconds), date (YYYY-MM-DD string), task (nested object with id, name, and projects array), user (nested object with id, name, avatar), and optionally comment. The task.projects array contains the projects the task belongs to, each with an id and name. Task IDs use the provider prefix format for integrated PM tools — Asana tasks have IDs like 'as:1234567890', Jira issues like 'jira:PROJ-123'. The projects endpoint (GET /projects) returns all projects in the account including their budget settings and total tracked time. Each project has a name, status (active/archived), and budget object (type, progress, hours). The budget.progress value is the percentage of budget consumed — useful for over-budget alerts. For building aggregate reports (hours per project, hours per user), fetch all time records for the period and aggregate in your API route before returning to the client. This keeps the aggregation logic server-side and returns a smaller, pre-processed payload to React components. Use JavaScript's reduce method to build lookup objects keyed by project ID and user ID.

1// app/api/everhour/time-records/route.ts
2import { NextResponse } from 'next/server';
3import { everhourFetch } from '@/lib/everhour';
4
5interface TimeRecord {
6  id: number;
7  time: number;
8  date: string;
9  task: { id: string; name: string; projects: Array<{ id: string; name: string }> };
10  user: { id: number; name: string };
11  comment?: string;
12}
13
14const cache = new Map<string, { data: unknown; expiresAt: number }>();
15
16export async function GET(request: Request) {
17  const { searchParams } = new URL(request.url);
18  const from = searchParams.get('from');
19  const to = searchParams.get('to');
20  const userId = searchParams.get('userId');
21
22  if (!from || !to) {
23    return NextResponse.json({ error: 'from and to are required' }, { status: 400 });
24  }
25
26  const cacheKey = `${from}-${to}-${userId}`;
27  const cached = cache.get(cacheKey);
28  if (cached && Date.now() < cached.expiresAt) {
29    return NextResponse.json(cached.data);
30  }
31
32  try {
33    const allRecords: TimeRecord[] = [];
34    let offset = 0;
35    const limit = 50;
36
37    while (true) {
38      const params: Record<string, string | number> = { from, to, limit, offset };
39      if (userId) params.userId = userId;
40
41      const records = await everhourFetch<TimeRecord[]>('/time-records', params);
42      allRecords.push(...records);
43      if (records.length < limit) break;
44      offset += limit;
45    }
46
47    const totalSeconds = allRecords.reduce((sum, r) => sum + r.time, 0);
48
49    // Group by project
50    const byProject: Record<string, { name: string; seconds: number }> = {};
51    for (const r of allRecords) {
52      const project = r.task.projects?.[0];
53      if (!project) continue;
54      if (!byProject[project.id]) byProject[project.id] = { name: project.name, seconds: 0 };
55      byProject[project.id].seconds += r.time;
56    }
57
58    // Group by user
59    const byUser: Record<number, { name: string; seconds: number }> = {};
60    for (const r of allRecords) {
61      if (!byUser[r.user.id]) byUser[r.user.id] = { name: r.user.name, seconds: 0 };
62      byUser[r.user.id].seconds += r.time;
63    }
64
65    const result = {
66      totalSeconds,
67      totalHours: Math.round((totalSeconds / 3600) * 100) / 100,
68      byProject: Object.entries(byProject)
69        .map(([id, v]) => ({ id, ...v, hours: Math.round((v.seconds / 3600) * 100) / 100 }))
70        .sort((a, b) => b.seconds - a.seconds),
71      byUser: Object.entries(byUser)
72        .map(([id, v]) => ({ id, ...v, hours: Math.round((v.seconds / 3600) * 100) / 100 }))
73        .sort((a, b) => b.seconds - a.seconds),
74      records: allRecords,
75    };
76
77    cache.set(cacheKey, { data: result, expiresAt: Date.now() + 30_000 });
78    return NextResponse.json(result);
79  } catch (err) {
80    const message = err instanceof Error ? err.message : 'Failed to fetch time records';
81    return NextResponse.json({ error: message }, { status: 500 });
82  }
83}

With the API routes returning aggregated time data, build the React dashboard that presents this information visually. A team hours dashboard has three typical sections: a summary bar at the top, a visual breakdown of hours by project, and a table showing individual team member contributions. Fetch data on component mount using useEffect with the current week or month as the default date range. Store both the loading state and the data in component state. Show loading skeletons while the fetch is in progress — Everhour's API can take 1-3 seconds for large accounts with many records. For the summary bar, display three key metrics: total tracked hours for the period, number of active projects with logged time, and total number of team members who tracked time. Convert seconds to hours using the / 3600 conversion and round to one decimal place for display. For the project breakdown, a horizontal bar chart (Recharts BarChart with layout='vertical') works well because project names can be long and fit better on the Y axis. Each bar represents one project's total hours. Color bars by a consistent palette and truncate project names longer than 30 characters with an ellipsis tooltip. For the team member table, show each person's name, total hours for the period, and a mini bar showing their hours as a percentage of the top contributor's hours. Sort by hours descending. This gives managers a quick glance at workload distribution. Add date range quick-select buttons (This Week, Last Week, This Month, Last Month) that recalculate the from and to dates and trigger a new fetch. Use JavaScript's Date object to calculate these ranges dynamically rather than hardcoding dates.

Writing time entries back to Everhour requires a task ID to associate the time with. Unlike pure time tracking tools where you can log time without a task, Everhour's core model is task-based — every time record belongs to a task (which belongs to a project). This reflects Everhour's role as an overlay on existing PM tools where tasks already exist. To create a time record, POST to /time-records with the body containing: time (integer seconds), date (YYYY-MM-DD string), task (object with id field), and optionally comment. The task ID must be a valid Everhour task ID — either a provider-specific ID from an integrated PM tool (format: 'as:1234567' for Asana) or a Everhour-native task ID. For the best user experience, build a task selector that lets users pick from their assigned tasks. Fetch tasks for a project using GET /projects/{projectId}/tasks, which returns task names and IDs. Populate a dropdown with these tasks so users select the task first, then enter hours and an optional comment. Time input from users should accept hours and minutes in a friendly format (e.g., '1h 30m' or '1.5') and convert to seconds before submission. A simple parser: if the input contains 'h', split on 'h' and 'm'; if it is a plain number, treat as hours and multiply by 3600. After successful creation, invalidate the time records cache for today's date range so the dashboard reflects the new entry immediately. Consider returning the full created record in the API response so the UI can update optimistically without a full refetch. Note: Everhour does not support incoming webhook callbacks during Bolt development — the WebContainer cannot receive POST requests from external services. For webhook-driven real-time sync, deploy to Netlify or Bolt Cloud and register the webhook URL in your Everhour account settings.

1// app/api/everhour/time-records/create/route.ts
2// NOTE: Everhour webhook callbacks require a deployed URL.
3// For real-time sync, deploy to Netlify or Bolt Cloud and register
4// your webhook URL in Everhour Settings → Integrations → Webhooks.
5import { NextResponse } from 'next/server';
6import { everhourPost } from '@/lib/everhour';
7
8interface CreateTimeRecordBody {
9  taskId: string;
10  date: string;
11  hours: number;
12  comment?: string;
13}
14
15interface EverhourTimeRecord {
16  id: number;
17  time: number;
18  date: string;
19  task: { id: string; name: string };
20  user: { id: number; name: string };
21}
22
23export async function POST(request: Request) {
24  const { taskId, date, hours, comment } = await request.json() as CreateTimeRecordBody;
25
26  if (!taskId?.trim()) {
27    return NextResponse.json({ error: 'taskId is required' }, { status: 400 });
28  }
29  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) {
30    return NextResponse.json({ error: 'date must be in YYYY-MM-DD format' }, { status: 400 });
31  }
32  if (!hours || hours <= 0 || hours > 24) {
33    return NextResponse.json({ error: 'hours must be a positive number up to 24' }, { status: 400 });
34  }
35
36  const timeInSeconds = Math.round(hours * 3600);
37
38  try {
39    const record = await everhourPost<EverhourTimeRecord>('/time-records', {
40      task: { id: taskId },
41      time: timeInSeconds,
42      date,
43      ...(comment?.trim() ? { comment: comment.trim() } : {}),
44    });
45
46    return NextResponse.json({
47      success: true,
48      record: {
49        id: record.id,
50        date: record.date,
51        hours: record.time / 3600,
52        taskName: record.task.name,
53        userName: record.user.name,
54      },
55    });
56  } catch (err) {
57    const message = err instanceof Error ? err.message : 'Failed to create time record';
58    return NextResponse.json({ error: message }, { status: 500 });
59  }
60}