API v1

Finitu API Documentation

Complete reference for integrating with the Finitu API. Manage tasks, projects, time tracking, and more programmatically.

Base URL

https://api.finitu.app/functions/v1/api/v1

API Keys

Scoped access control

HTTPS Only

End-to-end encryption

Rate Limited

100 req/min default

Authentication

The Finitu API supports two authentication methods: API Keys and Bearer Tokens (JWT). Both methods provide secure access to the API with different use cases.

API Key Authentication

API Keys are ideal for server-to-server integrations and automated systems. They provide scoped access and can be rotated without affecting user sessions.

Header:

X-API-Key: fnt_abc123def456...

Available Scopes:

tasks:read

tasks:write

tasks:delete

projects:read

projects:write

projects:delete

lists:read

lists:write

lists:delete

time:read

time:write

time:delete

Bearer Token Authentication

Bearer tokens (JWT) are obtained through user authentication and provide access based on the user's permissions. Ideal for user-facing applications.

Header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

How to Obtain a Token:

To obtain a Bearer token, authenticate using email and password credentials via the authentication endpoint.

POST /auth/v1/token?grant_type=password

// JavaScript (using fetch)
const response = await fetch('https://api.finitu.app/auth/v1/token?grant_type=password', {
  method: 'POST',
  headers: {
    'apikey': 'YOUR_ANON_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password'
  })
});

const { access_token } = await response.json();
// Use access_token as your Bearer token in subsequent requests

Example Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "xxxxx-xxxxx-xxxxx-xxxxx",
  "user": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "email": "user@example.com"
  }
}

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

API Key

100 requests per minute (or custom override)

Bearer Token

60 requests per minute

Response Headers:

X-RateLimit-LimitMaximum requests allowed in the window

X-RateLimit-RemainingRequests remaining in current window

X-RateLimit-ResetUnix timestamp when the window resets

Tasks

Manage tasks including creation, assignment, completion, and tracking. Tasks can be associated with projects, locations, Kanban lanes, and have comments, assignees, attached lists, dependencies, and QR codes for mobile access.

Projects

Manage projects with Kanban-style lanes, custom statuses, and team assignments. Projects can contain multiple tasks and support both user and group-based access control.

Lists

Manage checklists and templates that can be attached to tasks. Lists support conditional branching (decision trees) where each item can offer multiple choices with different actions, task linking to connect list items directly to existing tasks, ordering, and completion tracking. List items can trigger subtasks, link to other checklists for nested workflows, or be directly associated with existing tasks for integrated task management.

Time Entries

Track time spent on tasks, projects, and locations. Supports GPS-based check-in/check-out, duration tracking, and time summaries for reporting.

Locations

Manage physical locations with GPS coordinates, building plans, and QR codes for mobile check-in. Locations can be associated with tasks and time entries.

Users

Manage users within your account including profiles, roles, groups, and permissions. Access user profiles and manage team assignments.

Groups

Manage user groups for organizing teams and assigning collective permissions. Groups can have roles, nested hierarchies, and be assigned to projects.

Messages

Internal messaging system for team communication. Send and receive messages between users within the account with optional attachments.

Notifications

System notifications for task updates, mentions, assignments, and other events. Notifications can be marked as read or acknowledged.

QR Codes

Generate and manage QR codes for tasks and locations. QR codes enable mobile check-in, can be password-protected with automatic rotation, and track scan analytics.

External Contacts

Manage external contacts (vendors, clients, partners) who can be assigned to tasks but are not users in the system.

Task History

Access and query the history of completed and skipped tasks across your account. Task history records are created automatically when tasks are completed or skipped.

Webhooks

Configure webhooks to receive real-time HTTP notifications for events in your account. Webhooks support filtering by event type and include retry logic for failed deliveries.

Subscriptions

Subscribe to entities (tasks, projects, users) to receive notifications about changes. Subscriptions enable personalized notification preferences.