Runaways

Open reports of lost or escaped animals, with the owner, where the animal was last seen, and a photo.

List runaways

GET/v1/runaways

Requires the scope runaways:read.

Available from phase 2

Reports of lost or escaped animals (weglopers) that are still open.

Query parameters

created_afterISO 8601

Only records created after this time.

created_beforeISO 8601

Only records created before this time.

updated_afterISO 8601

Only records changed after this time. For a sync, pass your last sync time minus 60 seconds and deduplicate by id.

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/runaways" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "w_8Rt1",
      "status": "active",
      "name": "Bobby",
      "species": "Hond",
      "breed": "Labrador",
      "danger_level": "green",
      "owner": {
        "name": "J. de Vries",
        "phone": "+31687654321"
      },
      "location": {
        "address": "Maliebaan, Utrecht",
        "latitude": 52.087,
        "longitude": 5.13
      },
      "photo": {
        "url": "https://storage.googleapis.com/…",
        "expires_at": "2026-11-09T09:15:00Z"
      },
      "created_at": "2026-11-08T17:40:00Z",
      "updated_at": "2026-11-09T07:55:00Z"
    }
  ],
  "next_cursor": null
}

Get a runaway

GET/v1/runaways/{id}

Requires the scope runaways:read.

Available from phase 2

One report. The photo's url is a signed link valid for 15 minutes.

Request

curl "https://api.ambula.nl/v1/runaways/w_8Rt1" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "id": "w_8Rt1",
  "status": "active",
  "name": "Bobby",
  "species": "Hond",
  "breed": "Labrador",
  "danger_level": "green",
  "owner": {
    "name": "J. de Vries",
    "phone": "+31687654321"
  },
  "location": {
    "address": "Maliebaan, Utrecht",
    "latitude": 52.087,
    "longitude": 5.13
  },
  "photo": {
    "url": "https://storage.googleapis.com/…",
    "expires_at": "2026-11-09T09:15:00Z"
  },
  "created_at": "2026-11-08T17:40:00Z",
  "updated_at": "2026-11-09T07:55:00Z"
}

Create a runaway

POST/v1/runaways

Requires the scope runaways:write.

Available from phase 2

Report a lost or escaped animal.

Body

speciesstringrequired

Species.

namestring

The animal's name.

danger_levelstring

green, orange or red: how careful to be when approaching.

ownerobject

name and phone.

locationobject

Where it was last seen.

Request

curl -X POST "https://api.ambula.nl/v1/runaways" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…" \
  -H "Content-Type: application/json" \
  -d '{"species":"Hond","name":"Bobby","danger_level":"green"}'

Response · 201

{
  "id": "w_8Rt1",
  "status": "active",
  "name": "Bobby",
  "species": "Hond",
  "breed": "Labrador",
  "danger_level": "green",
  "owner": {
    "name": "J. de Vries",
    "phone": "+31687654321"
  },
  "location": {
    "address": "Maliebaan, Utrecht",
    "latitude": 52.087,
    "longitude": 5.13
  },
  "photo": null,
  "created_at": "2026-11-08T17:40:00Z",
  "updated_at": "2026-11-09T07:55:00Z"
}

Update a runaway

PATCH/v1/runaways/{id}

Requires the scope runaways:write.

Available from phase 2

Change a report. Send If-Match with the ETag from your last read.

Body

locationobject

Where it was last seen.

Request

curl -X PATCH "https://api.ambula.nl/v1/runaways/w_8Rt1" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"location":{"address":"Wilhelminapark, Utrecht"}}'

Response · 200

{
  "id": "w_8Rt1",
  "status": "active",
  "name": "Bobby",
  "species": "Hond",
  "breed": "Labrador",
  "danger_level": "green",
  "owner": {
    "name": "J. de Vries",
    "phone": "+31687654321"
  },
  "location": {
    "address": "Maliebaan, Utrecht",
    "latitude": 52.087,
    "longitude": 5.13
  },
  "photo": {
    "url": "https://storage.googleapis.com/…",
    "expires_at": "2026-11-09T09:15:00Z"
  },
  "created_at": "2026-11-08T17:40:00Z",
  "updated_at": "2026-11-09T07:55:00Z"
}

Close a runaway

DELETE/v1/runaways/{id}

Requires the scope runaways:write.

Available from phase 2

Remove a report once the animal is found.

Set the photo

PUT/v1/runaways/{id}/photo

Requires the scope runaways:write.

Available from phase 2

Upload a photo as multipart/form-data (field photo, up to 10 MB). Location data and other metadata are removed. Replaces the previous photo.

Request

curl -X PUT "https://api.ambula.nl/v1/runaways/w_8Rt1/photo" \
  -H "Authorization: Bearer amb_live_<key>" \
  -F "photo=@bobby.jpg"

Response · 200

{
  "photo": {
    "url": "https://storage.googleapis.com/…",
    "expires_at": "2026-11-09T09:15:00Z"
  }
}