# Mahsaalert — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Track real-time safety information across Iran by accessing map data on danger zones, confirmed attacks, evacuation warnings, citizen reports, and military sites filtered by location and category. Monitor specific areas or search for detailed information about threats and incidents in your region of interest.

**Category:** Maps & Geospatial | **Website:** [mahsaalert.app/](https://mahsaalert.app/) | **Docs:** [parse.bot/marketplace/0faeaa1a-2fb4-4801-8dff-7185ac420ee6/mahsaalert-app-api](https://parse.bot/marketplace/0faeaa1a-2fb4-4801-8dff-7185ac420ee6/mahsaalert-app-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/mahsaalert/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get feature detail

Get detailed information about a specific map feature by its ID. Returns coordinates, metadata, status, timestamps, and associated media.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `feature_id` | integer | Yes | Feature ID (obtained from get_layer_features or get_map_data results) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mahsaalert/get-feature-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"feature_id":"<integer>"}'
```

### Get layer features

Get features for a specific map layer by layer key or ID. Optionally filter by bounding box. Returns feature coordinates, properties (name, city, province, description, date), and status. Supports pagination via limit and offset.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bbox` | string | No | Bounding box filter: min_lon,min_lat,max_lon,max_lat (e.g. '51.0,35.5,51.8,35.9' for Tehran area) |
| `layer_id` | integer | No | Layer ID number. Either layer_key or layer_id is required. |
| `layer_key` | string | No | Layer key (e.g. 'nuclearPrograms', 'missilePrograms', 'antiAirBase', 'radarBase', 'areowayBase', 'newTargets', 'evacAreaII', 'citizenReport', 'targets', 'protestPoint'). Use get_layers to see all available keys. Either layer_key or layer_id is required. |
| `limit` | integer | No | Maximum number of features to return |
| `offset` | integer | No | Offset for pagination |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mahsaalert/get-layer-features \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"bbox":"<string>","layer_id":"<integer>","layer_key":"<string>","limit":"<integer>","offset":"<integer>"}'
```

### Get layers

Get all available map layers with metadata including layer keys, categories, property schemas, and update timestamps. Use the returned layer keys/IDs to query features via get_layer_features or get_map_data.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mahsaalert/get-layers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get map data

Get map features from multiple layers at once, filtered by bounding box and/or category. Defaults to Tehran area bbox. Returns features grouped by layer. Useful for getting an overview of all features in a geographic area.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bbox` | string | No | Bounding box: min_lon,min_lat,max_lon,max_lat |
| `category` | string | No | Filter by category name (e.g. 'Danger Zones', 'Monitor', 'Suppression Sites', 'Medical sites', 'Iran-Israel War', 'DeyMah-Protests') |
| `layer_keys` | string | No | Comma-separated layer keys to include (e.g. 'nuclearPrograms,missilePrograms,antiAirBase'). If omitted, includes all enabled layers. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mahsaalert/get-map-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"bbox":"<string>","category":"<string>","layer_keys":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.