Developer reference · v1

Maintenance data, ready for your tools.

A small, predictable REST surface for syncing AutoHomi tasks, completion history, and upcoming maintenance into the systems you already use.

Manage API tokens Start with authentication

Surface map

GET/api/v1/tasks

POST/api/v1/tasks

GET/api/v1/completions

GET/api/v1/calendar.ics

01 · Authentication

One token, one owner.

API access uses personal bearer tokens. Tokens are intentionally scoped to the AutoHomi account that created them, so an integration cannot read or write another owner's maintenance data.

Open token settings

Create and send a token

In the dashboard, open Settings → API access, create a token, and copy the raw value immediately. It is shown only once.

01Choose a descriptive label so you can revoke the integration later.
02Copy the token when it is revealed; AutoHomi stores only its hash.
03Send it on every request as Authorization: Bearer <token>.

The examples below assume BASE_URL is your deployed origin (for example https://autohomi.polsia.app) andTOKEN is the copied raw token.

02 · Tasks

Read and create maintenance work.

Task reads accept composable filters. Task creation stores the new row against the token owner; userId never comes from the request body.

GET

/api/v1/tasks

List the owner’s tasks, ordered by due date and then creation time. Filters combine with AND.

Request

shell

curl -G "$BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=pending" \
  --data-urlencode "category=home" \
  --data-urlencode "dueAfter=2026-09-01T00:00:00Z" \
  --data-urlencode "dueBefore=2026-12-01T00:00:00Z"

Response

{
  "items": [
    {
      "id": "task_123",
      "title": "Replace HVAC filter",
      "description": "Use MERV 11",
      "category": "home",
      "status": "pending",
      "dueAt": "2026-09-18T14:00:00.000Z",
      "frequencyDays": 90,
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-01T10:00:00.000Z"
    }
  ]
}

GET tasks query filters
Field	Type	Required	Constraints
status	enum	No	pending, done, or overdue
category	enum	No	home or auto
dueAfter	ISO datetime	No	Inclusive lower bound for dueAt; offset required
dueBefore	ISO datetime	No	Inclusive upper bound for dueAt; offset required

Status: 200 success · 400 malformed filter · 401 missing or invalid bearer token

POST

/api/v1/tasks

Create a pending task for the token owner. The response is the created task object, not an items envelope.

Request

shell

curl -X POST "$BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Replace HVAC filter",
    "dueAt": "2026-09-18T14:00:00Z",
    "category": "home",
    "description": "Use MERV 11",
    "frequencyDays": 90,
    "asset": "Main house",
    "assetId": null,
    "templateKey": null
  }'

Response

{
  "id": "task_123",
  "title": "Replace HVAC filter",
  "description": "Use MERV 11",
  "category": "home",
  "status": "pending",
  "dueAt": "2026-09-18T14:00:00.000Z",
  "frequencyDays": 90,
  "createdAt": "2026-09-05T10:00:00.000Z",
  "updatedAt": "2026-09-05T10:00:00.000Z"
}

POST tasks JSON body
Field	Type	Required	Constraints
title	string	Yes	1–200 characters
dueAt	ISO datetime	Yes	Offset-aware ISO 8601 datetime
category	enum	Yes	home or auto
description	string \| null	No	Optional; up to 2,000 characters
frequencyDays	integer \| null	No	Optional; positive, maximum 3,650
asset	string \| null	No	Optional free-text asset name; up to 200 characters
assetId	string \| null	No	Optional durable asset ID; must belong to the token owner
templateKey	string \| null	No	Optional; up to 120 characters

Status: 201 created · 400 invalid JSON or body · 401 missing or invalid bearer token · 404 assetId is not owned by the token owner

03 · Completions

Bring history into the loop.

Completion records are returned newest first and include the task title, cost fields, notes, and the ISO timestamp at which the task was completed.

GET

/api/v1/completions

List completion records belonging to the bearer token’s owner. An unknown or foreign taskId is a validation error.

Request

shell

curl -G "$BASE_URL/api/v1/completions" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "completedAfter=2026-01-01T00:00:00Z" \
  --data-urlencode "completedBefore=2026-12-31T23:59:59Z"

Response

{
  "items": [
    {
      "id": "completion_456",
      "taskId": "task_123",
      "taskTitle": "Replace HVAC filter",
      "completedAt": "2026-08-20T15:30:00.000Z",
      "costCents": 2400,
      "costCurrency": "USD",
      "notes": "Filter replaced"
    }
  ]
}

GET completions query filters
Field	Type	Required	Constraints
taskId	string	No	Filter to one owner-scoped task
completedAfter	ISO datetime	No	Inclusive lower bound for completedAt; offset required
completedBefore	ISO datetime	No	Inclusive upper bound for completedAt; offset required

Status: 200 success · 400 malformed date or unknown / foreign taskId · 401 missing or invalid bearer token

04 · Calendar

Subscribe to the next 90 days.

The ICS feed contains the owner's non-completed tasks due within the next 90 days. It is intended for calendar subscriptions and one-time imports, not historical completion reporting.

GET

/api/v1/calendar.ics

Download an RFC 5545 calendar feed for the token owner. The response is text/calendar and ends with CRLF line endings.

Request

shell

curl "$BASE_URL/api/v1/calendar.ics" \
  -H "Authorization: Bearer $TOKEN" \
  -o autohomi.ics

Response

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//polsia//tasks//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VEVENT
UID:task_123@tasks.polsia
DTSTAMP:20260905
DTSTART;VALUE=DATE:20260918
DTEND;VALUE=DATE:20260919
DUE;VALUE=DATE:20260918
SUMMARY:Replace HVAC filter
DESCRIPTION:Use MERV 11
END:VEVENT
END:VCALENDAR

Calendar window: future tasks through 90 days from the request time. Completed tasks are excluded, and each task is represented as an all-day event with an exclusive next-dayDTEND.

Status: 200 success with Content-Type text/calendar; charset=utf-8 · 401 missing or invalid bearer token · 400 is not emitted because this endpoint has no query validation