Pull (purchase) material properties

Purchase one or more properties of a material. Each property is a numeric row inside the material (e.g. carbon content, heating value). Pulling reveals the value to the active team and debits credits.

POST/public/materials/:id/properties/pull

⚠

This endpoint is non-idempotent and billable. Each successful request debits credits. Wrap it in your own idempotency layer if you're calling it from a retry-able workflow.

A property is a single numeric row inside a material — e.g. carbon content, heating value, net, density. Pulling a material as a whole isn't a concept; you pull the individual properties you need. The material id comes from the URL, so the request body only carries the property ids.

Path parameters

Parameter	Type	Description
idrequired	string (uuid)	The material id the properties belong to.

Request body

Parameter	Type	Description
propertyIdsrequired	string[]	1–500 property ids to pull. Each id is a row id off the parent material's properties array.

Response

200OK

{
  "materialId": "8c2a17a4-1234-4d1e-9b21-3a8e2c91c0a1",
  "pulledPropertyIds": ["55ada…", "18a58…"],
  "creditsDebited": 2
}

Errors

400Bad Request when propertyIds is empty or contains non-UUID values, or when the material id in the URL is not a UUID. 404Not Foundwhen the material doesn't exist or isn't visible to the active team. 403Forbidden when the team has insufficient credits.

Example

curl -s -X POST \
  'https://api.circa.ai/public/materials/8c2a17a4-1234-4d1e-9b21-3a8e2c91c0a1/properties/pull' \
  -H 'x-api-key: circa_live_xxx' \
  -H 'x-team-id: TEAM_ID_FROM_OVERVIEW' \
  -H 'Circa-Version: 2026-05-11.arrakis' \
  -H 'Content-Type: application/json' \
  -d '{"propertyIds": ["55ada…", "18a58…"]}'

After pulling

Once a property is pulled, every subsequent GET /public/materials / GET /public/materials/:id / GET /public/materials/:id/properties/:propertyId response will return that property with revealed: true and the real numeric value instead of null. Pass ?pulled=true to list only materials that have at least one revealed property.