Developers on Harbor

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

The Harbor API is a standard REST API over HTTPS. Requests and responses are JSON. You authenticate with a personal access token (for your own scripts) or an OAuth app (for integrations other people install). There’s also a first-class command-line tool and an agent skill for your AI.

Base URL

All API requests go to:

https://app.harbor.my/api/v1

The API is versioned in the path (/api/v1). We’ll add new versions rather than break this one.

The Harbor CLI

Mon, 01 Jan 0001 00:00:00 +0000

harbor is a small, dependency-light Go binary that exposes the entire Harbor API as composable commands: notebooks, notes, hierarchical tags, full-text and OCR search, file attachments, sync, version history, trash, templates, reminders, public sharing, client-side encryption, and Evernote import/export. Every command takes --json, so it drops straight into a pipeline.

It’s open source: github.com/HarborMyNotes/harbor-cli (MIT).

Install

Homebrew (macOS & Linux)

The repo is its own tap:

brew tap HarborMyNotes/harbor https://github.com/HarborMyNotes/harbor-cli
brew install harbor

Update later with brew upgrade harbor.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Every API request is authenticated with a bearer token in the Authorization header:

curl https://app.harbor.my/api/v1/notes \
 -H "Authorization: Bearer $HARBOR_TOKEN"

There are two kinds of token, for two different jobs.

Personal access tokens

A personal access token (PAT) is a long-lived key that acts as you. Use one for your own scripts, a cron job, a CLI, or a one-off integration. Tokens start with hbp_ and are scoped to exactly the permissions you pick.

Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Every endpoint in the API reference follows these rules. They’re documented here once instead of on every page.

JSON and field names

Requests and responses are JSON (Content-Type: application/json).
JSON field names are snake_case — notebook_id, created_at, source_url.
The token endpoint additionally accepts application/x-www-form-urlencoded, per the OAuth 2.0 spec.

Timestamps

All timestamps are UTC epoch milliseconds (integers):

{ "created_at": 1752600000000, "updated_at": 1752600000000 }

To convert:

# bash / GNU date
date -u -d @1752600000 # seconds → readable

from datetime import datetime, timezone
datetime.fromtimestamp(1752600000000 / 1000, tz=timezone.utc)

new Date(1752600000000).toISOString();

The one exception is OAuth’s expires_in, which is a duration in seconds (again, per the OAuth spec).

Errors

Mon, 01 Jan 0001 00:00:00 +0000

Harbor uses conventional HTTP status codes and returns every error in a single JSON envelope, so you only have to handle one shape.

The error envelope

{
 "error": {
 "code": "validation_failed",
 "message": "The request was invalid.",
 "details": { "title": "is required" },
 "request_id": "req_01HX…"
 }
}

Field	Description
`code`	A stable, machine-readable identifier. Branch on this, not on the message.
`message`	Human-readable and safe to show a user. Internal errors never leak specifics.
`details`	Optional. Present mainly on validation errors as a field → message map.
`request_id`	Included when available, and always in the `X-Request-Id` response header.

Handling errors

Check the HTTP status first, then the code for anything you want to handle specifically: