Versioned HTTP contract

A stable interface between your tools and DemioFlow

The v1 contract defines authentication, resources, errors and guarantees clients can rely on without depending on the Firestore schema.

Contract principles

The public facade used by the CLI is https://app.demioflow.com/v1.
The server derives ownership from the token; clients never provide userId.
Unknown options and fields are rejected with UNKNOWN_OPTION to catch typos.
Dates and instants use ISO 8601; instants are returned in UTC.

Browser authorization

The CLI starts a device code, opens the authorization page, then exchanges approval for a Firebase session. The password stays exclusively in the web application.

POST /v1/auth/device/code
POST /v1/auth/device/approve
POST /v1/auth/device/token

Codes expire, are single-use and token responses must never be written to logs.

Resources and actions

Resource	v1 collection
Areas	/v1/areas
Projects	/v1/projects
Sections	/v1/projects/{projectId}/sections
Tasks	/v1/tasks
Goals	/v1/goals
Habits	/v1/habits
Tags	/v1/tags

Relationships are validated server-side. A section must belong to the same project as the task that references it.

POST /v1/projects/{projectId}/sections:reorder
POST /v1/projects/reorder
POST /v1/tasks/reorder
POST /v1/tags/reorder
POST /v1/sections/{sectionId}:move
POST /v1/tags/{tagId}:link

Predictable errors

{
  "error": {
    "code": "PROJECT_MISMATCH",
    "message": "The section must belong to the selected project.",
    "retryable": false
  },
  "meta": { "requestId": "req_…", "apiVersion": "1.0" }
}

HTTP	Common codes	Meaning
400	UNKNOWN_OPTION / METHOD_NOT_ALLOWED	Unknown option or method
401	AUTH_REQUIRED / AUTH_INVALID	Missing or invalid token
404	NOT_FOUND / ROUTE_NOT_FOUND	Resource or route not found
422	INVALID_* / *_MISMATCH	Invalid value, relationship or state
500	INTERNAL_ERROR	Unexpected server error
503	API_UNAVAILABLE	Public facade temporarily unavailable

Safe automation

The retryable field states whether an operation may be retried. Today, the CLI maps network and server failures to non-zero exit codes; idempotency keys and If-Match preconditions are contract roadmap items, not guarantees of the deployed API.

Normative source

The versioned OpenAPI specification in the application repository remains the machine-readable source. This page is the human guide and evolves with every public contract extension.