Skip to content

JSON API

This page covers the EruvStatus JSON endpoints for websites, apps, and other integrations.

List all published eruvin

If you need a list of all published eruvin on the site, use:

https://eruvstat.us/api/v2/eruvin

Example response:

{
  "eruvin": [
    {
      "id": 123,
      "title": "Skokie",
      "url": "/skokie",
      "city": "Skokie",
      "state": "Illinois",
      "status_url": "/api/v2/eruv/123/status"
    },
    {
      "id": 456,
      "title": "West Rogers Park",
      "url": "/west-rogers-park",
      "city": "Chicago",
      "state": "Illinois",
      "status_url": "/api/v2/eruv/456/status"
    }
  ],
  "meta": {
    "version": 2,
    "count": 2
  }
}

Current status API

If you need the current status in JSON format for another website or app, use this v2 endpoint:

https://eruvstat.us/api/v2/eruv/{id}/status

Replace {id} with your eruv ID. You can find your eruv ID on the Eruv Settings page under Basic Info.

If you only need a website embed snippet instead of JSON data, see Embed the current status on another website.

This endpoint returns more detail:

{
  "eruv": {
    "id": 123,
    "title": "Skokie",
    "url": "/skokie"
  },
  "status": {
    "raw": "up",
    "effective": "not checked",
    "is_pending": false,
    "is_expired": true,
    "message": ""
  },
  "timestamps": {
    "created_unix": 1773436352,
    "created_iso": "2026-03-13T21:12:32+00:00",
    "expires_unix": 1773609152,
    "expires_iso": "2026-03-15T21:12:32+00:00",
    "display_date": "13 March 2026"
  },
  "timezone": {
    "api": "UTC",
    "display": "America/New_York"
  },
  "tokens": {
    "date": "13 March 2026",
    "title": "Skokie",
    "status": "UP",
    "candles": "7:16 pm",
    "havdalah": "8:19 pm",
    "parsha": "Parshas Tazria-Metzora"
  },
  "history": [],
  "meta": {
    "version": 2,
    "legacy_endpoint": "/eruv/123/json",
    "history_limit": 10,
    "history_max": 10
  }
}

This endpoint also includes recent status history.

It also includes current token values such as:

  • parsha
  • candles
  • havdalah

You can ask for fewer history items if you want:

https://eruvstat.us/api/v2/eruv/{id}/status?history=5

The history list is capped at 10 items.

Legacy JSON API

The older endpoint is still available, but it is deprecated:

https://eruvstat.us/eruv/{id}/json

Use it only if you already have something that depends on the old format.

Example response:

[
  {
    "created": "1733507169",
    "field_status": "not checked",
    "field_status_info": "Parshas Vayeitzei",
    "field_date": "06 December 2024"
  }
]

Remote status update API

If you want a third-party service to post a status update without logging into Drupal, use this endpoint:

https://eruvstat.us/api/v2/eruv/{id}/status-update

This endpoint requires:

  • your eruv ID
  • your eruv's Status Update API Token

You can find the token in Eruv Settings under Settings → Advanced Settings.

If you need to replace the token, open Advanced Settings, check Generate new API token on save, and save the form. The previous token stops working as soon as the form is saved.

If an integration wants to check whether its token is valid before sending a real status update, it can call this verification endpoint:

https://eruvstat.us/api/v2/eruv/{id}/status-update/verify

Example:

curl -i "https://eruvstat.us/api/v2/eruv/123/status-update/verify" \
  -H "Authorization: Bearer YOUR_STATUS_UPDATE_TOKEN"

A valid token returns 204 No Content.

An invalid token, missing token, or wrong eruv ID returns:

  • 401 Invalid API credentials.

The verification endpoint is rate limited separately from status submissions. After 30 verification attempts within 10 minutes from the same IP address for the same eruv, it returns:

  • 429 Too many token verification attempts. Please try again later.

Example curl request:

curl -X POST "https://eruvstat.us/api/v2/eruv/123/status-update" \
  -H "Authorization: Bearer YOUR_STATUS_UPDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "up",
    "message": "Checked before Shabbos.",
    "expiration_time": 48
  }'

JSON requests that start with { or [ are also accepted when a client forgets to send the Content-Type header, but it is still best to include Content-Type: application/json.

Standard form posts are supported too:

curl -X POST "https://eruvstat.us/api/v2/eruv/123/status-update" \
  -H "Authorization: Bearer YOUR_STATUS_UPDATE_TOKEN" \
  --data-urlencode "status=up" \
  --data-urlencode "message=Checked before Shabbos." \
  --data-urlencode "expiration_time=48"

The message field supports the same display tokens used elsewhere in EruvStatus, including:

  • [date]
  • [title]
  • [status]
  • [candles]
  • [havdalah]
  • [parsha]

Example:

curl -X POST "https://eruvstat.us/api/v2/eruv/123/status-update" \
  -H "Authorization: Bearer YOUR_STATUS_UPDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "up",
    "message": "Candle lighting is [candles]. This week is [parsha].",
    "expiration_time": 48
  }'

[message] is not expanded inside the message field itself.

Allowed status values are:

  • up
  • down
  • pending

Allowed expiration_time values are:

  • 24
  • 48
  • 72

Common error responses:

  • 401 Invalid API credentials. when the bearer token is missing, invalid, or the eruv ID does not exist
  • 409 Duplicate status update rejected. Identical updates must be at least 60 seconds apart. when the same update is submitted again too quickly
  • 415 Unsupported request body. Send JSON or form data. when the request body is not valid JSON or a real form post
  • 422 Only status, message, and expiration_time are supported. when a request tries to send extra fields outside the limited API contract
  • 422 validation errors when status or expiration_time uses an unsupported value
  • 429 Too many status update attempts. Please try again later. after 10 write attempts within 10 minutes from the same IP address for the same eruv

Rate-limited responses include Retry-After: 600 so clients know when to try again.

The endpoint creates a normal EruvStatus status update, so your standard site behavior still applies after submission.

When to contact support

Contact info@eruvstat.us if you need help with:

  • locked eruv fields
  • changing the sending phone number
  • advanced integrations beyond the standard admin tools