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.
userCountrequired	integer	Number of end users this pull is licensed for. Must be a positive integer (≥ 1). The credit cost is multiplied by this value — see Per-user licensing below.

ℹ

Per-user licensing: every billable pull is prorated by the number of end users who will have access to the pulled data, even within the same team. Set userCount to that number — the total credits debited is (sum of property prices) × userCount.

Response

200OK

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

creditsDebited already reflects the userCount multiplier — e.g. 2 properties with userCount: 3 debits 6 credits.

Errors

400Bad Request when propertyIds is empty or contains non-UUID values, when userCount is missing or not a positive integer, 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…"], "userCount": 1}'

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.