> ## 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. # Upload an image > Get a microscopy image into HalfPage. How the request is sent decides which of the two modes you get: **One request** — send `multipart/form-data` with a `file` part. The file is streamed to storage and converted before the response returns, so the returned `image` is already `ready` and its `id` can go straight into `POST /predict`. Simplest, and the right choice up to a few hundred MB. **Resumable** — send `application/json` with `{"name": ..., "size": ...}` instead of a file. No bytes are sent on this request; the response carries `upload` with presigned part URLs. PUT each chunk directly to its `url` (in part order), call `POST /upload/{image_id}/complete`, then poll `GET /upload/{image_id}` until `upload_status` is `ready`. Use this for large files or unreliable connections — an interrupted part can be retried on its own instead of restarting the whole transfer. Either way the image counts against your plan's storage cap, so both modes return `402` once that cap is reached. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/upload 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/upload: post: tags: - upload summary: Upload an image description: >- Get a microscopy image into HalfPage. How the request is sent decides which of the two modes you get: **One request** — send `multipart/form-data` with a `file` part. The file is streamed to storage and converted before the response returns, so the returned `image` is already `ready` and its `id` can go straight into `POST /predict`. Simplest, and the right choice up to a few hundred MB. **Resumable** — send `application/json` with `{"name": ..., "size": ...}` instead of a file. No bytes are sent on this request; the response carries `upload` with presigned part URLs. PUT each chunk directly to its `url` (in part order), call `POST /upload/{image_id}/complete`, then poll `GET /upload/{image_id}` until `upload_status` is `ready`. Use this for large files or unreliable connections — an interrupted part can be retried on its own instead of restarting the whole transfer. Either way the image counts against your plan's storage cap, so both modes return `402` once that cap is reached. operationId: upload_api_v1_upload_post requestBody: content: multipart/form-data: schema: properties: file: type: string format: binary description: The microscopy image to upload (TIFF). Up to 4 GB. type: object required: - file title: SingleRequestUpload description: >- Send the whole file in one request. The response returns the image already `ready`. application/json: schema: properties: name: type: string title: Name description: Filename or label for the image. examples: - sample.tif size: type: integer title: Size description: Exact total size of the file in bytes. examples: - 104857600 additional_info: additionalProperties: true type: object title: Additional Info description: Arbitrary JSON metadata to store alongside the image. type: object required: - name - size title: ResumableUploadRequest description: >- Open a resumable upload for a file you are about to send in parts. `size` must be the file's exact byte size — the part plan is computed from it. Deliberately free of enums and server-controlled fields so the JSON branch of `POST /upload` stays a flat, self-contained schema. example: name: sample.tif size: 104857600 required: true responses: '200': description: >- The file was stored (`upload` is `null`, the image is `ready`), or a resumable upload was opened (`upload` carries the presigned plan). content: application/json: schema: $ref: '#/components/schemas/UploadResult' '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: >- Image storage quota exceeded for your plan. Upgrade to store more images. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: >- You've reached your storage limit of 100 images. Upgrade to store 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 '413': description: The uploaded file exceeds the 4 GB size limit. '422': description: >- The `file` part is missing, or the JSON body is invalid (bad `name`/`size`). '501': description: >- A resumable upload was requested but storage does not support it (local dev only). security: - HTTPBearer: [] components: schemas: UploadResult: properties: success: type: boolean title: Success default: true image: $ref: '#/components/schemas/ImageStatusResponse' upload: anyOf: - $ref: '#/components/schemas/UploadPlan' - type: 'null' type: object required: - image title: UploadResult description: >- The image the pixels landed on (or will land on). After a single-request upload `upload` is `null` and `image.upload_status` is already `ready` — the `image.id` can go straight into `POST /predict`. After a resumable upload was opened, `upload` carries the presigned plan and `image.upload_status` is `uploading` until you complete it. 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. ImageStatusResponse: properties: id: type: string title: Id name: type: string title: Name upload_status: $ref: '#/components/schemas/UploadStatus' image_type: $ref: '#/components/schemas/ImageType' size: type: integer title: Size shape: anyOf: - items: type: integer type: array - type: 'null' title: Shape folder_id: anyOf: - type: string format: uuid - type: 'null' title: Folder Id created_at: type: string format: date-time title: Created At processed_at: anyOf: - type: string format: date-time - type: 'null' title: Processed At upload_error: anyOf: - type: string - type: 'null' title: Upload Error type: object required: - id - name - upload_status - image_type - size - created_at title: ImageStatusResponse description: |- An image's upload lifecycle and metadata — enough to know when a freshly uploaded image is `ready` to run a prediction against. examples: - created_at: '2026-07-01T12:00:00Z' id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 image_type: TIFF name: sample.tif processed_at: '2026-07-01T12:00:05Z' shape: - 512 - 512 - 3 size: 4194304 upload_status: ready UploadPlan: properties: upload_id: type: string title: Upload Id part_size: type: integer title: Part Size urls: items: $ref: '#/components/schemas/PartUrlOut' type: array title: Urls type: object required: - upload_id - part_size - urls title: UploadPlan description: >- The presigned multipart plan: PUT each chunk of the file to its `url` (in part order), then call `POST /upload/{image_id}/complete` — no body needed, the server verifies the uploaded parts with storage directly. The internal storage object key is deliberately not exposed: the presigned `url`s already encode everything the client needs, and the key layout is a server-side implementation detail we keep off the public contract. examples: - part_size: 33554432 upload_id: 2~aBcD3fGhIjKlMnOpQrStUvWxYz urls: - part_number: 1 url: https://halfpage.s3.amazonaws.com/...&partNumber=1 - part_number: 2 url: https://halfpage.s3.amazonaws.com/...&partNumber=2 UploadStatus: type: string enum: - uploading - processing - ready - failed title: UploadStatus description: >- Lifecycle of a resumable S3 multipart image upload. uploading -> row created, bytes still being PUT directly to S3 processing -> object landed in S3, backend is converting it off the event loop ready -> conversion done, `shape` populated, image is usable failed -> aborted or conversion failed (orphan-sweep cron will reap it) ImageType: type: string enum: - TIFF title: ImageType PartUrlOut: properties: part_number: type: integer title: Part Number url: type: string title: Url type: object required: - part_number - url title: PartUrlOut securitySchemes: HTTPBearer: type: http scheme: bearer ````