Timix.AI — Integration API Examples

Runnable examples for the Timix.AI Integration API — time tracking & billing for services businesses. Authenticate with an API key, then create and read customers, projects, tasks, subtasks, and time entries from any language.

• Base URL: https://api.timix.ai/api/integration/v1
• Auth: Authorization: Bearer <key> (also accepts X-Api-Key: <key>)
• Examples: curl · Node.js · Python

Each quickstart runs the same flow: verify the key (GET /me) → create Customer → Project → Task → SubTask → log time → list customers.

---

Get an API key

1. In the Timix.AI web app, go to Settings → API Keys and create a key.
2. New keys start with tmx_ (older bbl_ keys still work). Enable the Write scope for the create/update/delete examples.
3. API access requires a Professional plan or higher.

Then set it as an environment variable (never hard-code keys):

export TIMIX_API_KEY="tmx_your_key_here"

Some writes are role-gated (e.g. creating a Customer requires an Owner/Admin key). Reads and logging time work for lower roles. See the per-endpoint notes below.

---

Run an example

# curl (needs bash + jq)
export TIMIX_API_KEY="tmx_..." && bash examples/curl/quickstart.sh

# Node.js (18+, no dependencies — uses built-in fetch)
export TIMIX_API_KEY="tmx_..." && node examples/node/quickstart.mjs

# Python (3.8+, needs `requests`)
export TIMIX_API_KEY="tmx_..." && python examples/python/quickstart.py

---

Endpoints

Hierarchy: Customer → Project → Task → SubTask → Time Entry. All time is logged at the SubTask level.

Method & path	Does	Notes
GET /me	Who am I / plan check	{ organizationId, organizationName, userId, apiKeyId, plan, hasApiAccess }
GET /customers	List customers	Paginated (see below). Also /projects, /tasks, /subtasks, /time-reports, /invoices
POST /customers	Create a customer	Body { name, ... }. 201 + the created entity. Owner/Admin key
GET /customers/{id}	Read one	200 / 404
PUT /customers/{id}	Update	Full update, or partial with ?fields=Name,Country. 200 + entity
DELETE /customers/{id}	Delete	204
POST /projects	Create a project	`{ name, parentId: , allowedBillingTypes?: ["TM"
POST /tasks	Create a task	{ name, parentId: <projectId>, createGeneralActivity?: true }
POST /subtasks	Create a subtask	{ name, parentId: <taskId> }
POST /time-reports	Log time	{ parentId: <subTaskId>, subTaskId: <subTaskId>, start, end, text? }. Server computes duration/hours

Pagination: ?page=<1-based>&pageSize=<n ≤200, default 50> → { items, totalCount, page, pageSize, hasMore } (also an X-Total-Count header). Lists are stable-sorted newest-first. Polling filters: ?createdAfter=<ISO>, ?updatedAfter=<ISO>; /time-reports and /invoices also accept ?from=&to=.

GET /invoices returns the wrapper { data: [...] } and pages with pageNumber (not { items } / page).

---

Auth, errors & rate limits

• Auth header: Authorization: Bearer <key> (or X-Api-Key: <key>). The organization is bound to the key server-side, so you never send an org id.
• Errors: non-2xx responses are { "error": { "code": "...", "message": "...", "details"?: ... } } with real HTTP status codes — 422 validation, 401 bad/missing key, 403 (entitlement_required = plan gate), 404, 409, 429, 500.
• Rate limit: per key, a fixed 60-second window (120/min Free–Starter, 300/min Professional, 1000/min Business). On 429 a Retry-After header (seconds) tells you how long to back off.
• Sensitive data: customer contact fields (name/email/phone/VAT) are redacted unless the key is allowed to see sensitive data (a per-key toggle in the app).

---

Learn more at timix.ai · Integrations & API · hello@timix.ai