Skip to content

API overview

The PoreStore API lets a script do the core of what a person does in the app: upload a 3D image, wait for it to be ingested, run an analysis on it, and read the result. It's a small, team-scoped JSON API over HTTPS, and every analysis the API exposes runs on the same solvers with the same settings as in the app; the User guide describes each tool and the Scientific reference what it computes. Some of the app isn't in the API yet; the list is below.

Until launch day

PoreStore hasn't launched yet. Until launch day, /api/v1/ may still change, including renames and removals. From launch day it only grows.

Base URL

Every endpoint lives under one team:

https://porestore.com/api/v1/teams/{team_id}/

{team_id} is your team's Team ID: the eight-character identifier shown in team settings. It never changes, even if you rename the team. The OpenAPI schema calls this path parameter team_slug. That's a historical name for the same value.

How the pieces fit

1. Upload the image2. Once the image is ready, run an analysisPOST /uploads/Object storagePOST /uploads/{id}/complete/GET /images/{id}/GET /analysis-types/POST /analysis-jobs/GET /analysis-jobs/{id}/GET /analysis-jobs/{id}/result/ presigned form202, processing202, pendingcompleted
The calls behind one analysis. Ingestion and analysis both return 202 at once; poll until the status settles.

Two parts of the API work asynchronously, and both follow the same pattern: the request returns 202 Accepted right away, and you poll a resource until its status settles.

  • Ingestion. Completing an upload creates an image with status: processing. PoreStore reads the file, checks it, converts it to its chunked storage and measures its basic properties. Then the image becomes ready or failed.
  • Analysis. Submitting a job sends it to a solver. The job goes through pending, queued and processing to completed, failed or cancelled: cancelled by you before it starts, or by PoreStore when it waits or runs far past its limits. Job states says what each one means.

The quickstart walks through the whole loop in about 60 lines of Python.

Endpoints

Method Path (under /api/v1/teams/{team_id}) What it does
POST /uploads/ Create a direct-to-storage upload session
POST /uploads/{upload_id}/complete/ Register the uploaded file and start ingestion
GET /images/ List the team's images
GET /images/{image_id}/ Get one image
DELETE /images/{image_id}/ Delete an image and its stored data, keeping its jobs and results
GET /analysis-types/ Discover the analyses available to you, with their parameter schemas
POST /analysis-jobs/ Submit a job
GET /analysis-jobs/ List the team's jobs
GET /analysis-jobs/{job_id}/ Get one job
GET /analysis-jobs/{job_id}/result/ Get a completed job's result

What the API doesn't do yet

The API runs one job on one image and returns its numbers. The app does more. This table lists what only the app does today. It isn't a plan or a promise of what comes next.

Capability In the app In the API
Batches: run an analysis on every image in a batch at once Yes, for most analyses Not in the API yet Submit one job per image. A .zip or .npz uploaded through the API is still grouped into a batch you can use in the app.
Workflows beta: save a set of analysis steps and run them together Yes Not in the API yet
Image operations: segmentation, trimming, cleaning, converting, mesh import and image export (VTK or STL), noise filtering, resizing and downsampling Yes Not in the API yet Prepare images before uploading them.
Downloads: saved fields, pore networks, reports and CSV tables Yes Not in the API yet A result's numbers come back as JSON.
Editing an image after upload: its name or voxel size Yes Not in the API yet Set name and voxel_size when you create the upload or complete it.
Creating and revoking API keys Yes, for team owners In the app. See Authentication.
Managing a team and its members Yes In the app.

Conventions

  • JSON in, JSON out. Send Content-Type: application/json on every POST. The one exception is the file upload itself, which goes to object storage as a multipart form.
  • Identifiers for images, uploads and jobs are UUIDs.
  • Timestamps are ISO 8601 with a UTC offset, for example 2026-10-10T14:03:22.418193+00:00.
  • Lists (/images/, /analysis-jobs/) return every item in one results array. They aren't paginated, and their order isn't guaranteed.
  • Results are stored in voxel units and come back in your image's physical units when it has a voxel size. See Units and voxel size.
  • Unknown fields and values may appear over time. Ignore fields you don't recognise, and don't treat an unknown status or analysis_type as an error.

Rate limits

Each API key, or each signed-in user in the browser, gets 3000 requests per hour. A request over the limit returns 429 with a Retry-After header. See Errors and retries.

Machine-readable schema

The full OpenAPI 3 document is rendered here and can be downloaded as JSON. Signed-in team members can also fetch the live copy from https://porestore.com/api/schema/.