Upload an image

curl --request POST \
  --url https://api.halfpagetechnologies.com/backend/api/v1/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://api.halfpagetechnologies.com/backend/api/v1/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.halfpagetechnologies.com/backend/api/v1/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.halfpagetechnologies.com/backend/api/v1/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.halfpagetechnologies.com/backend/api/v1/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.halfpagetechnologies.com/backend/api/v1/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.halfpagetechnologies.com/backend/api/v1/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "image": {
    "id": "<string>",
    "name": "<string>",
    "image_type": "TIFF",
    "size": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "shape": [
      123
    ],
    "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "processed_at": "2023-11-07T05:31:56Z",
    "upload_error": "<string>"
  },
  "success": true,
  "upload": {
    "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"
      }
    ]
  }
}

{
  "detail": "Requires authentication"
}

{
  "detail": "You've reached your storage limit of 100 images. Upgrade to store more."
}

{
  "detail": "Image with id 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found"
}

upload

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.

POST

api

upload

Upload an image

curl --request POST \
  --url https://api.halfpagetechnologies.com/backend/api/v1/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://api.halfpagetechnologies.com/backend/api/v1/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.halfpagetechnologies.com/backend/api/v1/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.halfpagetechnologies.com/backend/api/v1/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.halfpagetechnologies.com/backend/api/v1/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.halfpagetechnologies.com/backend/api/v1/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.halfpagetechnologies.com/backend/api/v1/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "image": {
    "id": "<string>",
    "name": "<string>",
    "image_type": "TIFF",
    "size": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "shape": [
      123
    ],
    "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "processed_at": "2023-11-07T05:31:56Z",
    "upload_error": "<string>"
  },
  "success": true,
  "upload": {
    "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"
      }
    ]
  }
}

{
  "detail": "Requires authentication"
}

{
  "detail": "You've reached your storage limit of 100 images. Upgrade to store more."
}

{
  "detail": "Image with id 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Send the whole file in one request. The response returns the image already ready.

file

required

The microscopy image to upload (TIFF). Up to 4 GB.

Response

The file was stored (upload is null, the image is ready), or a resumable upload was opened (upload carries the presigned plan).

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.

image

ImageStatusResponse · object

required

An image's upload lifecycle and metadata — enough to know when a freshly uploaded image is ready to run a prediction against.

Show child attributes

Example:

{
  "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"
}

success

boolean

default:true

upload

UploadPlan · object | null

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 urls already encode everything the client needs, and the key layout is a server-side implementation detail we keep off the public contract.

Show child attributes

Example:

{
  "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"
    }
  ]
}

upload

predict

export

models

Upload an image

Authorizations

Body

Response