Measurements

Measurements are lines drawn on a project's views: the piece seen from the front, the top, the left and the bottom. Your team draws them on your Bench, and your customer can too if your store lets them. Both see every line, and both can change any of them. Every call takes your API key and the customer's access token from Auth.

Type	What it is
reference	A length the customer knows, usually the inner diameter of a ring in their size: US 7 is 17.3 mm. It sets the scale. A project has one reference, on any view, and a new one replaces it.
measurement	A line whose length Diamra works out from the reference. You send its two ends, never its length.
callout	A note on a point, such as the metal or a stone's weight.

Add a measurement

Adds a line to one of the project's views. It answers the measurement, with its length.

POSThttps://api.diamra.com/v1/measurements

Header	What it is
Authorization	Required. `Bearer` and your API key.
Diamra-Customer-Token	Required. The customer's `access_token` from Log in, Register or Refresh.

Parameter	What it is
view	Required. The view to draw on, as an object.
view.id	Required. The view's id, from List views.
type	Required. reference, measurement or callout.
from	Required. The line's first point on the view's image, as x and y: fractions of its width and height from the top-left corner, from 0 to 1. For a callout, the point it marks.
to	Required. The line's other point. For a callout, where its note sits. A length's two points are at least 0.01 apart.
mm	Required for a reference: its length in millimeters, from 0.1 to 300. Only a reference takes it.
text	Required for a callout: its note, 1 to 60 characters. Only a callout takes it.
label	What the line measures, such as band width, up to 60 characters.

RequestShell

curl https://api.diamra.com/v1/measurements \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "view": {      "id": "e1a7c4d2-8b3f-4e69-a05d-6c2f9b8e1d37"    },    "type": "measurement",    "from": {      "x": 0.4875,      "y": 0.7104    },    "to": {      "x": 0.4875,      "y": 0.7358    },    "label": "shank thickness"  }'

ResponseHTTP

HTTP/2 201content-type: application/jsonrequest-id: req_0c5e8b3f61d74a92{  "id": "6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64",  "project": {    "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58"  },  "view": {    "id": "e1a7c4d2-8b3f-4e69-a05d-6c2f9b8e1d37",    "view": "front"  },  "type": "measurement",  "label": "shank thickness",  "mm": 1.6,  "text": null,  "from": {    "x": 0.4875,    "y": 0.7104  },  "to": {    "x": 0.4875,    "y": 0.7358  },  "drawn_by": "customer",  "created_at": 1794325212}

A measurement's mmis null until the project has a reference. Your store decides whether customers may measure, with the Measure switch in your Bench's project settings. While it's off, the call answers 403 measurements_disabled.

Adding a reference replaces the project's reference, on whichever view it was. The old line is deleted, and every measurement's length is worked out again from the new one.

List measurements

Returns every line on the project's views, oldest first, your team's and the customer's.

GEThttps://api.diamra.com/v1/measurements

Send the same two headers. The parameters go in the query string.

Parameter	What it is
project	Required. The project's id.
view	Only the lines on this view: its id.

RequestShell

curl -G https://api.diamra.com/v1/measurements \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -d project=8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58

ResponseHTTP

HTTP/2 200content-type: application/jsonrequest-id: req_7a2d9f4c06e81b35{  "object": "list",  "url": "/v1/measurements",  "has_more": false,  "data": [    {      "id": "2b9e7d41-5c08-4f6a-b3d2-8a1e6c0f9b57",      "project": {        "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58"      },      "view": {        "id": "e1a7c4d2-8b3f-4e69-a05d-6c2f9b8e1d37",        "view": "front"      },      "type": "reference",      "label": "inner diameter",      "mm": 17.3,      "text": null,      "from": {        "x": 0.3625,        "y": 0.5875      },      "to": {        "x": 0.6375,        "y": 0.5875      },      "drawn_by": "customer",      "created_at": 1794325212    },    {      "id": "a4d81f3c-6e29-4b75-9c0a-3f5e7b2d8c16",      "project": {        "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58"      },      "view": {        "id": "e1a7c4d2-8b3f-4e69-a05d-6c2f9b8e1d37",        "view": "front"      },      "type": "callout",      "label": "bezel",      "mm": null,      "text": "14K yellow gold",      "from": {        "x": 0.6633,        "y": 0.3519      },      "to": {        "x": 0.8211,        "y": 0.2042      },      "drawn_by": "owner",      "created_at": 1794325212    },    {      "id": "6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64",      "project": {        "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58"      },      "view": {        "id": "e1a7c4d2-8b3f-4e69-a05d-6c2f9b8e1d37",        "view": "front"      },      "type": "measurement",      "label": "shank thickness",      "mm": 1.6,      "text": null,      "from": {        "x": 0.4875,        "y": 0.7104      },      "to": {        "x": 0.4875,        "y": 0.7358      },      "drawn_by": "customer",      "created_at": 1794325212    }  ]}

Retrieve a measurement

Returns one line.

GEThttps://api.diamra.com/v1/measurements/{id}

RequestShell

curl https://api.diamra.com/v1/measurements/6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64 \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN"

Update a measurement

Changes any line of the project, your team's too: its points, a reference's mm, a callout's text or its label. Send only what changes. A line keeps its type and its view: to move one, delete it and add another.

POSThttps://api.diamra.com/v1/measurements/{id}

Send the same two headers. It takes from, to, mm, text and label, as Add a measurement does; a label of null removes it.

RequestShell

curl https://api.diamra.com/v1/measurements/6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64 \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "to": {      "x": 0.4875,      "y": 0.739    }  }'

A change to the reference works out every measurement's length again.

Delete a measurement

Deletes any line of the project. Deleting the reference leaves every measurement without a length until a new reference is added.

DELETEhttps://api.diamra.com/v1/measurements/{id}

RequestShell

curl -X DELETE https://api.diamra.com/v1/measurements/6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64 \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN"

ResponseHTTP

HTTP/2 200content-type: application/jsonrequest-id: req_3f8b1e6a29c05d74{  "id": "6f1c2a8e-9d47-4b3a-8e25-0c7f3b9d1a64",  "deleted": true}

The measurement

id	The measurement's id.
project.id	The project it's drawn on.
view.id	The view it's drawn on.
view.view	That view's side: front, top, left or bottom.
type	reference, measurement or callout.
label	What the line measures, such as shank thickness. null when nobody named it.
mm	The length in millimeters, to 0.1 mm. null for a callout, and for a measurement while the project has no reference.
text	A callout's note. null for a length.
from	The line's first point on the view's image, x and y from 0 to 1. For a callout, the point it marks. A line your team drew past the image's edge can go below 0 or above 1.
to	The other point. For a callout, where its note sits.
drawn_by	customer, or owner when your team drew it on your Bench.
created_at	When it was drawn, in Unix seconds.

Limits

One customer	30 adds, updates and deletes a minute, together.
Your store	120 adds, updates and deletes, and 240 lists and retrievals, a minute.

Over a limit, the call answers a 429 rate_limit, with Retry-After: 60.

Errors

Answer	When
400 parameter_missing	A required parameter is missing. param names it.
400 parameter_unknown	A parameter the call doesn't take, often a typo. param names it.
400 parameter_invalid	A type that doesn't exist; an id that isn't well formed; a point outside 0 to 1; a length's points too close; mm out of range or sent for a line that isn't a reference; text out of range or sent for a length; a label over 60 characters. param names the one at fault.
400 resource_missing	view.id, or view in a list, isn't a view this customer sees in your store; or project in a list isn't a project of theirs. The message gives the id.
401 api_key_invalid	No key, or one Diamra doesn't know. See API keys.
401 api_key_revoked	The key was revoked in your console.
401 customer_token_invalid	No access token, or one that ran out or was never valid. Refresh the session, or log the customer in again.
403 access_pending	Your store approves new customers first and hasn't approved this one. Approve them under Customers in your Bench.
403 plan_required	Your store isn't on the Retail plan. Its keys work again once it is.
403 measurements_disabled	Your store doesn't let customers measure. Turn it on in your Bench's project settings.
404 resource_missing	No measurement with this id for this customer in your store.
429 rate_limit	Over a limit above.

An errorHTTP

HTTP/2 400content-type: application/jsonrequest-id: req_9d4b2e7a15c38f06{  "error": {    "type": "invalid_request_error",    "code": "parameter_invalid",    "message": "Only a reference takes mm. A measurement's length comes from the reference.",    "param": "mm"  }}