OpenAPI reference¶

Every /api/v1/ endpoint, with its parameters, request body and responses, rendered from the machine-readable schema that the server generates. The endpoint guides explain how to use each one.

Download openapi.json

All endpoints live under https://porestore.com and authenticate with an Authorization: Api-Key <key> header (see Authentication).

Images and uploads¶

Create an upload session¶

POST/api/v1/teams/{team_slug}/uploads/

Returns a presigned form that uploads the file straight to object storage. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Request body (required, JSON): UploadSessionRequest

Responses

Status	Body	Notes
`201`	`UploadSession`

Complete an upload¶

POST/api/v1/teams/{team_slug}/uploads/{upload_id}/complete/

Registers the uploaded file as an image and starts ingesting it. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.
`upload_id`	path	string (uuid)	yes	The upload session's `id`, returned when the session was created.

Request body (required, JSON): UploadCompletionRequest

Responses

Status	Body	Notes
`202`	`Image`

List images¶

GET/api/v1/teams/{team_slug}/images/

Lists every image in the team. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`ImageList`

Get an image¶

GET/api/v1/teams/{team_slug}/images/{image_id}/

Returns one image, including its ingestion status. Guide →

Parameters

Name	In	Type	Required	Description
`image_id`	path	string (uuid)	yes	The image's `id`.
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`Image`

Delete an image¶

DELETE/api/v1/teams/{team_slug}/images/{image_id}/

Deletes an image and its stored data. Guide →

Parameters

Name	In	Type	Required	Description
`image_id`	path	string (uuid)	yes	The image's `id`.
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`204`	none

Analysis types¶

List analysis types¶

GET/api/v1/teams/{team_slug}/analysis-types/

Lists the analyses the team can run now, each with a JSON Schema for its parameters. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`AnalysisTypeList`

Analysis jobs¶

Submit a job¶

POST/api/v1/teams/{team_slug}/analysis-jobs/

Queues the analysis on a ready image. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.
`Idempotency-Key`	header	string	no	Optional team-scoped key (maximum 255 characters). An exact replay returns the original job; reusing it with a different request returns 409. Exact replays remain available after an analysis flag is disabled; a new submission must pass current availability.

Request body (required, JSON): AnalysisSubmissionRequest

Responses

Status	Body	Notes
`200`	`AnalysisJob`
`202`	`AnalysisJob`
`403`	`AnalysisUnavailableResponse`	An unavailable analysis returns error.code analysis_unavailable. 403 permission_denied is also used for a key that is not valid for a team the caller belongs to; a team the caller cannot access returns 404.

List jobs¶

GET/api/v1/teams/{team_slug}/analysis-jobs/

Lists every analysis job in the team. Guide →

Parameters

Name	In	Type	Required	Description
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`AnalysisJobList`

Get a job¶

GET/api/v1/teams/{team_slug}/analysis-jobs/{job_id}/

Returns one job, including its status and progress. Guide →

Parameters

Name	In	Type	Required	Description
`job_id`	path	string (uuid)	yes	The job's `id`.
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`AnalysisJob`

Cancel a job¶

POST/api/v1/teams/{team_slug}/analysis-jobs/{job_id}/cancel/

Cancels a job that hasn't started running. Guide →

Parameters

Name	In	Type	Required	Description
`job_id`	path	string (uuid)	yes	The job's `id`.
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`AnalysisJob`
`403`	`AnalysisUnavailableResponse`	An unavailable analysis returns error.code analysis_unavailable. 403 permission_denied is also used for a key that is not valid for a team the caller belongs to; a team the caller cannot access returns 404.
`409`	`JobCancelRefusedResponse`
`503`	`JobCancelRefusedResponse`

Get a result¶

GET/api/v1/teams/{team_slug}/analysis-jobs/{job_id}/result/

Returns a completed job's result, converted with the image's current voxel size. Guide →

Parameters

Name	In	Type	Required	Description
`job_id`	path	string (uuid)	yes	The job's `id`.
`team_slug`	path	string	yes	Your team's Team ID, shown in team settings and on the API keys page. The guides write it as `{team_id}`.

Responses

Status	Body	Notes
`200`	`AnalysisResult`

Schemas¶

The objects that the endpoints above send and receive.

AnalysisJob¶

Field	Type	Required	Description
`id`	string (uuid)	yes
`image_id`	string (uuid) or null	yes	The image the job ran on. Null once that image has been deleted.
`analysis_type`	string	yes
`status`	string	yes	`pending`, `queued`, `processing`, `completed`, `failed` or `cancelled`. A job is `queued` until its work starts running, and `processing` while it runs. New values may be added.
`queue_reason`	string or null	yes	While the job is `pending` or `queued`, why it waits, when known: `behind_other_jobs` (the workers that run it are busy) or `scarce_hardware` (the hardware it needs is in short supply, which can take minutes to hours; a job that cannot start in time to finish within a day fails). Null otherwise. New values may be added.
`parameters`	object	yes	The normalised parameters the job ran with, including defaults and routing fields.
`progress_percentage`	integer	yes	A coarse 0–100 indicator, not a run-time prediction.
`error_message`	string	yes	Why the job failed or was cancelled. Empty otherwise.
`created_at`	string (date-time)	yes
`started_at`	string (date-time) or null	yes	When the job was picked up to run.
`completed_at`	string (date-time) or null	yes	When the job finished.
`selected_compute_tier`	string or null	yes	The key of the compute tier the job ran on. Null for analyses without tiers.
`solver_converged`	boolean or null	yes	For iterative solvers, whether every convergence check passed. Null otherwise.
`solver_iterations_completed`	integer or null	yes	Iterations the solver ran.
`solver_wall_time_seconds`	number (double) or null	yes	Always null for customer keys; staff keys may receive provider telemetry.
`solver_convergence_telemetry`	object	yes	Per-check convergence history, where the solver reports it.
`solver_version`	string or null	yes	Version of the solver that produced the result.
`worker_image_tag`	string or null	yes	Provenance: the worker build that ran the job.
`worker_image_digest`	string or null	yes	Provenance: the exact worker image that ran the job.
`worker_application_revision`	string or null	yes	Provenance: the source revision of the worker that ran the job.
`compute_hardware`	string or null	yes	Provenance: the GPU or CPU the job ran on, such as `NVIDIA A40`.

AnalysisJobList¶

Field	Type	Required
`results`	array of `AnalysisJob`	yes

AnalysisResult¶

Field	Type	Required	Description
`job_id`	string (uuid)	yes
`metrics`	object	yes	The result. Its `solution` holds the analysis's outputs in the image's units.

AnalysisSubmissionRequest¶

Field	Type	Required	Description
`analysis_type`	`AnalysisTypeEnum`	yes
`image_id`	string (uuid)	yes	A `ready` image in this team.
`parameters`	object	yes	Validated against the analysis's `parameters_schema` from List analysis types.

AnalysisType¶

Field	Type	Required	Description
`slug`	string	yes	The `analysis_type` to send when submitting.
`label`	string	yes	Human-readable name.
`contract_version`	integer	yes	Version of the analysis's input and output contract.
`expected_duration_seconds`	integer	yes	A typical run time. A job still running after twice this is cancelled.
`required_solution_keys`	array of string	yes	Keys always present in the result's `solution`.
`parameters_schema`	object	yes	JSON Schema for the job's `parameters`.

AnalysisTypeEnum¶

A string, one of: network_extraction beta, network_validation beta, permeability, diffusivity, conductivity, poresize, hg_porosimetry, radial_density, chord_length_distribution, porosity_profile, porosity_connectivity beta, rev_porosity, sem_view, xray_view, interfacial_surface_area beta.

AnalysisTypeList¶

Field	Type	Required
`results`	array of `AnalysisType`	yes

AnalysisUnavailableResponse¶

Field	Type	Required	Description
`error`	object	yes	Error envelope with code analysis_unavailable, a message, and details.

Image¶

Field	Type	Required	Description
`id`	string (uuid)	yes
`name`	string	yes
`description`	string	yes
`status`	string	yes	`processing` while ingestion runs, then `ready` or `failed`. New values may be added.
`file_size`	integer	yes	Bytes in the uploaded file.
`dimensions`	array of integer or null	yes	The array shape, NumPy axes 0, 1 and 2. Null until ingestion ends.
`voxel_size`	number (double) or null	yes	Edge length of one voxel in micrometres.
`metrics`	object	yes	What ingestion measured: always `shape`, `data_type` and `range`; for binary images also `porosity` and `segmentation_phase_state`. Other keys may appear.
`processing_error`	string	yes	Why ingestion failed. Empty otherwise.
`created_at`	string (date-time)	yes
`updated_at`	string (date-time)	yes

ImageList¶

Field	Type	Required
`results`	array of `Image`	yes

JobCancelRefusedResponse¶

Field	Type	Required	Description
`error`	object	yes	Error envelope. Its code is `job_started` when the job is already running, `job_ended` when it has finished, or `cancel_unconfirmed` when the cancel could not be confirmed yet, so try again.

UploadCompletionRequest¶

Field	Type	Required	Description
`filename`	string	yes	The same filename the upload session was created with. At most 255 characters.
`name`	string	no	Display name. Defaults to the filename. At most 200 characters.
`description`	string	no	Free text.
`voxel_size`	number (double)	no	Edge length of one voxel in micrometres, a positive finite number. Results are in physical units only when it is set.
`raw_metadata`	object	no	Required for .raw files: `width`, `height`, `depth` and `dtype`, such as `uint8`.
`compute_tier`	string	no	`auto` (the default), or the key of a guarded compute tier this team has been given to ingest on. At most 100 characters.

UploadSession¶

Field	Type	Required	Description
`id`	string (uuid)	yes	The upload session's ID, used to complete the upload.
`url`	string (uri)	yes	Where to POST the file, as multipart form data. Do not send your API key.
`fields`	object	yes	Form fields to send, exactly as given, before the file field `file`.
`storage_key`	string	yes	Where the file will be stored.
`expires_in_seconds`	integer	yes	How long the form stays valid.
`max_file_size`	integer	yes	The largest file the form accepts, in bytes.

UploadSessionRequest¶

Field	Type	Required	Description
`filename`	string	yes	The file's name. Its extension picks the decoder: .npy, .npz, .zip, .raw, .tif or .tiff. At most 255 characters.
`name`	string	no	Display name. Defaults to the filename. At most 200 characters.
`description`	string	no	Free text.
`voxel_size`	number (double)	no	Edge length of one voxel in micrometres, a positive finite number. Results are in physical units only when it is set.
`raw_metadata`	object	no	Required for .raw files: `width`, `height`, `depth` and `dtype`, such as `uint8`.