Projects

A project is a piece your customer wants made, started from one of a design's images. It opens on your Bench, where your team takes it from an estimate to the finished piece. Your server creates a project when the customer picks an image, reads it back with its measurements, lists and searches the customer's projects, and deletes one if they change their mind. Every call takes your API key and the customer's access token from Auth. Each project belongs to that customer, in your store. The API comes with the Retail plan.

Create a project

Starts a project from the image the customer picked. Its id is in the design's images, which Retrieve a design returns.

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

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
design_image	Required. The image the project is for, as an object.
design_image.id	Required. The image's `id` from the design's `images`.

RequestShell

curl https://api.diamra.com/v1/projects \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "design_image": {      "id": "6cae4081-3d5f-4b7c-9e1a-2f4d6b8cae32"    }  }'

ResponseHTTP

HTTP/2 201content-type: application/jsonrequest-id: req_1f8c3a6e94d27b05{  "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58",  "design_image": {    "id": "6cae4081-3d5f-4b7c-9e1a-2f4d6b8cae32",    "url": "https://assets.diamra.com/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/2.webp"  },  "projections": []}

An image has one project. If the image has a project already, the call answers it with a 200 and starts nothing new. A new project sends the project.started webhook event, like every new project in your store. Diamra also emails your team about it, unless you turned that email off in Diamra Email Delivery.

Retrieve a project

Returns the project with its projections. When a project starts, Diamra draws the piece from the front, the top, the left and the bottom so it can be measured. The projections take about a minute, and until then the list is empty. Your team measures the piece by drawing lines over them on your Bench, and the customer can too if your store lets them. Each projection lists those lines as its measurements.

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

Send the same two headers.

RequestShell

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

ResponseHTTP

HTTP/2 200content-type: application/jsonrequest-id: req_7b2e0c5d18f94a63{  "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58",  "design_image": {    "id": "6cae4081-3d5f-4b7c-9e1a-2f4d6b8cae32",    "url": "https://assets.diamra.com/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/2.webp"  },  "projections": [    {      "view": "front",      "url": "https://assets.diamra.com/measure-projections/5b8e1f3a-2c47-4d9e-b061-7a3f9c2e4d18/8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58/front/2b7e4c90-6a1d-4f3b-8e5c-9d0a1b2c3e4f.webp",      "measurements": [        {          "type": "reference",          "label": "total setting height",          "mm": 10,          "text": null,          "from": { "x": 0.2814, "y": 0.2367 },          "to": { "x": 0.2814, "y": 0.7712 }        },        {          "type": "measurement",          "label": "center stone major axis",          "mm": 5.4,          "text": null,          "from": { "x": 0.3712, "y": 0.3105 },          "to": { "x": 0.6288, "y": 0.3105 }        },        {          "type": "measurement",          "label": "shank thickness",          "mm": 1.6,          "text": null,          "from": { "x": 0.4875, "y": 0.7104 },          "to": { "x": 0.4875, "y": 0.7871 }        },        {          "type": "callout",          "label": "bezel",          "mm": null,          "text": "14K yellow gold",          "from": { "x": 0.6633, "y": 0.3519 },          "to": { "x": 0.8211, "y": 0.2042 }        }      ]    },    {      "view": "top",      "url": "https://assets.diamra.com/measure-projections/5b8e1f3a-2c47-4d9e-b061-7a3f9c2e4d18/8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58/top/2b7e4c90-6a1d-4f3b-8e5c-9d0a1b2c3e4f.webp",      "measurements": [        {          "type": "measurement",          "label": "center stone minor axis",          "mm": 3.8,          "text": null,          "from": { "x": 0.4093, "y": 0.5 },          "to": { "x": 0.5907, "y": 0.5 }        }      ]    },    {      "view": "left",      "url": "https://assets.diamra.com/measure-projections/5b8e1f3a-2c47-4d9e-b061-7a3f9c2e4d18/8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58/left/2b7e4c90-6a1d-4f3b-8e5c-9d0a1b2c3e4f.webp",      "measurements": []    },    {      "view": "bottom",      "url": "https://assets.diamra.com/measure-projections/5b8e1f3a-2c47-4d9e-b061-7a3f9c2e4d18/8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58/bottom/2b7e4c90-6a1d-4f3b-8e5c-9d0a1b2c3e4f.webp",      "measurements": []    }  ]}

A reference is a length someone entered, and it sets the scale. Measurements are worked out from it, and a line with no length yet isn't listed. A callout is a note, such as the metal or a stone's weight. Lengths are in millimeters, to 0.1 mm.

Each line has two points on the projection's image, from and to. Their x and y are fractions of the image's width and height from its top-left corner, so multiply them by the image's size in pixels to draw the line. For a length they are its two ends. For a callout, from is the point it marks and to is where its note sits. A line drawn past the image's edge can go below 0 or above 1.

Delete a project

Takes the project off the customer's projects. Nothing is lost: your store keeps it on your Bench, with its projections and everything else made for it.

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

Send the same two headers.

RequestShell

curl -X DELETE https://api.diamra.com/v1/projects/8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58 \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN"

ResponseHTTP

HTTP/2 200content-type: application/jsonrequest-id: req_6a0d4e2b71f93c58{  "id": "8d3e5b17-2f6a-4c9e-b0d4-7a1c9e2f6b58",  "deleted": true}

Deleting it again answers 404, and so does retrieving it. To bring it back, create a project from the same image: the same project comes back, with its id, its projections and their measurements.

List projects

Returns the customer's projects, newest first, one page at a time. Each one is the same object that Retrieve a project returns. Deleted projects aren't listed.

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

Send the same two headers. The parameters go in the query string, and each one is optional.

Parameter	What it is
limit	How many projects to return, from 1 to 100. The default is 10.
starting_after	The id of the last project on the page you have. The next page starts after it.
search	Words to look for, up to 200 characters. A project matches when each word is in its design's prompt, or in the names of the options the customer picked in your studio. Case doesn't matter.

RequestShell

curl -G https://api.diamra.com/v1/projects \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -d limit=1 \  --data-urlencode "search=oval sapphire"

ResponseHTTP

HTTP/2 200content-type: application/jsonrequest-id: req_9c4a1e7f30b2d865{  "object": "list",  "url": "/v1/projects",  "has_more": true,  "data": [    {      "id": "9e4f6c28-3a7b-4d0f-8c1e-5b2d0a3f7c69",      "design_image": {        "id": "7dbf5192-4e6a-4c8d-af2b-3a5e7c9dbf43",        "url": "https://assets.diamra.com/design-images/3f6d1c2e-8a4b-4f0e-9b7a-2c5e8d1f4a90/3.webp"      },      "projections": []    }  ]}

has_more is true when more projects follow. For the next page, send the last project's id as starting_after, with the same limit and search.

The next pageShell

curl -G https://api.diamra.com/v1/projects \  -H "Authorization: Bearer $DIAMRA_API_KEY" \  -H "Diamra-Customer-Token: $ACCESS_TOKEN" \  -d limit=1 \  --data-urlencode "search=oval sapphire" \  -d starting_after=9e4f6c28-3a7b-4d0f-8c1e-5b2d0a3f7c69

When has_more is false, you have them all. A search that matches nothing returns an empty data list.

The project

Create a project and Retrieve a project answer it, and List projects returns a page of them in data. Delete a project answers its id and deleted: true.

Field	What it is
id	The project's id. Webhook events about the project carry it as `project_id`.
design_image.id	The image the project is for. Webhook events carry it as `design_image_id`.
design_image.url	A public link to the image, the same as in the design's images.
projections	The piece drawn from each side for measuring, in this order: front, top, left, bottom. Empty until they're made.
projections[].view	front, top, left or bottom.
projections[].url	A public link to the projection's image.
projections[].measurements	The lines drawn on the projection, oldest first.
measurements[].type	`reference`, a length someone entered; `measurement`, a length worked out from the reference; or `callout`, a note.
measurements[].label	What the line measures, such as shank thickness. Diamra names each line, and your team can rename it. null until it has a name.
measurements[].mm	The length in millimeters, to 0.1 mm. null for a callout.
measurements[].text	A callout's note, such as 14K yellow gold. null for a length.
measurements[].from	The line's first point on the projection's image: x and y, fractions of its width and height from the top-left corner. For a callout, the point it marks.
measurements[].to	The line's other point, in the same terms. For a callout, where its note sits.

Limits

One customer	10 calls a minute to Create a project.
Your store	30 calls a minute to Create a project, and 120 to List projects.

Over a limit, the call answers a 429 rate_limit, with Retry-After: 60, and the message says which. Retrieve a project and Delete a project have no limit.

Errors

Answer	When
400 parameter_missing	No design_image, or no id in it. param names it.
400 parameter_unknown	A parameter the call doesn't take, often a typo. param names it.
400 parameter_invalid	design_image isn't an object, or its id isn't a well-formed id. For a list: limit isn't a whole number from 1 to 100, starting_after isn't a well-formed id, or search is over 200 characters. param names the one at fault.
400 resource_missing	design_image.id isn't an image of this customer's designs in your store, or starting_after 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.
404 resource_missing	No project with this id belongs to this customer in your store, or it was deleted.
429 rate_limit	More than 10 calls to Create a project in a minute for one customer, or 30 for your store. More than 120 calls to List projects in a minute for your store.
503	The project couldn't be created. Try again in a minute.

An errorHTTP

HTTP/2 400content-type: application/jsonrequest-id: req_3c7e1b94a05d2f86{  "error": {    "type": "invalid_request_error",    "code": "resource_missing",    "message": "No design image 7c2e9a41-5d3b-4f8e-a1c6-0b9d4e2f8a73 of this customer in your store.",    "param": "design_image.id"  }}