Stock Formats

The Stock Formats API manages the sheet formats your shop buys: list them, fetch any version, add, edit, and retire your own, and hide or show standard ones.

Auto-generated from the public OpenAPI spec — this page never drifts from the running API. Base URL https://api.arcnm.io. Authenticate with the X-API-Key header (see Authentication).

List Stock Formats

GET /api/v1/stock-formats

The stock formats your organization prices with, its own first.

That is every format of your own plus each standard format you have not hidden. Every row says in resolution what calculations do with it.

The response is a plain array, so the page position travels in the Link (RFC 8288) and X-Next-Cursor / X-Has-More response headers.

Paginated. Pass cursor (from the previous response) to fetch the next page; limit caps the page size.

Parameters

Name	In	Type	Required	Description
kind	query	sheet | plate | bar | tube	no	Which purchased stock form to list: sheet, plate, bar or tube. One kind per list.
include_suppressed	query	boolean	no	Also list the standard formats your organization has hidden, marked suppressed. Off by default, so the list is exactly the formats calculations price with.
at	query	string	no	Read the list as it stood on this date (YYYY-MM-DD): the formats a calculation dated then prices with. Defaults to today (UTC).
cursor	query	string	no	Opaque position token from the previous page's next_cursor (or the Link / X-Next-Cursor response header). Omit it for the first page. Keep every other query parameter identical for the whole walk — a cursor replayed against different filters is rejected.
limit	query	integer	no	Maximum rows to return in one page.
offset	query	integer	no	Rows to skip. Superseded by cursor, which is stable under concurrent writes; kept for existing integrations. Bounded — past the cap, page with cursor.

Request

curl -X GET https://api.arcnm.io/api/v1/stock-formats \
  -H "X-API-Key: $ARCNM_API_KEY"

import requests

resp = requests.get(
    "https://api.arcnm.io/api/v1/stock-formats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()

Responses

Status	Description
200	Successful Response
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Create Stock Format

POST /api/v1/stock-formats

Add a format your shop buys ("GF 3000 × 1500", or a 6 m bar).

Calculations price with it from today on, beside the standard formats of its kind you have not hidden. Each kind states its own dimensions — see kind.

Request body (application/json)

Field	Type	Required	Description
diameter_mm	number	no
gauge_max_mm	number	no
gauge_min_mm	number	no
key	string	yes	A short identifier of lowercase letters, digits, - and _, starting with a letter or digit — unique among your current formats, and kept by every later version of this one.
kind	sheet | plate | bar | tube	no	Which purchased stock form this is. A sheet states length_mm and width_mm; a plate adds thickness_mm to its largest size; a bar states length_mm and, optionally, diameter_mm; a tube states length_mm, diameter_mm and wall_mm.
label	string	yes	The format's name, e.g. GF 3000 × 1500, as calculations and quotes show it. Invisible formatting is removed — direction controls and zero-width characters — and a name with nothing left to read is refused.
length_mm	number	yes
material_category	carbon_steel | alloy_steel | stainless_steel | tool_steel | cast_iron | aluminium | copper_alloy | nickel_alloy | titanium_alloy | magnesium_alloy | zinc_alloy | thermoplastic | thermoset | elastomer | composite | other	no
thickness_mm	number	no
wall_mm	number	no
width_mm	number	no

Request

curl -X POST https://api.arcnm.io/api/v1/stock-formats \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "string",
    "label": "string",
    "length_mm": 0
  }'

import requests

resp = requests.post(
    "https://api.arcnm.io/api/v1/stock-formats",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "key": "string",
        "label": "string",
        "length_mm": 0
    },
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "key": "string",
    "label": "string",
    "length_mm": 0
  }),
})
const data = await resp.json()

Responses

Status	Description
201	Successful Response
409	One of your current formats already uses this key (stock_format_key_taken).
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
409	conflict	A conflicting change, or an Idempotency-Key reused with a different body.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 201

Field	Type	Description
diameter_mm	number	Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres.
gauge_max_mm	number	Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind.
gauge_min_mm	number	Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind.
id	string	Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key.
is_platform	boolean	True for a standard format. You can hide a standard format for your organization, but not edit or retire it.
key	string	Stable identifier shared by every version.
kind	sheet | plate | bar | tube	The purchased stock form: sheet, plate (ordered cut to size), bar (round bar) or tube. Each kind states its own dimensions.
label	string	Display name, e.g. GF 3000 × 1500.
length_mm	number	Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres.
material_category	carbon_steel | alloy_steel | stainless_steel | tool_steel | cast_iron | aluminium | copper_alloy | nickel_alloy | titanium_alloy | magnesium_alloy | zinc_alloy | thermoplastic | thermoset | elastomer | composite | other	Material category this format is bought in; null for every material.
org_id	string	Your organization's id on a format of your own; null on a standard format.
resolution	priced | suppressed | closed	What calculations do with this format on the date read — at on the list, today otherwise. priced: they price with it. suppressed: a standard format your organization has hidden. closed: this version wasn't in force on that date — it was retired, or replaced by a newer version.
thickness_mm	number	Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind.
valid_from	string	Date this version took effect.
valid_to	string	Date this version was retired or replaced by a newer version; null while it is current.
wall_mm	number	Tube: the wall thickness, in millimetres. Null on every other kind.
width_mm	number	Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube.

Example response

{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}

Retire Stock Format

DELETE /api/v1/stock-formats/{format_id}

Stop buying this format.

It closes today and stays readable by id, so calculations priced on it keep their numbers when they are run again. A format added today that no calculation has used yet is removed instead.

Parameters

Name	In	Type	Required	Description
format_id	path	string	yes	Identifier of the format.

Request

curl -X DELETE https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY"

import requests

resp = requests.delete(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()

Responses

Status	Description
200	Successful Response
404	None of your own formats has this id (stock_format_not_found). A standard format can be hidden, but not edited or retired.
409	This version is already closed (stock_format_superseded), or retiring it would leave no format to price with (stock_format_last_remaining).
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
404	not_found	A referenced resource doesn't exist or isn't visible to your organisation.
409	conflict	A conflicting change, or an Idempotency-Key reused with a different body.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 200

Field	Type	Description
message	string

Example response

{
  "message": "string"
}

Get Stock Format

GET /api/v1/stock-formats/{format_id}

One stock format by id, in any version — including one retired or replaced since.

The format a calculation was priced on stays readable here after it leaves the list. resolution says what calculations dated today do with it.

Parameters

Name	In	Type	Required	Description
format_id	path	string	yes	Identifier of the format.

Request

curl -X GET https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY"

import requests

resp = requests.get(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()

Responses

Status	Description
200	Successful Response
404	No format with this id is visible to your organization (stock_format_not_found).
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
404	not_found	A referenced resource doesn't exist or isn't visible to your organisation.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 200

Field	Type	Description
diameter_mm	number	Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres.
gauge_max_mm	number	Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind.
gauge_min_mm	number	Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind.
id	string	Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key.
is_platform	boolean	True for a standard format. You can hide a standard format for your organization, but not edit or retire it.
key	string	Stable identifier shared by every version.
kind	sheet | plate | bar | tube	The purchased stock form: sheet, plate (ordered cut to size), bar (round bar) or tube. Each kind states its own dimensions.
label	string	Display name, e.g. GF 3000 × 1500.
length_mm	number	Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres.
material_category	carbon_steel | alloy_steel | stainless_steel | tool_steel | cast_iron | aluminium | copper_alloy | nickel_alloy | titanium_alloy | magnesium_alloy | zinc_alloy | thermoplastic | thermoset | elastomer | composite | other	Material category this format is bought in; null for every material.
org_id	string	Your organization's id on a format of your own; null on a standard format.
resolution	priced | suppressed | closed	What calculations do with this format on the date read — at on the list, today otherwise. priced: they price with it. suppressed: a standard format your organization has hidden. closed: this version wasn't in force on that date — it was retired, or replaced by a newer version.
thickness_mm	number	Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind.
valid_from	string	Date this version took effect.
valid_to	string	Date this version was retired or replaced by a newer version; null while it is current.
wall_mm	number	Tube: the wall thickness, in millimetres. Null on every other kind.
width_mm	number	Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube.

Example response

{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}

Update Stock Format

PATCH /api/v1/stock-formats/{format_id}

Edit one of your own formats. Standard formats are not editable.

Changing the size, gauge band or material starts a new version: this one closes today, so calculations priced on it keep their numbers, and the response is the new version — a new id under the same key. A version that took effect today changes in place instead, unless a calculation has already been pinned to it or priced on it; a new label always changes in place. A value sent unchanged changes nothing.

Parameters

Name	In	Type	Required	Description
format_id	path	string	yes	Identifier of the format.

Request body (application/json)

Field	Type	Required	Description
diameter_mm	number	no
gauge_max_mm	number	no
gauge_min_mm	number	no
label	string	no	The format's name, e.g. GF 3000 × 1500, as calculations and quotes show it. Invisible formatting is removed — direction controls and zero-width characters — and a name with nothing left to read is refused.
length_mm	number	no
material_category	carbon_steel | alloy_steel | stainless_steel | tool_steel | cast_iron | aluminium | copper_alloy | nickel_alloy | titanium_alloy | magnesium_alloy | zinc_alloy | thermoplastic | thermoset | elastomer | composite | other	no
thickness_mm	number	no
wall_mm	number	no
width_mm	number	no

Request

curl -X PATCH https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "diameter_mm": 0,
    "gauge_max_mm": 0,
    "gauge_min_mm": 0,
    "label": "string",
    "length_mm": 0,
    "material_category": "carbon_steel",
    "thickness_mm": 0,
    "wall_mm": 0,
    "width_mm": 0
  }'

import requests

resp = requests.patch(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "diameter_mm": 0,
        "gauge_max_mm": 0,
        "gauge_min_mm": 0,
        "label": "string",
        "length_mm": 0,
        "material_category": "carbon_steel",
        "thickness_mm": 0,
        "wall_mm": 0,
        "width_mm": 0
    },
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "diameter_mm": 0,
    "gauge_max_mm": 0,
    "gauge_min_mm": 0,
    "label": "string",
    "length_mm": 0,
    "material_category": "carbon_steel",
    "thickness_mm": 0,
    "wall_mm": 0,
    "width_mm": 0
  }),
})
const data = await resp.json()

Responses

Status	Description
200	Successful Response
404	None of your own formats has this id (stock_format_not_found). A standard format can be hidden, but not edited or retired.
409	This version is closed, so its size, gauge band and material can't change (stock_format_superseded). Edit the current version instead.
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
404	not_found	A referenced resource doesn't exist or isn't visible to your organisation.
409	conflict	A conflicting change, or an Idempotency-Key reused with a different body.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 200

Field	Type	Description
diameter_mm	number	Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres.
gauge_max_mm	number	Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind.
gauge_min_mm	number	Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind.
id	string	Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key.
is_platform	boolean	True for a standard format. You can hide a standard format for your organization, but not edit or retire it.
key	string	Stable identifier shared by every version.
kind	sheet | plate | bar | tube	The purchased stock form: sheet, plate (ordered cut to size), bar (round bar) or tube. Each kind states its own dimensions.
label	string	Display name, e.g. GF 3000 × 1500.
length_mm	number	Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres.
material_category	carbon_steel | alloy_steel | stainless_steel | tool_steel | cast_iron | aluminium | copper_alloy | nickel_alloy | titanium_alloy | magnesium_alloy | zinc_alloy | thermoplastic | thermoset | elastomer | composite | other	Material category this format is bought in; null for every material.
org_id	string	Your organization's id on a format of your own; null on a standard format.
resolution	priced | suppressed | closed	What calculations do with this format on the date read — at on the list, today otherwise. priced: they price with it. suppressed: a standard format your organization has hidden. closed: this version wasn't in force on that date — it was retired, or replaced by a newer version.
thickness_mm	number	Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind.
valid_from	string	Date this version took effect.
valid_to	string	Date this version was retired or replaced by a newer version; null while it is current.
wall_mm	number	Tube: the wall thickness, in millimetres. Null on every other kind.
width_mm	number	Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube.

Example response

{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}

Unsuppress Stock Format

DELETE /api/v1/stock-formats/{format_id}/suppression

Show a standard format you had hidden.

Calculations price with it again from today on.

Parameters

Name	In	Type	Required	Description
format_id	path	string	yes	Identifier of the format.

Request

curl -X DELETE https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression \
  -H "X-API-Key: $ARCNM_API_KEY"

import requests

resp = requests.delete(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()

Responses

Status	Description
200	Successful Response
404	No format with this id is visible to your organization (stock_format_not_found).
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
404	not_found	A referenced resource doesn't exist or isn't visible to your organisation.
409	conflict	A conflicting change, or an Idempotency-Key reused with a different body.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 200

Field	Type	Description
message	string

Example response

{
  "message": "string"
}

Suppress Stock Format

POST /api/v1/stock-formats/{format_id}/suppression

Hide a standard format your shop doesn't buy, for your organization only.

Calculations stop pricing with it from today on; earlier calculations keep the formats they were priced with. The hide holds for the format, so it stays hidden when a newer version of it replaces this one. A format of your own is retired instead.

Parameters

Name	In	Type	Required	Description
format_id	path	string	yes	Identifier of the format.

Request body (application/json)

Field	Type	Required	Description
reason	string	no

Request

curl -X POST https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "string"
  }'

import requests

resp = requests.post(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "reason": "string"
    },
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "string"
  }),
})
const data = await resp.json()

Responses

Status	Description
201	Successful Response
404	No format with this id is visible to your organization (stock_format_not_found).
409	The format is one of your own, which you retire instead (stock_format_own_row_use_retire), this version of it is closed (stock_format_superseded), or hiding it would leave no format to price with (stock_format_last_remaining).
422	Validation Error

Errors

Standard error responses — see the Errors catalog for the full envelope, request_id, and retry-safety table.

Status	Code	When
401	invalid_api_key	Missing, malformed, or revoked API key.
403	insufficient_scope	The key is valid but lacks a scope this endpoint requires.
404	not_found	A referenced resource doesn't exist or isn't visible to your organisation.
409	conflict	A conflicting change, or an Idempotency-Key reused with a different body.
429	rate_limited	Per-key or per-org rate limit exceeded — back off with jitter and retry.

Response body 201

Field	Type	Description
message	string

Example response

{
  "message": "string"
}