Locations

Create, list, retrieve, update, and deactivate locations.

• Base path: /api/integrations/v1/locations/
• Required scope: integrations.locations.{read|write|delete}
• Identifier: code (see Identifiers)

---

Create location

POST /api/integrations/v1/locations/

Body

Field	Type	Required	Description
code	string	Yes	Unique location code (e.g. A-101)
name	string	No	Human-readable name
zone	string	No	Zone identifier
aisle	string	No	Aisle identifier
metadata	object	No	Arbitrary metadata

curl

curl -X POST https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"code": "A-103", "name": "Aisle A, Shelf 103", "zone": "A", "aisle": "1"}'

Python

import requests

res = requests.post(
    "https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/",
    headers={"X-API-Key": "sk_live_..."},
    json={"code": "A-103", "name": "Aisle A, Shelf 103", "zone": "A", "aisle": "1"},
    timeout=30,
)

Node.js

await fetch(
  "https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      code: "A-103",
      name: "Aisle A, Shelf 103",
      zone: "A",
      aisle: "1",
    }),
  },
);

Response 201 Created

{
  "success": true,
  "data": {
    "id": "...",
    "code": "A-103",
    "name": "Aisle A, Shelf 103",
    "zone": "A",
    "aisle": "1",
    "is_active": true
  }
}

Errors

Status	Code	When
400	VALIDATION_ERROR	Missing code
422	MAPPING_ERROR	Mapping engine failed
409	DUPLICATE	A location with that code exists

---

List locations

GET /api/integrations/v1/locations/

Returns a cursor-paginated list of active locations, newest-first.

Query parameters: limit (1–200, default 50), cursor (opaque). See Pagination.

curl 'https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/?limit=100' \
  -H "X-API-Key: sk_live_..."

{
  "success": true,
  "data": [
    {"code": "A-101", "name": "Aisle A, Shelf 101", "zone": "A", "aisle": "1", "is_active": true}
  ],
  "pagination": {"limit": 100, "next_cursor": "eyJjIjoi..."}
}

---

Get location

GET /api/integrations/v1/locations/{code}/

curl https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/A-101/ \
  -H "X-API-Key: sk_live_..."

Returns the full record (same shape as Create). Returns 404 NOT_FOUND if the code doesn't exist.

---

Update location

PUT /api/integrations/v1/locations/{code}/

Field	Type
name	string
zone	string
aisle	string
metadata	object
is_active	boolean

curl -X PUT https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/A-101/ \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Aisle A, Shelf 101 (Renovated)", "zone": "A-NEW"}'

---

Deactivate location

DELETE /api/integrations/v1/locations/{code}/

Soft delete — sets is_active = false. The record stays in the database.

curl -X DELETE https://<your-tenant>.datamingle.ai/api/integrations/v1/locations/A-101/ \
  -H "X-API-Key: sk_live_..."

{
  "success": true,
  "data": {"id": "...", "code": "A-101", "is_active": false}
}