Safe writes and retries

Send a flat record payload#

Create with POST /{resource} and update with PATCH /{resource}/{id}. Send the field values directly in a JSON object, not inside a fields wrapper. PATCH changes only the fields you supply. Describe the resource first to discover required fields and valid options. The examples use a company named Northfold; workspace-specific required fields may need to be added.

• Create returns 201, { data: record } and a Location header.
• Update returns 200 and { data: record }.
• Unknown fields and invalid values are refused, rather than silently accepted.
• Writes need a write key and the owner’s resource and field write permissions.

# Set IDEMPOTENCY_KEY once for this logical operation; keep it for retries.
read -r -p 'Unique operation key: ' IDEMPOTENCY_KEY
curl --fail-with-body --include --request POST "$SQUARIO_API_BASE/companies" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"name":"Northfold"}'

# Use the actual id returned by creation and a new key for this operation.
read -r -p 'Company id: ' COMPANY_ID
read -r -p 'Unique update operation key: ' UPDATE_KEY
curl --fail-with-body --request PATCH "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $UPDATE_KEY" \
  --data '{"name":"Northfold Studio"}'

Write custom fields by key#

Use either flat cf__<key> properties or one custom_fields object. Do not mix both formats in a request. Replace integration_code in the example with a real editable field key from your workspace’s schema. Required and conditional field rules are enforced on the server.

{
  "custom_fields": {
    "integration_code": "northfold-001"
  }
}

Archive instead of deleting permanently#

DELETE /{resource}/{id} archives the record. It is a soft delete; you may send { reason } as an optional JSON body. Restore with POST /{resource}/{id}/restore. Both return the resulting record in data. Active lists exclude archived records unless you set include_archived=true.

read -r -p 'Unique archive operation key: ' ARCHIVE_KEY
curl --fail-with-body --request DELETE "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $ARCHIVE_KEY" \
  --data '{"reason":"Integration cleanup"}'

read -r -p 'Unique restore operation key: ' RESTORE_KEY
curl --fail-with-body --request POST "$SQUARIO_API_BASE/companies/$COMPANY_ID/restore" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header "Idempotency-Key: $RESTORE_KEY"

Make write retries deliberate#

Every record write and association PUT/DELETE accepts Idempotency-Key. Generate one unique key per logical operation, store it with the operation, and reuse it for retries. It must contain 1–255 printable ASCII characters without spaces and is scoped to the API key. The fingerprint includes method, /v1 path, query string and exact body bytes.

Plan for an uncertain outcome#

Idempotency reduces duplicate writes, but it is not an exactly-once guarantee. An unfinished claim can be taken over after five minutes; a write that committed just before a worker failed can run again. After an ambiguous failure, retry with the original key and bytes, then reconcile the record before creating a new operation. Reads ignore this header, and only successful responses are stored.