Search & OCR API

{
  "error": {
    "code": "validation_failed",
    "message": "The request was invalid.",
    "details": {
      "meta": "expected meta:KEY or meta:KEY=VALUE, where KEY is 1-64 characters of A-Z, a-z, 0-9, '_' or '-'"
    }
  }
}

curl -G "https://app.harbor.my/api/v1/search" \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  --data-urlencode 'q=meta:album="Summer 2026" -meta:favorite=true' \
  --data-urlencode 'types=note'

curl -G "https://app.harbor.my/api/v1/search" \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  --data-urlencode 'q=budget tag:finance -draft created:day-30' \
  --data-urlencode 'types=note,attachment' \
  --data-urlencode 'limit=20'

{
  "data": [
    {
      "type": "note",
      "note_id": "9c2e7b10-4f6d-4a2e-9b1c-3d8e5f7a0c21",
      "notebook_id": "5b1f2c9a-8e3d-4b7f-a1c6-2f9d0e4b8a53",
      "title": "Quarterly plan",
      "snippet": "…the <em>budget</em> for Q3…",
      "highlights": ["budget"],
      "score": 8.42,
      "tags": ["finance", "planning"],
      "created_at": 1749000000000,
      "updated_at": 1750000000000
    },
    {
      "type": "attachment",
      "resource_id": "7d41e0c2-3b8a-4f19-a6d2-5c0e9b7f1a84",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "note_id": "9c2e7b10-4f6d-4a2e-9b1c-3d8e5f7a0c21",
      "note_title": "Quarterly plan",
      "notebook_id": "5b1f2c9a-8e3d-4b7f-a1c6-2f9d0e4b8a53",
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "filename": "Q3 Budget.xlsx",
      "snippet": "",
      "highlights": [],
      "score": 0,
      "has_coordinates": false,
      "match": "name",
      "created_at": 1749000000000,
      "updated_at": 1750000000000
    },
    {
      "type": "attachment",
      "resource_id": "0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40",
      "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "note_id": "9c2e7b10-4f6d-4a2e-9b1c-3d8e5f7a0c21",
      "note_title": "Quarterly plan",
      "notebook_id": "5b1f2c9a-8e3d-4b7f-a1c6-2f9d0e4b8a53",
      "mime": "application/pdf",
      "filename": "invoice.pdf",
      "snippet": "…total <em>budget</em> 12,500…",
      "highlights": ["budget"],
      "score": 3.07,
      "has_coordinates": true,
      "match": "text",
      "created_at": 1749000000000,
      "updated_at": 1750000000000
    }
  ],
  "paging": { "limit": 100, "offset": 0, "total": 3, "has_more": false }
}

import os
import requests

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

# Search notes and attachments: free text + tag + date-range operators.
resp = requests.get(
    f"{BASE}/search",
    headers=HEADERS,
    params={
        "q": "budget tag:finance -draft created:day-30",
        "types": "note,attachment",
        "limit": 20,
    },
)
resp.raise_for_status()

for hit in resp.json()["data"]:
    if hit["type"] == "note":
        print(f"note:       {hit['title']}  (score {hit['score']})")
    elif hit.get("match") == "name":
        # Found by its file name: no snippet, nothing to highlight.
        print(f"file name:  {hit['filename']} in \"{hit['note_title']}\"")
    else:
        # Attachment hit — a match on the words inside a file.
        print(f"attachment: {hit['filename']} in \"{hit['note_title']}\"")
        if hit["has_coordinates"]:
            print("            has word boxes — /search/coordinates works")

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

// Search notes and attachments: free text + tag + date-range operators.
const params = new URLSearchParams({
  q: "budget tag:finance -draft created:day-30",
  types: "note,attachment",
  limit: "20",
});

const res = await fetch(`${BASE}/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HARBOR_TOKEN}` },
});
if (!res.ok) throw new Error(`search failed: ${res.status}`);

const { data, paging } = await res.json();
for (const hit of data) {
  if (hit.type === "note") {
    console.log(`note:       ${hit.title} (score ${hit.score})`);
  } else if (hit.match === "name") {
    // Found by its file name: no snippet, nothing to highlight.
    console.log(`file name:  ${hit.filename} in "${hit.note_title}"`);
  } else {
    console.log(`attachment: ${hit.filename} in "${hit.note_title}"`);
  }
}
console.log(`${paging.total} total, has_more=${paging.has_more}`);

package main

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

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

// searchHit is the subset of hit fields this example prints.
type searchHit struct {
	Type           string  `json:"type"`
	Title          string  `json:"title"`
	Filename       string  `json:"filename"`
	NoteTitle      string  `json:"note_title"`
	Score          float64 `json:"score"`
	HasCoordinates bool    `json:"has_coordinates"`
	Match          string  `json:"match"`
}

func main() {
	// Search notes and attachments: free text + tag + date-range operators.
	params := url.Values{}
	params.Set("q", "budget tag:finance -draft created:day-30")
	params.Set("types", "note,attachment")
	params.Set("limit", "20")

	req, err := http.NewRequest("GET", base+"/search?"+params.Encode(), nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("HARBOR_TOKEN"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data []searchHit `json:"data"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		panic(err)
	}

	for _, hit := range out.Data {
		if hit.Type == "note" {
			fmt.Printf("note:       %s (score %.2f)\n", hit.Title, hit.Score)
		} else if hit.Match == "name" {
			// Found by its file name: no snippet, nothing to highlight.
			fmt.Printf("file name:  %s in %q\n", hit.Filename, hit.NoteTitle)
		} else {
			fmt.Printf("attachment: %s in %q\n", hit.Filename, hit.NoteTitle)
		}
	}
}

curl -G "https://app.harbor.my/api/v1/search/coordinates" \
  -H "Authorization: Bearer $HARBOR_TOKEN" \
  --data-urlencode 'resource_id=0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40' \
  --data-urlencode 'q=budget "q3 plan"'

{
  "data": {
    "resource_id": "0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40",
    "mime": "application/pdf",
    "page_count": 3,
    "terms": ["budget", "q3 plan"],
    "pages": [
      {
        "page": 0,
        "page_width": 1700,
        "page_height": 2200,
        "matches": [
          {
            "term": "budget",
            "word": "Budget",
            "word_index": 42,
            "box": { "x": 510.0, "y": 880.0, "w": 120.0, "h": 28.0 },
            "norm": { "x": 0.3, "y": 0.4, "w": 0.0706, "h": 0.0127 },
            "confidence": 0.98
          }
        ],
        "phrases": [
          {
            "phrase": "q3 plan",
            "word_indexes": [43, 44],
            "boxes": [
              { "x": 640.0, "y": 880.0, "w": 70.0, "h": 28.0 },
              { "x": 716.0, "y": 880.0, "w": 90.0, "h": 28.0 }
            ],
            "norm_union": { "x": 0.376, "y": 0.4, "w": 0.0976, "h": 0.0127 }
          }
        ]
      }
    ],
    "truncated": false
  }
}

import os
import requests

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

# Fetch OCR highlight boxes for one attachment (a has_coordinates hit).
resp = requests.get(
    f"{BASE}/search/coordinates",
    headers=HEADERS,
    params={
        "resource_id": "0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40",
        "q": 'budget "q3 plan"',
    },
)
if resp.status_code == 409:
    print("OCR still running — try again shortly")
    raise SystemExit(1)
resp.raise_for_status()

data = resp.json()["data"]
for page in data["pages"]:
    for m in page["matches"]:
        # `norm` is always present — scale it to your rendered page size.
        n = m["norm"]
        print(f"page {page['page']}: '{m['word']}' at "
              f"x={n['x']:.3f} y={n['y']:.3f} w={n['w']:.3f} h={n['h']:.3f}")
    for ph in page["phrases"]:
        u = ph["norm_union"]
        print(f"page {page['page']}: phrase '{ph['phrase']}' union "
              f"x={u['x']:.3f} y={u['y']:.3f}")
if data["truncated"]:
    print("output clipped by max_boxes — raise it for more")

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

// Fetch OCR highlight boxes for one attachment (a has_coordinates hit).
const params = new URLSearchParams({
  resource_id: "0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40",
  q: 'budget "q3 plan"',
});

const res = await fetch(`${BASE}/search/coordinates?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HARBOR_TOKEN}` },
});
if (res.status === 409) throw new Error("OCR still running — try again shortly");
if (!res.ok) throw new Error(`coordinates failed: ${res.status}`);

const { data } = await res.json();
for (const page of data.pages) {
  for (const m of page.matches) {
    // `norm` is always present — scale it to your rendered page size
    // to place the yellow highlight at any zoom level.
    const { x, y, w, h } = m.norm;
    console.log(`page ${page.page}: "${m.word}" at ${x},${y} (${w}×${h})`);
  }
  for (const ph of page.phrases) {
    console.log(`page ${page.page}: phrase "${ph.phrase}"`, ph.norm_union);
  }
}

package main

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

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

// rect is a normalized or pixel rectangle from the coordinates payload.
type rect struct {
	X, Y, W, H float64
}

// coordPage is one page entry with its word matches and phrase spans.
type coordPage struct {
	Page    int `json:"page"`
	Matches []struct {
		Term      string `json:"term"`
		Word      string `json:"word"`
		WordIndex int    `json:"word_index"`
		Norm      rect   `json:"norm"`
	} `json:"matches"`
	Phrases []struct {
		Phrase    string `json:"phrase"`
		NormUnion rect   `json:"norm_union"`
	} `json:"phrases"`
}

func main() {
	// Fetch OCR highlight boxes for one attachment (a has_coordinates hit).
	params := url.Values{}
	params.Set("resource_id", "0f9c2b1e-6a4d-4e8b-9c2f-1b7a3d5e8f40")
	params.Set("q", `budget "q3 plan"`)

	req, err := http.NewRequest("GET", base+"/search/coordinates?"+params.Encode(), nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("HARBOR_TOKEN"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusConflict {
		fmt.Println("OCR still running — try again shortly")
		return
	}

	var out struct {
		Data struct {
			Pages     []coordPage `json:"pages"`
			Truncated bool        `json:"truncated"`
		} `json:"data"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		panic(err)
	}

	for _, page := range out.Data.Pages {
		for _, m := range page.Matches {
			// Norm is always present — scale it to your rendered page size.
			fmt.Printf("page %d: %q at %.3f,%.3f\n", page.Page, m.Word, m.Norm.X, m.Norm.Y)
		}
		for _, ph := range page.Phrases {
			fmt.Printf("page %d: phrase %q union at %.3f,%.3f\n",
				page.Page, ph.Phrase, ph.NormUnion.X, ph.NormUnion.Y)
		}
	}
}