Create an image record

curl --request POST \
  --url https://api.halfpagetechnologies.com/backend/api/v1/image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "size": 123,
  "image_type": "TIFF",
  "additional_info": {},
  "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resumable": false
}
'

import requests

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

payload = {
    "name": "<string>",
    "size": 123,
    "image_type": "TIFF",
    "additional_info": {},
    "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "resumable": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    size: 123,
    image_type: 'TIFF',
    additional_info: {},
    folder_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    resumable: false
  })
};

fetch('https://api.halfpagetechnologies.com/backend/api/v1/image', 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/image",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'size' => 123,
    'image_type' => 'TIFF',
    'additional_info' => [
        
    ],
    'folder_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'resumable' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/image"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/image")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}"

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

{
  "id": "3fa85f64",
  "name": "sample.tif",
  "upload_status": "uploading",
  "image_type": "TIFF",
  "size": 4194304,
  "created_at": "2026-07-16T12:00:00Z",
  "upload": {
    "upload_id": "2~aBcD3fGhIjKlMnOpQrStUvWxYz",
    "part_size": 33554432,
    "urls": [
      {
        "part_number": 1,
        "url": "https://halfpage.s3.amazonaws.com/...&partNumber=1"
      }
    ]
  }
}

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

image

Create an image record

Create an image record for the resumable upload flow.

Pass resumable: true to open the upload in the same call: the response then carries upload with presigned part URLs — PUT each chunk of your file to its URL, call POST /upload/{image_id}/complete, and poll GET /image/{image_id} until upload_status is ready.

(For files up to a few hundred MB the single-request POST /upload is simpler still — it creates the record for you and returns it ready.)

The image counts against your plan’s storage cap the moment it is created, so this returns 402 when the cap is reached — even before any bytes are uploaded.

POST

api

image

Create an image record

curl --request POST \
  --url https://api.halfpagetechnologies.com/backend/api/v1/image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "size": 123,
  "image_type": "TIFF",
  "additional_info": {},
  "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resumable": false
}
'

import requests

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

payload = {
    "name": "<string>",
    "size": 123,
    "image_type": "TIFF",
    "additional_info": {},
    "folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "resumable": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    size: 123,
    image_type: 'TIFF',
    additional_info: {},
    folder_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    resumable: false
  })
};

fetch('https://api.halfpagetechnologies.com/backend/api/v1/image', 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/image",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'size' => 123,
    'image_type' => 'TIFF',
    'additional_info' => [
        
    ],
    'folder_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'resumable' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/image"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/image")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"size\": 123,\n  \"image_type\": \"TIFF\",\n  \"additional_info\": {},\n  \"folder_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"resumable\": false\n}"

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

{
  "id": "3fa85f64",
  "name": "sample.tif",
  "upload_status": "uploading",
  "image_type": "TIFF",
  "size": 4194304,
  "created_at": "2026-07-16T12:00:00Z",
  "upload": {
    "upload_id": "2~aBcD3fGhIjKlMnOpQrStUvWxYz",
    "part_size": 33554432,
    "urls": [
      {
        "part_number": 1,
        "url": "https://halfpage.s3.amazonaws.com/...&partNumber=1"
      }
    ]
  }
}

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

application/json

The metadata for a new image record. The pixels are uploaded separately; size is the total byte size of the file you will upload. Set resumable to also receive the presigned upload plan in the same response. Server-controlled fields (id, created_by, organization_id, upload_status) are not accepted here.

name

string

required

Filename or label for the image.

Example:

"sample.tif"

size

integer

required

Total size of the image file in bytes.

Example:

4194304

image_type

enum<string>

default:TIFF

Image format. Only TIFF is currently supported.

Available options:

TIFF

additional_info

Additional Info · object

Arbitrary JSON metadata to store alongside the image.

folder_id

string<uuid> | null

Optional folder to place the image in; it must belong to your organization. API clients typically have no folders and omit this.

resumable

boolean

default:false

Set to true to also open a resumable upload in the same call: the response then carries upload with presigned part URLs sized for size (so size must be exact). PUT each chunk to its URL, then call POST /upload/{image_id}/complete — no separate /init call needed.

Response

The image record was created; upload the pixels next.

The created image record, plus — when resumable: true was requested — the presigned upload plan under upload (otherwise null).

string

required

name

string

required

upload_status

enum<string>

required

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)

Available options:

uploading,

processing,

ready,

failed

image_type

enum<string>

required

Available options:

TIFF

size

integer

required

created_at

string<date-time>

required

shape

integer[] | null

folder_id

string<uuid> | null

processed_at

string<date-time> | null

upload_error

string | null

upload

InitUploadResponse · object | null

The presigned multipart plan: PUT each chunk of the file to its url (in part order), then call /complete — no body needed, the server verifies the uploaded parts with storage directly.

The internal S3 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

job

image

segmentation

export

models

Create an image record

Authorizations

Body

Response