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

Segmentation runs asynchronously on GPU workers, so the API is poll-based: you submit work, then poll a status endpoint 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? Use the resumable flow.)
2

Pick a model and submit a prediction

List models with GET /models, then POST /job/prediction with an image_id and a model_id. This returns a job_id.
3

Wait until the job completes

Poll GET /job/{job_id} until status is COMPLETED. The response then carries a segmentation_id.
4

Export the results

Download the segmentation as GeoJSON ROIs (GET /export/{segmentation_id}/rois.geojson), per-cell measurements (.../measurements.csv), or an ImageJ ROI archive (.../rois.zip).
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 16 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.