REST quickstart¶
This example submits a simple geometry through the central service and retrieves its saved outputs. It is an interface tutorial, not a thermal-performance or manufacturing validation. A network connection and a credential with the required geometry, job and artifact permissions are needed.
1. Discover and validate¶
Use the environment variables from authentication. Inspect the template before changing any parameters:
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $GD_API_KEY" \
"$GD_API_BASE/v1/geometry/templates/cold_plate"
Save the following as geometry-request.json:
{
"template_id": "cold_plate",
"parameters": {},
"outputs": ["stl", "design"]
}
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $GD_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @geometry-request.json \
"$GD_API_BASE/v1/geometry/validate"
Validation starts no geometry job. Read any returned errors. An omitted project_id is supported: the service assigns a private workflow for new work without an input artifact. To place the job in an existing accessible project, include its real ID.
2. Submit once¶
Choose a unique key for this intended job and retain it with the request. The example key is illustrative; replace it for each new intended run.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $GD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tutorial-geometry-001" \
--data-binary @geometry-request.json \
"$GD_API_BASE/v1/geometries"
The normal asynchronous response is HTTP 202 with a job id. Keep that ID. If the response is lost, reconcile this same request using the same key; a new key can start new work. Check the service’s estimate and charging policy before submitting mesh, simulation, inference or study work.
3. Follow the job¶
# Set JOB_ID to the actual id from the submission response.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $GD_API_KEY" \
"$GD_API_BASE/v1/jobs/$JOB_ID"
Poll at the returned/recommended interval. Read state, error, result, artifact_ids and links. Follow job recovery for pending, unknown, failed or cancelled states. Closing your client does not cancel the job.
4. View and continue¶
On success, request the job’s default viewer:
curl --fail-with-body --silent --show-error \
-X POST -H "Authorization: Bearer $GD_API_KEY" \
-H "Prefer: respond-async" \
"$GD_API_BASE/v1/jobs/$JOB_ID/viewer"
If this returns operation_id, follow GET /v1/operations/{operation_id} until its result is ready. Open the complete returned viewer_url privately. Inspect the geometry artifact’s units and bounds before meshing. Use the saved geometry artifact as input; a screenshot is not geometry.
For exact HTTP parameters and response models see geometry endpoints, job endpoints and operation endpoints.