> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halfpagetechnologies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HalfPage API

> Run Cellpose cell segmentation on your microscopy images programmatically — upload an image, run a prediction, and export ROIs and measurements.

The **HalfPage API** runs [Cellpose](https://www.cellpose.org/)-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](/api-reference/openapi.json).

## Base URL

Every path in the [API reference](/api-reference) is relative to this base URL:

```
https://api.halfpagetechnologies.com/backend/api/v1
```

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:

```
Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

Keys are created in the HalfPage dashboard and cannot be minted through the API.
See [Authentication](/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.

<Steps>
  <Step title="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](/quickstart#large-files-the-resumable-upload).)
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`).
  </Step>
</Steps>

The [Quickstart](/quickstart) walks through this entire flow with copy-pasteable
`curl` and Python.

## Explore

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Upload → predict → export, end to end, with runnable code.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Create an API key and understand how key scoping works.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    All 10 endpoints, generated from the OpenAPI spec, with a live playground.
  </Card>

  <Card title="Using with AI agents" icon="robot" href="/ai-agents">
    Connect an agent via the hosted MCP server, `llms.txt`, and the OpenAPI spec.
  </Card>
</CardGroup>

## 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.