Import & Export API

{
  "id": "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f",
  "kind": "enex",
  "status": "running",
  "filename": "Contractors.enex",
  "total_bytes": 1073741824,
  "created_at": 1784131100000,
  "total_notes": 120,
  "imported_notes": 38,
  "skipped_notes": 0,
  "failed_notes": 0,
  "failure_reason": "",
  "errors": [],
  "updated_at": 1784131200000
}

curl https://app.harbor.my/api/v1/import/enex/uploads \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"total_bytes": 1073741824, "filename": "Contractors.enex"}'

{
  "data": {
    "import_job_id": "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f",
    "status": "awaiting_upload",
    "part_size": 67108864,
    "part_count": 16
  }
}

curl https://app.harbor.my/api/v1/import/enex/uploads/0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f/parts \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"part_numbers": [1, 2, 3]}'

{
  "data": {
    "parts": [
      { "part_number": 1, "url": "https://storage.example.com/cache/imports/..." }
    ],
    "expires_in_seconds": 21600
  }
}

curl https://app.harbor.my/api/v1/import/enex/uploads/0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f/complete \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parts": [{"part_number": 1, "etag": "9b2cf535f27731c974343645a3985328"}]}'

{
  "data": {
    "import_job_id": "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f",
    "status": "queued",
    "total_notes": 0,
    "imported_notes": 0,
    "skipped_notes": 0,
    "failed_notes": 0
  }
}

curl -X POST https://app.harbor.my/api/v1/import/enex/uploads/0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f/abort \
  -H "Authorization: Bearer $HARBOR_TOKEN"

BASE=https://app.harbor.my/api/v1
FILE=Contractors.enex
BYTES=$(wc -c < "$FILE")

# 1. Create — returns the job id and the chunking plan.
CREATED=$(curl -s "$BASE/import/enex/uploads" \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"total_bytes\": $BYTES, \"filename\": \"$FILE\"}")

JOB=$(echo "$CREATED" | jq -r .data.import_job_id)
PART_SIZE=$(echo "$CREATED" | jq -r .data.part_size)
PART_COUNT=$(echo "$CREATED" | jq -r .data.part_count)

# 2 & 3. Presign in batches of 1000 (the server's per-call maximum), then PUT
#        each slice, keeping the ETag the storage returns.
ETAGS="[]"
FROM=1
while [ "$FROM" -le "$PART_COUNT" ]; do
  TO=$(( FROM + 999 )); [ "$TO" -gt "$PART_COUNT" ] && TO=$PART_COUNT
  NUMBERS=$(seq "$FROM" "$TO" | jq -s .)

  URLS=$(curl -s "$BASE/import/enex/uploads/$JOB/parts" \
    -H "Authorization: Bearer $HARBOR_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"part_numbers\": $NUMBERS}" | jq -c '.data.parts[]')

  for P in $URLS; do
    N=$(echo "$P" | jq -r .part_number)
    URL=$(echo "$P" | jq -r .url)
    dd if="$FILE" bs="$PART_SIZE" skip=$((N - 1)) count=1 2>/dev/null > part.bin
    ETAG=$(curl -s -X PUT --data-binary @part.bin "$URL" -D - -o /dev/null \
      | tr -d '\r' | sed -n 's/^[Ee][Tt]ag: *//p' | tr -d '"')
    ETAGS=$(echo "$ETAGS" | jq -c ". + [{\"part_number\": $N, \"etag\": \"$ETAG\"}]")
  done
  FROM=$(( TO + 1 ))
done
rm -f part.bin

# 4. Complete, then poll.
curl -s "$BASE/import/enex/uploads/$JOB/complete" \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"parts\": $ETAGS}" > /dev/null

curl -s "$BASE/import/enex/$JOB" -H "Authorization: Bearer $HARBOR_TOKEN" | jq .data

import os, time, requests

BASE = "https://app.harbor.my/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['HARBOR_TOKEN']}"}
PATH = "Contractors.enex"

created = requests.post(
    f"{BASE}/import/enex/uploads",
    headers=HEADERS,
    json={"total_bytes": os.path.getsize(PATH), "filename": os.path.basename(PATH)},
).json()["data"]

job, part_size, part_count = (
    created["import_job_id"], created["part_size"], created["part_count"]
)

etags = []
with open(PATH, "rb") as fh:
    # Presign in batches of 1000 — the server's per-call maximum.
    for start in range(1, part_count + 1, 1000):
        numbers = list(range(start, min(start + 1000, part_count + 1)))
        parts = requests.post(
            f"{BASE}/import/enex/uploads/{job}/parts",
            headers=HEADERS,
            json={"part_numbers": numbers},
        ).json()["data"]["parts"]

        for part in parts:
            # Read one slice at a time; never load the whole export.
            fh.seek((part["part_number"] - 1) * part_size)
            put = requests.put(part["url"], data=fh.read(part_size))
            put.raise_for_status()
            # The ETag is the only proof the part landed. Keep every one.
            etags.append({
                "part_number": part["part_number"],
                "etag": put.headers["ETag"].strip('"'),
            })

requests.post(
    f"{BASE}/import/enex/uploads/{job}/complete", headers=HEADERS, json={"parts": etags}
).raise_for_status()

while True:
    j = requests.get(f"{BASE}/import/enex/{job}", headers=HEADERS).json()["data"]
    if j["status"] in ("completed", "partial", "failed", "aborted"):
        print(j["status"], j.get("failure_reason", ""), j["imported_notes"])
        break
    time.sleep(5)

import { open, stat } from "node:fs/promises";

const BASE = "https://app.harbor.my/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.HARBOR_TOKEN}`,
  "Content-Type": "application/json",
};
const PATH = "Contractors.enex";

const { size } = await stat(PATH);
const created = await (await fetch(`${BASE}/import/enex/uploads`, {
  method: "POST",
  headers,
  body: JSON.stringify({ total_bytes: size, filename: PATH }),
})).json();

const { import_job_id: job, part_size: partSize, part_count: partCount } = created.data;

const fh = await open(PATH, "r");
const etags = [];

for (let start = 1; start <= partCount; start += 1000) {
  const numbers = [];
  for (let n = start; n < Math.min(start + 1000, partCount + 1); n++) numbers.push(n);

  const presigned = await (await fetch(`${BASE}/import/enex/uploads/${job}/parts`, {
    method: "POST",
    headers,
    body: JSON.stringify({ part_numbers: numbers }),
  })).json();

  for (const part of presigned.data.parts) {
    // One slice at a time — the whole export never sits in memory.
    const buf = Buffer.alloc(partSize);
    const { bytesRead } = await fh.read(buf, 0, partSize, (part.part_number - 1) * partSize);
    const put = await fetch(part.url, { method: "PUT", body: buf.subarray(0, bytesRead) });
    if (!put.ok) throw new Error(`part ${part.part_number}: ${put.status}`);
    // Keep the ETag from every PUT; complete is rejected without them.
    etags.push({ part_number: part.part_number, etag: put.headers.get("etag").replaceAll('"', "") });
  }
}
await fh.close();

await fetch(`${BASE}/import/enex/uploads/${job}/complete`, {
  method: "POST",
  headers,
  body: JSON.stringify({ parts: etags }),
});

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

const base = "https://app.harbor.my/api/v1"

func main() {
	token := os.Getenv("HARBOR_TOKEN")
	path := "Contractors.enex"

	fi, err := os.Stat(path)
	if err != nil {
		panic(err)
	}

	// 1. Create the upload and read back the chunking plan.
	var created struct {
		Data struct {
			ImportJobID string `json:"import_job_id"`
			PartSize    int64  `json:"part_size"`
			PartCount   int    `json:"part_count"`
		} `json:"data"`
	}
	post(token, base+"/import/enex/uploads", map[string]any{
		"total_bytes": fi.Size(),
		"filename":    path,
	}, &created)

	job, partSize, partCount := created.Data.ImportJobID, created.Data.PartSize, created.Data.PartCount

	f, err := os.Open(path)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	type etag struct {
		PartNumber int    `json:"part_number"`
		ETag       string `json:"etag"`
	}
	var etags []etag
	buf := make([]byte, partSize)

	// 2 & 3. Presign in batches of 1000, then PUT each slice.
	for start := 1; start <= partCount; start += 1000 {
		var numbers []int
		for n := start; n < min(start+1000, partCount+1); n++ {
			numbers = append(numbers, n)
		}

		var presigned struct {
			Data struct {
				Parts []struct {
					PartNumber int    `json:"part_number"`
					URL        string `json:"url"`
				} `json:"parts"`
			} `json:"data"`
		}
		post(token, fmt.Sprintf("%s/import/enex/uploads/%s/parts", base, job),
			map[string]any{"part_numbers": numbers}, &presigned)

		for _, p := range presigned.Data.Parts {
			// Read one slice; the export is never held in memory whole.
			n, err := f.ReadAt(buf, int64(p.PartNumber-1)*partSize)
			if err != nil && err != io.EOF {
				panic(err)
			}
			req, _ := http.NewRequest(http.MethodPut, p.URL, bytes.NewReader(buf[:n]))
			res, err := http.DefaultClient.Do(req)
			if err != nil {
				panic(err)
			}
			res.Body.Close()
			if res.StatusCode >= 300 {
				panic(fmt.Sprintf("part %d: %s", p.PartNumber, res.Status))
			}
			// The ETag proves the part landed. Complete is rejected without it.
			etags = append(etags, etag{p.PartNumber, strings.Trim(res.Header.Get("ETag"), `"`)})
		}
	}

	// 4. Complete — the import is enqueued and you poll it from here.
	post(token, fmt.Sprintf("%s/import/enex/uploads/%s/complete", base, job),
		map[string]any{"parts": etags}, nil)
	fmt.Println("import job:", job)
}

// post sends a JSON body to the Harbor API and decodes the reply into out,
// which may be nil when the caller does not need it.
func post(token, url string, body any, out any) {
	b, _ := json.Marshal(body)
	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewReader(b))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("%s: %s %s", url, res.Status, msg))
	}
	if out != nil {
		json.NewDecoder(res.Body).Decode(out)
	}
}

curl https://app.harbor.my/api/v1/import/enex/0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f \
  -H "Authorization: Bearer $HARBOR_TOKEN"

{
  "data": {
    "id": "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f",
    "kind": "enex",
    "status": "partial",
    "filename": "Contractors.enex",
    "total_bytes": 1073741824,
    "total_notes": 12,
    "imported_notes": 11,
    "skipped_notes": 0,
    "failed_notes": 1,
    "failure_reason": "",
    "errors": [
      { "note_index": 7, "title": "Broken note", "reason": "attachment_unreadable" }
    ],
    "created_at": 1784131100000,
    "updated_at": 1784131200000
  }
}

import os
import time
import requests

BASE = "https://app.harbor.my/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['HARBOR_TOKEN']}"}

job_id = "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f"

# Poll until the job reaches a terminal status.
while True:
    job = requests.get(f"{BASE}/import/enex/{job_id}", headers=HEADERS).json()["data"]
    print(f"{job['status']}: {job['imported_notes']}/{job['total_notes']}")
    if job["status"] not in ("queued", "running"):
        break
    time.sleep(2)

for e in job["errors"]:
    print(f"note {e['note_index']} ({e['title']}): {e['reason']}")

const BASE = "https://app.harbor.my/api/v1";
const headers = { Authorization: `Bearer ${process.env.HARBOR_TOKEN}` };

const jobId = "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f";

// Poll until the job reaches a terminal status.
let job;
do {
  const res = await fetch(`${BASE}/import/enex/${jobId}`, { headers });
  job = (await res.json()).data;
  console.log(`${job.status}: ${job.imported_notes}/${job.total_notes}`);
  if (job.status === "queued" || job.status === "running") {
    await new Promise((r) => setTimeout(r, 2000));
  }
} while (job.status === "queued" || job.status === "running");

for (const e of job.errors) {
  console.log(`note ${e.note_index} (${e.title}): ${e.reason}`);
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

const base = "https://app.harbor.my/api/v1"

func main() {
	token := os.Getenv("HARBOR_TOKEN")
	jobID := "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f"

	// Poll until the job reaches a terminal status.
	for {
		req, _ := http.NewRequest("GET", base+"/import/enex/"+jobID, nil)
		req.Header.Set("Authorization", "Bearer "+token)

		res, err := http.DefaultClient.Do(req)
		if err != nil {
			panic(err)
		}

		var out struct {
			Data struct {
				Status        string `json:"status"`
				TotalNotes    int    `json:"total_notes"`
				ImportedNotes int    `json:"imported_notes"`
				FailedNotes   int    `json:"failed_notes"`
			} `json:"data"`
		}
		json.NewDecoder(res.Body).Decode(&out)
		res.Body.Close()

		j := out.Data
		fmt.Printf("%s: %d/%d\n", j.Status, j.ImportedNotes, j.TotalNotes)
		if j.Status != "queued" && j.Status != "running" {
			break
		}
		time.Sleep(2 * time.Second)
	}
}

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

{
  "data": [
    {
      "id": "0f9c2b1e-7c4d-4b8a-9e2f-3a5d6c8b0e1f",
      "kind": "enex",
      "status": "running",
      "filename": "Contractors.enex",
      "total_bytes": 1073741824,
      "total_notes": 120,
      "imported_notes": 38,
      "skipped_notes": 0,
      "failed_notes": 0,
      "failure_reason": "",
      "errors": [],
      "created_at": 1784131100000,
      "updated_at": 1784131200000
    }
  ]
}

# Export a whole notebook, attachments included.
curl https://app.harbor.my/api/v1/export/enex \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook_id": "5b1f2c9a-8d3e-4f6a-b1c2-7e9d0a4f5b6c", "include_resources": true}' \
  -o notebook.enex

# Export a hand-picked selection of notes.
curl https://app.harbor.my/api/v1/export/enex \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note_ids": ["a3d81c47-2e6f-4b90-8c15-d94e7f2a6b03"], "include_resources": true}' \
  -o notes.enex