Skip to main content
The HalfPage API runs Cellpose-based cell segmentation on your microscopy images programmatically. Upload an image, run a prediction against a segmentation model, and export the resulting cell masks as ROIs and per-cell measurements — no browser required. The API is designed for scripts, pipelines, and AI agents. Every endpoint is scoped to the organization that owns your API key, and the whole surface is described by a single OpenAPI document.

​
Base URL

Every path in the API reference is relative to this base URL:
A staging environment is available at https://staging-api.halfpagetechnologies.com/backend/api/v1.

​
Authentication

Authenticate every request with an API key as a bearer token:
Keys are created in the HalfPage dashboard and cannot be minted through the API. See Authentication for how to create a key and how key scoping works.

​
How segmentation works

Three verbs — upload, predict, export. Segmentation runs asynchronously on GPU workers, so the middle step is poll-based: you submit work, then poll until the result is ready.
1

Upload an image

One call: POST /upload with the file as multipart/form-data. The image record is created for you and the response returns it already ready, with the image.id for the next step. (Large files? The same endpoint has a resumable mode.)
2

Pick a model and run a prediction

List models with GET /models, then POST /predict with an image_id and a model_id. This returns a prediction_id.
3

Wait for it to finish

Poll GET /predict/{prediction_id} until status is COMPLETED. The response then carries a segmentation_id and the cell_count detected.
4

Export the results

Download the segmentation as an overlay PNG (GET /export/{segmentation_id}/overlay.png), GeoJSON ROIs (.../rois.geojson), per-cell measurements (.../measurements.csv), or an ImageJ ROI archive (.../rois.zip). The overlay PNG is a presentation RGB image, not original TIFF bit depth or scientific metadata.
The Quickstart walks through this entire flow with copy-pasteable curl and Python.

​
Explore

Quickstart

Upload → predict → export, end to end, with runnable code.

Authentication

Create an API key and understand how key scoping works.

API reference

All 10 endpoints, generated from the OpenAPI spec, with a live playground.

Using with AI agents

Connect an agent via the hosted MCP server, llms.txt, and the OpenAPI spec.

​
Quotas

Uploads and analyses are metered against your plan. Exceeding your image storage cap or monthly analysis cap returns 402 with a human-readable detail explaining the limit — upgrade your plan to raise it.