Quickstart

Upload a microscopy image, run a segmentation, and download the ROIs — end to end.

This walkthrough takes you through the full workflow with runnable curl and Python: upload an image (one call), run a prediction, wait for the job, and download the resulting ROIs as GeoJSON — entirely over the API.

Before you start

1. Get an API key

   Create one in the dashboard (Settings → API Keys) and export it:

   export HALFPAGE_API_KEY="hp_live_xxxxxxxxxxxxxxxxxxxxxxxx"
   export BASE="https://api.halfpagetechnologies.com/backend/api/v1"
   

   See Authentication for details.

2. Install tooling (for the bash examples)

   The curl snippets use jq to read JSON responses. The Python snippets use requests (pip install requests).

1. Upload your image

One request does everything: POST /upload streams the file in, creates the image record for you (named after the file), converts it, and returns the record already ready. No pre-registration, no polling.

curl

IMAGE_ID=$(curl -s -X POST "$BASE/upload" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -F "file=@image.tif" | jq -r .image.id)
echo "image: $IMAGE_ID"
# The returned image is already "ready" — no polling needed.

Each image counts against your plan’s storage cap; POST /upload returns 402 once the cap is reached. Files can be up to 4 GB, but for anything larger than a few hundred MB — or a connection that might drop — use the resumable upload below.

2. Pick a model and submit a prediction

List the models available to your organization, then submit a prediction job for your image. GET /models returns shared public base models (such as cpsam, the Cellpose-SAM generalist) alongside any custom models your org has trained.

curl

# Pick the public cpsam base model (or the first available model).
MODEL_ID=$(curl -s "$BASE/models" -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  | jq -r '(map(select(.name == "cpsam")) + .)[0].id')

# Submit the prediction. Returns a job_id to poll.
JOB_ID=$(curl -s -X POST "$BASE/job/prediction" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model_id\": \"$MODEL_ID\", \"image_id\": \"$IMAGE_ID\"}" | jq -r .job_id)
echo "job: $JOB_ID"

Each organization runs one job at a time. If you already have a job running, POST /job/prediction returns 400 — wait for it to finish. If an identical job is already queued, the response comes back with status: "skipped" and the existing job_id.

3. Wait until the job completes

Segmentation runs asynchronously on GPU workers, so poll GET /job/{job_id} until status is COMPLETED. The completed response carries the segmentation_id you’ll export.

curl

until [ "$(curl -s "$BASE/job/$JOB_ID" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" | jq -r .status)" = "COMPLETED" ]; do
  echo "segmenting..." && sleep 5
done
SEG_ID=$(curl -s "$BASE/job/$JOB_ID" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" | jq -r .segmentation_id)
echo "segmentation: $SEG_ID"

status moves through SUBMITTED → STARTED → COMPLETED (or FAILED).

4. Export the results

Download the segmentation in whichever analysis-ready format you need. GeoJSON is handy for GIS and web tools; the CSV is one row per cell; the ZIP is an ImageJ/FIJI ROI archive.

curl

# GeoJSON ROIs
curl -s "$BASE/export/$SEG_ID/rois.geojson" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o rois.geojson

# Per-cell measurements (CSV)
curl -s "$BASE/export/$SEG_ID/measurements.csv" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o measurements.csv

# ImageJ ROI archive (ZIP)
curl -s "$BASE/export/$SEG_ID/rois.zip" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o rois.zip

That’s the whole loop: upload → predict → complete → export. 🎉

Large files: the resumable upload

For multi-GB files or unreliable connections, upload the pixels straight to object storage in chunks instead of through the API. Create the record with resumable: true — the response includes presigned part URLs — then PUT each chunk to its URL and call /complete. If a chunk fails, just retry that PUT; nothing else is lost.

The presigned PUT requests go straight to object storage — do not send your Authorization header on them. All other calls are authenticated with your API key as usual.

curl

# a) Create the record AND get the presigned upload plan in one call.
CREATE=$(curl -s -X POST "$BASE/image" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"image.tif\", \"size\": $(wc -c < image.tif), \"resumable\": true}")
IMAGE_ID=$(jq -r .id <<< "$CREATE")
PART_SIZE=$(jq -r .upload.part_size <<< "$CREATE")

# b) Split the file into part_size chunks and PUT each to its presigned URL.
split -b "$PART_SIZE" image.tif hp_part_
i=0
for chunk in hp_part_*; do
  curl -sf -X PUT --data-binary "@$chunk" \
    "$(jq -r ".upload.urls[$i].url" <<< "$CREATE")" -o /dev/null
  i=$((i+1))
done

# c) Finish the upload — no body needed; the server verifies the parts itself.
curl -s -X POST "$BASE/upload/$IMAGE_ID/complete" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY"
# -> {"status": "processing"}

# d) Conversion runs asynchronously: poll until the image is ready.
until [ "$(curl -s "$BASE/image/$IMAGE_ID" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" | jq -r .upload_status)" = "ready" ]; do
  echo "converting..." && sleep 3
done
echo "image ready"

From here, continue at step 2 — everything downstream is identical.

The record counts against your storage cap from the moment it is created, and keeps counting until you delete it. If you abandon an upload, DELETE /image/{image_id} frees the slot (POST /upload/{image_id}/abort only discards the uploaded chunks and marks the record failed).

Full Python script

segment.py — the complete workflow in one file

import os
import time
import requests

BASE_URL = "https://api.halfpagetechnologies.com/backend/api/v1"
API_KEY = os.environ["HALFPAGE_API_KEY"]
FILE_PATH = "image.tif"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"


def upload_image(file_path: str) -> str:
    """One call: creates the record, uploads and converts the pixels, and
    returns the id of the ready-to-segment image."""
    with open(file_path, "rb") as f:
        upload = session.post(f"{BASE_URL}/upload", files={"file": f})
    upload.raise_for_status()
    return upload.json()["image"]["id"]


def predict(image_id: str) -> str:
    models = session.get(f"{BASE_URL}/models").json()
    model_id = next((m["id"] for m in models if m["name"] == "cpsam"), models[0]["id"])
    job = session.post(
        f"{BASE_URL}/job/prediction",
        json={"model_id": model_id, "image_id": image_id},
    ).json()
    job_id = job["job_id"]
    while True:
        status = session.get(f"{BASE_URL}/job/{job_id}").json()
        if status["status"] == "COMPLETED":
            return status["segmentation_id"]
        if status["status"] == "FAILED":
            raise RuntimeError("prediction job failed")
        time.sleep(5)


def export(segmentation_id: str, out_path: str = "rois.geojson") -> None:
    resp = session.get(f"{BASE_URL}/export/{segmentation_id}/rois.geojson")
    resp.raise_for_status()
    with open(out_path, "wb") as out:
        out.write(resp.content)


if __name__ == "__main__":
    image_id = upload_image(FILE_PATH)
    segmentation_id = predict(image_id)
    export(segmentation_id)
    print(f"done — wrote rois.geojson for segmentation {segmentation_id}")

Next steps

API reference

Every endpoint, parameter, and response — with a live playground.

Using with AI agents

Point an agent at the MCP server and OpenAPI spec to drive this flow for you.