Hours reports

Full members can inspect only their own summary. Workspace-wide summaries and detailed entry pages require the admin role; manager capabilities do not widen this external connector surface. Every response is money-blind.

Get my hours summary

Summarize YOUR OWN hours for a server-resolved calendar period. Defaults to this_month in the workspace timezone. Returns the resolved range, recorded/worked/Task/taskless/billable totals, an optional breakdown, and an explicit completeness bit. Accepts no target member or workspace-wide filter and never returns rates, amounts, or email.

GET /v1/workspaces/{workspaceId}/hours/me/summary

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/hours/me/summary"

Response: the resulting object as JSON.

Get workspace hours summary

ADMIN-ONLY workspace hours summary for a server-resolved calendar period. Filters people, teams, Project, Task, activity, and billable classification with AND semantics (people and teams form a union). Returns money-blind totals, member rows, optional breakdown, resolved range, and completeness. Managers with time.viewAll remain self-only on connectors.

GET /v1/workspaces/{workspaceId}/hours/summary

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/hours/summary"

Response: the resulting object as JSON.

List workspace time entries

ADMIN-ONLY paginated workspace time entries for a required calendar period. Open entries are emitted before closed entries; closed rows are newest report time first. Returns money-blind rows plus count, nextCursor, and completeness. Follow nextCursor until null; max page size 100. Managers with time.viewAll cannot call this connector tool.

GET /v1/workspaces/{workspaceId}/hours/entries

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/hours/entries?period=today"

Response: a list envelope { data, has_more, next_cursor }. While has_more is true, pass next_cursor back as cursor to get the next page.

Errors

Every error is an RFC 9457 application/problem+json body with a machine-stable code. Branch on the code, not the message:

• 401 — unauthenticated / invalid_token: the bearer token is missing, expired, or revoked. Re-authenticate; do not retry as-is.
• 403 — insufficient_scope / forbidden / upgrade_required: the token works but may not do this. upgrade_required means the workspace is not on Pro.
• 404 — not_found_or_forbidden: the resource does not exist for this token. Never probe for existence.
• 409 — idempotency_conflict: same Idempotency-Key, different body. Mint a new key.
• 429 — rate_limited: back off for the number of seconds in Retry-After, then retry.
• 400 — validation_failed: the request shape is wrong. Fix the request; retrying unchanged will fail again.