InventTasks External API v2 — REST API for Obsidian tasks

InventTasks is a task manager for Obsidian that stores every task as an ordinary Markdown note. Its optional sync server is free and self-hosted: it provides whole-vault Obsidian sync, a browser web app, and the REST API documented here. Because tasks are plain Markdown, this API reads and writes the same files the plugin uses — no separate task database sits between your automation and your vault.

External API v2 provides stable-ID access to InventTasks Workspaces, Spaces, Folders, Lists, Items, comments, checklists, attachments, Docs, Pages, saved Views, fields, guarded secrets, and arbitrary Workspace or Vault files. It is the automation surface of the self-hosted InventTasks server; the OpenAPI 3.1 document and this guide describe the routes implemented by the current server.

The public resource name is Item. Task appears only in deprecated v1 URLs and legacy storage keys such as parent_task and task_types.

Base URL:    https://your-server/api/ext/v2
OpenAPI:     https://your-server/api/ext/v2/openapi.json
Console:     https://your-server/api-console
Bruno:       https://inventtasks.solidinvent.pl/download/inventtasks-api-bruno.zip

Enable and authenticate#

External API access is configured independently for every server Workspace or Vault and is Off by default.

Enabling access creates a dedicated key beginning with ITX.. It is separate from the sync token and scoped to one server object. The key is displayed once and stored as a hash on the server; rotate it from the dashboard if it is lost or may have been exposed.

export IT_BASE='https://your-server/api/ext/v2'
export IT_WS='main'
export IT_KEY='ITX.replace-me'

curl "$IT_BASE/workspaces/$IT_WS" \
  -H "Authorization: Bearer $IT_KEY"

The owner's dashboard session is also accepted by the same-origin API console.

Secret fields have a second Allow secret access via API switch. It remains Off until explicitly enabled.

Use HTTPS outside a trusted local machine, keep External API access Off when it is not needed, and prefer Read-only mode for reporting and search integrations. Do not commit real API keys or workspace passwords to this Bruno collection, shell history, source control, logs, or screenshots.

Stable IDs and response metadata#

Choose the server Workspace with {ws}. This URL segment is the server object ID shown in the dashboard, not workspace_id from _workspace.md. Then address a structured resource by the stable ID stored in its Markdown frontmatter:

GET /workspaces/{ws}/items/TSK-00001
GET /workspaces/{ws}/lists/LST-02EFGH
GET /workspaces/{ws}/docs/DOC-A1B2C3
GET /workspaces/{ws}/pages/PG-D4E5F6

Filename, title, current List, and nesting are not required. custom_id and titles are searchable values and may be duplicated; they are not canonical single-resource addresses.

A structured response includes read-only metadata similar to:

{
  "object_type": "item",
  "id": "TSK-00001",
  "title": "Ship the API",
  "ancestry": {
    "workspace_id": "WSP-REAL",
    "space_id": "SPC-PRODUCT",
    "folder_id": "FLD-BACKEND",
    "list_id": "LST-API"
  },
  "path": "Product/Backend/API/tsk-00001-ship-the-api.md",
  "storage_path": "Space - Product/Folder - Backend/List - API/tsk-00001-ship-the-api.md",
  "rev": 42
}

ancestry is resolved ownership metadata. It is not stored as the resource's domain location field. A Doc, for example, can return both:

{
  "location": "list:Space - Product/List - Planning",
  "ancestry": { "space_id": "SPC-1", "list_id": "LST-2" }
}

For Space, Folder, and List, storage_path represents the directory and source_path identifies its marker file. Paths are useful for diagnostics and the low-level file API, but structured routes use IDs.

JSON, Markdown, and redaction#

JSON is the default. An explicit format overrides the Accept header.

?format=json
?format=md
?format=markdown
Accept: text/markdown

Collections always return JSON. Single-resource Markdown behaves as follows:

curl "$IT_BASE/workspaces/$IT_WS/items/TSK-00001?format=md" \
  -H "Authorization: Bearer $IT_KEY"

curl "$IT_BASE/workspaces/$IT_WS/docs/DOC-A1B2C3?format=md" \
  -H "Authorization: Bearer $IT_KEY"

curl "$IT_BASE/workspaces/$IT_WS/docs/DOC-A1B2C3?format=md&view=raw" \
  -H "Authorization: Bearer $IT_KEY"

Ordinary JSON, Markdown, search, and file reads never return secret plaintext.

Concurrency, limits, and errors#

Structured responses include rev; applicable reads also return ETag. Send a previous revision with mutation requests to prevent overwriting newer changes:

If-Match: "42"

A stale value returns 412 REVISION_MISMATCH. Multi-file domain operations are atomic, including Item moves, relationship updates, cascading deletion cleanup, and Page promotion. The server also checks the current catalog revision before structured commits.

All writes use the versioned sync store and obey maxFileBytes, optional maxWorkspaceBytes, and the inline/blob threshold.

Errors use a flat JSON envelope:

{
  "error": "Item not found",
  "code": "NOT_FOUND",
  "details": { "id": "TSK-99999" }
}

details is optional. Duplicate stable IDs return 409 DUPLICATE_ID with the conflicting paths.

Removed v1 surface#

The legacy v1 API (/api/ext/v1/...) has been removed without backward compatibility. Any v1 path answers 410 GONE with code: API_VERSION_REMOVED and a successor link to the v2 OpenAPI document. All integrations must use /api/ext/v2/workspaces/{ws}/items and stable frontmatter IDs.

Tooling#

• Open /api-console for the interactive Scalar console.
• Import /api/ext/v2/openapi.json into an OpenAPI client.
• Download the Bruno collection, open it, select Local, and replace every placeholder with the stable IDs and credentials from your own test object. Keep real values in a private Bruno environment that is excluded from source control.