> ## 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. # Run a prediction > Start an asynchronous segmentation of a ready image. Returns immediately with a `prediction_id`; the segmentation itself runs on a GPU worker. Poll `GET /predict/{prediction_id}` until `status` is `COMPLETED`, then read `segmentation_id` off that response and hand it to the `/export/*` endpoints. Each run counts against your plan's monthly analysis quota (`402` when exceeded). The `image_id` and `model_id` are org-scoped: an id outside your organization returns `404`. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/predict openapi: 3.1.0 info: title: HalfPage API description: > The **HalfPage API** runs Cellpose-based cell segmentation on your microscopy images programmatically — upload an image, run a prediction, and export the resulting cell masks, ROIs, and measurements. ## Base URL ``` https://api.halfpagetechnologies.com/backend/api/v1 ``` Every path in this reference is relative to that base URL. A staging environment is available at `https://staging-api.halfpagetechnologies.com/backend/api/v1`. ## Authentication Authenticate every request with an API key in the `Authorization` header as a bearer token: ``` Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxx ``` Create and manage keys from the **API Keys** section of the HalfPage dashboard — keys cannot be minted through the API. A key is scoped to the organization that owns it; every resource you create or read is confined to that organization. Requests without a valid key receive `401`; a valid key used against an endpoint outside the public product surface receives `403`. ## Core workflow Three steps — **upload, predict, export** — plus a model list to choose from. Segmentation runs asynchronously on GPU workers, so step 2 is poll-based: 1. **Upload an image** (`POST /upload`) as `multipart/form-data` with a `file` part. One call: the image record is created for you and the response returns it already `ready`, with the `image.id` for the next step. *(Large file or flaky connection? POST the same endpoint as `application/json` with `{"name": ..., "size": ...}` instead. You get back presigned part URLs — PUT the chunks, call `POST /upload/{image_id}/complete`, then poll `GET /upload/{image_id}` until `upload_status` is `ready`.)* 2. **Pick a model** (`GET /models`) and **run a prediction** (`POST /predict`) with the `image_id` and a `model_id`. That returns a `prediction_id`; poll `GET /predict/{prediction_id}` until `status` is `COMPLETED`. The response then carries a `segmentation_id` and the `cell_count` detected. 3. **Export** that segmentation as CSV measurements (`GET /export/{segmentation_id}/measurements.csv`), GeoJSON ROIs (`.../rois.geojson`), or an ImageJ ROI archive (`.../rois.zip`). ## 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. version: 1.0.0 servers: - url: https://api.halfpagetechnologies.com/backend description: Production - url: https://staging-api.halfpagetechnologies.com/backend description: Staging security: [] tags: - name: upload description: >- Get microscopy images into HalfPage, and manage them once they are there. `POST /upload` is the only way in and covers both modes: send `multipart/form-data` with a `file` part to upload in one request (the image comes back `ready`), or send `application/json` with `{name, size}` to open a resumable upload and get presigned part URLs back. Resumable uploads finish with `complete` (no ETag bookkeeping needed) and are polled until `ready`. - name: predict description: >- Run segmentation on a ready image and poll it to completion. `POST /predict` queues the run on a GPU worker and returns a `prediction_id`; `GET /predict/{prediction_id}` reports progress and, once `COMPLETED`, the `segmentation_id` and cell count of the result. - name: export description: >- Download a completed segmentation in analysis-ready formats: a CSV of per-cell measurements, a GeoJSON of ROI polygons, or a ZIP of ImageJ-compatible ROIs. The CSV endpoint accepts a `columns` parameter to narrow the output to the measurements you care about. - name: models description: >- List the segmentation models available to your organization — the shared public base models (e.g. `cpsam`) plus any custom models trained in the dashboard — to choose a `model_id` for a prediction. paths: /api/v1/predict: post: tags: - predict summary: Run a prediction description: >- Start an asynchronous segmentation of a ready image. Returns immediately with a `prediction_id`; the segmentation itself runs on a GPU worker. Poll `GET /predict/{prediction_id}` until `status` is `COMPLETED`, then read `segmentation_id` off that response and hand it to the `/export/*` endpoints. Each run counts against your plan's monthly analysis quota (`402` when exceeded). The `image_id` and `model_id` are org-scoped: an id outside your organization returns `404`. operationId: create_prediction_api_v1_predict_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PredictRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PredictionAccepted' '400': description: You already have a running job — wait for it to finish. '401': description: >- Missing or invalid credentials. Supply a valid `Authorization: Bearer hp_live_...` API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Requires authentication '402': description: >- Monthly analysis quota exceeded for your plan. Upgrade to run more analyses. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: >- You've reached your monthly analysis limit. Upgrade to run more. '404': description: The resource does not exist, or is not in your organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Image with id 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found '410': description: >- The selected model's weights have been cleaned up — retrain to recover. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: PredictRequest: properties: image_id: type: string title: Image Id examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 model_id: type: string title: Model Id examples: - c0ffee00-1234-5678-9abc-def012345678 type: object required: - image_id - model_id title: PredictRequest description: >- Run a model over one uploaded image. `image_id` must be `ready` (see `GET /upload/{image_id}`) and `model_id` must be one of the ids returned by `GET /models`. PredictionAccepted: properties: prediction_id: type: string title: Prediction Id examples: - b1e5c7d2-9a4f-4c3b-8e2d-1f6a7b8c9d0e status: type: string enum: - submitted - skipped title: Status reason: anyOf: - type: string - type: 'null' title: Reason description: Why an identical prediction was skipped, when `status` is `skipped`. type: object required: - prediction_id - status title: PredictionAccepted description: >- Acknowledgement that a prediction was queued. `status` is `submitted` for a fresh run, or `skipped` when an identical prediction is already in flight — in both cases `prediction_id` is the one to poll. ErrorResponse: properties: detail: type: string title: Detail examples: - Job with id 11111111-1111-1111-1111-111111111111 not found type: object required: - detail title: ErrorResponse description: |- The body returned for a handled error: a single human-readable ``detail`` string. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````