For AI Agents

You are an integration assistant for the Synaptic Aviation API.

Follow the Synaptic API skill at /for-ai-agents/skill.md (or the "For AI Agents" page on the Synaptic API docs site). Use only documented endpoints. Do not invent fields, event names, or authentication schemes.

Base URL: https://api.synapticaviation.io/v2

Authentication:
- POST https://api.synapticaviation.io/v2/user/login with JSON {"email","password"} to obtain a JWT.
- Send Authorization: Bearer <token> (JWT or API key from Settings).
- Tokens expire in 7 days by default. Never print full secrets in logs or chat.

Hard rules:
- Datetime fields are airport-local wall-clock times. JSON often appends a trailing Z; that does NOT mean UTC. Do not convert from UTC.
- Access is scoped by airline, station/location, and gate. Empty results often mean no access, not a missing API.
- List webhook events the user can subscribe to with GET https://api.synapticaviation.io/v2/webhooks before subscribing.
- Subscribe with POST https://api.synapticaviation.io/v2/webhooks/subscribe using WebhookId, EventSubscriberId (user email), and EventPostbackUrl.
- Paginate list endpoints with offset and limit.

When writing code, prefer curl or fetch examples that match the docs. If a required value is missing (token, WebhookId, gate, dates), ask for it instead of guessing.

---
name: synaptic-api
description: Use the Synaptic Aviation API to list flights, retrieve gate videos, list subscribeable operational events, manage webhooks, check camera heartbeat, and fetch dashboard stats. Use when integrating with Synaptic, calling api.synapticaviation.io, or working with flights, events, or webhooks.
---

# Synaptic Aviation API

Base URL: `https://api.synapticaviation.io/v2`

Human docs: /
This skill (raw): /for-ai-agents/skill.md
Prompt (raw): /for-ai-agents/prompt.txt

## Auth

1. Login:

```bash
curl -X POST https://api.synapticaviation.io/v2/user/login \
  -H "Content-Type: application/json" \
  -d '{"email":"USER_EMAIL","password":"USER_PASSWORD"}'
```

The JSON response includes `token` and `email`.

2. All other requests:

```
Authorization: Bearer TOKEN_OR_API_KEY
```

API keys are created in Settings after login and are also sent as Bearer tokens. JWTs expire in 7 days by default. Never echo full tokens.

## Hard rules

- **Airport-local times:** Fields such as `FlightDateTime`, `EventDateTimeFirstSeen`, and video timestamps are airport-local wall-clock times. JSON serialization often appends `Z`. That suffix is **not** UTC. Do not convert from UTC.
- **Access control:** Results are filtered by the caller's airline, location/station, and gate access. `403` means no access rows; empty `data` often means no matching accessible rows.
- **Do not invent:** Only use endpoints and fields in this skill or the docs. Ask for missing IDs, gates, dates, or tokens.

## Pagination

List endpoints accept `offset` (default 0) and `limit` (often default 10, flights default 25, typical max 100). Responses nest items in `data` and may include `meta.count`.

## Flights

### List flights — GET /v2/flights

Query: `airlineCode`, `departureDate`, `flightNumber`, `location` (airport), `gate`, `tailNumber`, `offset`, `limit`.

```bash
curl -G https://api.synapticaviation.io/v2/flights \
  -H "Authorization: Bearer TOKEN" \
  -d airlineCode="NK" \
  -d location="FLL" \
  -d offset=0 \
  -d limit=25
```

### Get flight + detections — GET /v2/flights/:id

Returns the flight row plus a `detections` array (`VideoURL`, `VideoType`, `DateAdded`).

### Get one event video — GET /v2/flights/:id/:flightProperty

`flightProperty` is an event base name whose `Start`/`End` columns exist on the flight, for example:

`AircraftArriving`, `AircraftDeparting`, `AircraftStationary`, `BeltLoader`, `CateringTruck`, `JetbridgeExtending`, `JetbridgeRetracting`, `JetbridgeConnected`, `PCAConnected`, `PushTruckConnected`.

Missing video returns null fields, not always an error. Missing flight returns 404.

## Videos

### Gate videos — GET /v2/videos

Required query: `Gate`, `StartDateTime`, `EndDateTime` (ISO 8601). Omitting any returns 400.

```bash
curl -G https://api.synapticaviation.io/v2/videos \
  -H "Authorization: Bearer TOKEN" \
  -d Gate="G13" \
  -d StartDateTime="2023-01-01T00:00:00Z" \
  -d EndDateTime="2023-01-02T00:00:00Z"
```

## Events and webhooks

Events are operational signals (aircraft movement, GSE sightings, jet bridge, and more). Consume them by subscribing a postback URL.

### List subscribeable events — GET /v2/webhooks

Returns webhooks the authenticated user may subscribe to:

- `WebhookId` — required to subscribe
- `WebhookName`, `WebhookUrlInfo`, `EventTypeId`

```bash
curl -G https://api.synapticaviation.io/v2/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -d offset=0 \
  -d limit=10
```

### Subscribe — POST /v2/webhooks/subscribe

JSON body:

```json
{
  "WebhookId": "WEBHOOK_ID",
  "EventSubscriberId": "user@email.com",
  "EventPostbackUrl": "https://yourapp.com/webhook",
  "EventPostbackUser": "optional-basic-user",
  "EventPostbackPassword": "optional-basic-password"
}
```

`EventSubscriberId` must be the authenticated user's email. Optional postback user/password enable HTTP Basic auth on each outbound POST.

### Unsubscribe — DELETE /v2/webhooks/unsubscribe?EventSubscriptionId=ID

### Outbound POST body

Synaptic POSTs JSON to `EventPostbackUrl`:

- `payload` — EventPayload (`EventName`, `AirlineCode`, `Gate`, `Station`, `ArrivalFlight#`, `DepartureFlight#`, `TailNumber`, `EventDateTimeFirstSeen`, `EventDateTimeLastSeen`, `MediaUrl`, plus pass-through keys)
- `Summary` — same as `payload.EventName`
- `type` — always `"message"`
- `attachments` — optional Adaptive Card
- `webhookId`, `webhookEventId`, `eventNotificationId`

Common `EventName` values: `AIRCRAFT.ARRIVED`, `AIRCRAFT.STATIONARY`, `AIRCRAFT.DEPARTED`, belt loader / fuel house / catering / GPU / PCA / chocks seen, `JETBRIDGE.CONNECTED`. Always prefer the live `GET /v2/webhooks` catalog over this list.

### Lookups

- GET /v2/webhooks/events/:webhookEventId — persisted event (404 if missing or unauthorized; no separate 403)
- GET /v2/webhooks/notifications/:eventNotificationId — one delivery
- GET /v2/webhooks/notifications?WebhookId=&offset=&limit= — delivery history

Caller must be subscribed (or admin). Notification rows belong to the JWT email.

## Heartbeat

GET /v2/heartbeat/camera/:id

Returns camera online/offline and last heartbeat.

## Dashboard

POST /v2/dashboard/stats

```json
{
  "location": "LAX",
  "start_date": "2021-08-10T14:00:00Z",
  "end_date": "2021-08-10T15:00:00Z"
}
```

Returns departure/arrival on-time stats, turn times, and gate utilization.

## Errors

- 2xx success
- 4xx caller error (`invalid_request` is typical)
- 5xx server error (`api_error`)

Error JSON may include `type`, `message`, and `documentation_url`.

## Workflow

1. Confirm the user has a Bearer token (login or API key).
2. For events: list `GET /v2/webhooks`, pick `WebhookId`, then subscribe.
3. For flights/videos: require airline/airport/gate/time window as needed; do not invent them.
4. Treat `Z` timestamps as airport-local clock time for the station/airport on the record.