Create, Update & Delete Records

These endpoints require read-write or admin scope.

POST /v1/records

Create a new record.

Request body

{
  "form_id": "df7991ef-4a6f-48f4-9f1d-0fd4f53c9a77",
  "project_id": "c328e46a-8fb9-41f1-a5f9-3dca9a894ab3",
  "properties": {
    "inspector_name": "Jane Smith",
    "condition": "good"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-73.985, 40.758]
  }
}

Field	Required	Description
`form_id`	Yes	Target form ID in your organization
`project_id`	No	Project ID (defaults to form project)
`properties`	No	JSON object with form field values
`geometry`	No	GeoJSON geometry

Example

curl -X POST \
  -H "X-API-Key: mk_live_..." \
  -H "Idempotency-Key: create-record-001" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "df7991ef-4a6f-48f4-9f1d-0fd4f53c9a77",
    "properties": {"inspector_name": "Jane Smith", "condition": "good"}
  }' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records"

PUT /v1/records/:id

Update a record by ID. Include only fields you want to change.

Request body

{
  "properties": {
    "condition": "needs_repair",
    "notes": "Crack observed in north wall"
  },
  "priority": 2,
  "workflow_state_id": "state_in_review"
}

Field	Description
`properties`	Replaces `properties` object
`geometry`	Replaces geometry (`null` removes it)
`assigned_to`	Assign record to user ID
`priority`	Set priority
`workflow_state_id`	Set workflow state

Example

curl -X PUT \
  -H "X-API-Key: mk_live_..." \
  -H "Idempotency-Key: update-record-001" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"condition": "needs_repair"}}' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records/8ba2dac9-2f85-4b36-9b8f-2da8c9a7f4a0"

DELETE /v1/records/:id

Soft-deletes the record.

curl -X DELETE \
  -H "X-API-Key: mk_live_..." \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records/8ba2dac9-2f85-4b36-9b8f-2da8c9a7f4a0"

Success response:

{
  "ok": true,
  "data": {
    "id": "8ba2dac9-2f85-4b36-9b8f-2da8c9a7f4a0",
    "deleted": true
  }
}

Use include_deleted=true on list endpoint to view deleted records.

Idempotency details

Write calls with POST and PUT support Idempotency-Key.

Repeated retry with same payload replays cached response.
Same key with different payload returns 409 idempotency_key_conflict.
Same key while first request is still in-flight returns 409 idempotency_in_progress.