General


base="https://platform-api.parachute.live/v0"

The Parachute Platform API gives you programmatic control of the Parachute Platform. The Parachute Platform API is available to all organizations using the Parachute Platform.

All Parachute Platform resources are accessed by prepending $base to the resource’s path.

Versioning

The Parachute Platform API is versioned. The current major version is version 0. No dictionary keys will be removed through releases of the same major version. Minor version releases of the same major version may only introduce new dictionary keys.

Authentication


curl -H "Authorization: Token $api_key"

Authenticate by passing in your API Key using the HTTP Authorzation header.

The API Key is shown in the dashboard’s Account page

Profile

curl -H "Authorization: Token $api_key"
  "$base/me.json"

{
  "name": "Org Admin",
  "email": "admin@demo.org",
  "organization": {
    "name":"Demo Organization",
    "hotlines": [
      {
        "name": "Demo Hotline",
        "path": "/hotlines/Rp7sbAY8FIdylX9U6033kQ"
      }
    ],
    "endpoints": [
      {
        "name": "Demo Endpoint",
        "path": "/endpoints/B6zMBe2WCiIcsemmtVxgcA"
      }
    ],
    "apps": [
      {
        "name": "Demo App",
        "path": "/apps/G7e2hGNfemjdmg_fssUpxA"
      }
    ],
    "devices": [
      {
        "name": "Demo App",
        "path": "/devices/ZGzz3Etvp25ooaqeDwnBVA"
      }
    ]
  }

}

See your profile and your organization’s profile summary

HTTP Request

GET me

Organization Dictionary

Parameter	Description
name	The name of the organization
hotlines	The Parachute hotlines the organization owns
endpoints	The Parachute endpoints the organization owns
apps	The Parachute-connected apps the organization owns
devices	The Parachute-connected devices the organization owns

Hotline

Hotline Overview

curl -H "Authorization: Token $api_key"
  "$base/hotlines/026YAeAzkBZjro75cpDUMw.json"

{
  "name": "Demo Hotline",
  "description": "Demo hotline description",
  "description_url": "http://demo.org",
  "privacy_policy_url": "http://demo.org/privacy",
  "add_link": "https://parachute.live/web/hotlines/026YAeAzkBZjro75cpDUMw/add"

}

Get general details about the hotline

HTTP Request

GET <hotline_path>

Hotline Dictionary

Parameter	Description
name	The name of the hotline, shown to the user before adding
description	A brief description of what the hotline is about, shown to the user before adding
description_url	A url with more information about the hotline, shown to the user before adding
privacy_policy_url	A url with your hotline’s privacy policy, shown to the user before adding
add_link	A web url that can be shared with anyone you would like to send incidents to the hotline. When opened on the user’s phone, it directs the user to the Parachute app and displays a screen that lets the user add the hotline to their emergency contacts

Hotline Users


curl -H "Authorization: Token $api_key"
  "$base/hotlines/026YAeAzkBZjro75cpDUMw/users.json"

{
  "users":[
    {
      "name": "Person 1",
      "email": "person1@gmail.com",
      "added_at": "2016-01-01T00:00:00.000Z"
    }
  ]
}

Get the users who have added the hotline to their emergency contacts

HTTP Request

GET <hotline_path>/users

User Dictionary

Parameter	Description
name	The name of the user
email	The user’s email
added_at	The time at which the user added the hotline to their emergency contacts

Hotline Incidents


curl -H "Authorization: Token $api_key"
  "$base/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares.json"

{
  "incident_shares":[
    {
      "label":"Protest Angle 1",
      "method": "shared",
      "created_at": "2016-01-01T00:00:00.000Z",
      "path": "/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA",
      "incident": {
        "path":"/incidents/S3Z8WuRCOI2_mSSRxujmLA",
        "web_url":"https://parachute.live/web/S3Z8WuRCOI2_mSSRxujmLA",
        "created_at": "2016-01-01T00:00:00.000Z",
        "client_created_at": "2016-01-01T00:00:00.000Z",
        "ended_at": "2016-01-01T00:00:00.000Z",
        "client_ended_at":"2016-01-01T00:00:00.000Z",
        "user": {
          "name": "Person 1"
        }
      }
    }
  ]
}

Get the incidents shared with the hotline

HTTP Request

GET <hotline_path>/incident_shares

See Incident Share

Hotline Composites


curl -H "Authorization: Token $api_key"
  "$base/hotlines/026YAeAzkBZjro75cpDUMw/composites.json"

{
  "composites":[
    {
      "name":"Protest Composite",
      "status": "done",
      "created_at": "2016-01-01T00:00:00.000Z",
      "path": "/composites/CPVTiHgcrIdl6jMcuWEJuQ",
      "web_url": "https://platform.parachute.live/web/composites/CPVTiHgcrIdl6jMcuWEJuQ"
    }
  ]
}

Get the hotline’s composites

HTTP Request

GET <hotline_path>/composites

Composite Dictionary

See Composite


curl -H "Authorization: Token $api_key"
  "$base/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA.json"


{
  "label":"Protest Angle 1",
  "method": "shared",
  "created_at": "2016-01-01T00:00:00.000Z",
  "incident": {  
    "path":"/incidents/S3Z8WuRCOI2_mSSRxujmLA",
    "web_url":"https://parachute.live/web/S3Z8WuRCOI2_mSSRxujmLA",
    "created_at": "2016-01-01T00:00:00.000Z",
    "client_created_at": "2016-01-01T00:00:00.000Z",
    "ended_at": "2016-01-01T00:00:00.000Z",
    "client_ended_at":"2016-01-01T00:00:00.000Z",
    "user": {
      "name": "Person 1"
    },
    "locations": [
      {
        "created_at": "2016-01-01T00:00:00.000Z",
        "client_created_at": "2016-01-01T00:00:00.000Z",
        "latitude": "40.7007216017257",
        "longitude": "-73.9871011714297",
        "horizontal_accuracy": "65.0",
        "vertical_accuracy": "2016-01-01T00:00:00.000Z",
        "altitude": "13.0"
      }
    ],
    "video": {
      "mp4_container_url":"https://platform.parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/video.mp4",
      "event_playlist_url":"https://parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/playlists/event.m3u8",
      "vod_playlist_url":"https://parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/playlists/vod.m3u8"
    },
    "custom_data": [
      {
        "created_at": "2016-01-01T00:00:00.000Z",
        "client_created_at": "2016-01-01T00:00:00.000Z",
        "type": "heartrate",
        "provider": "apple_watch",
        "data": {}
      }
    ]
  }
}

HTTP Request

GET <incident_share_path>

Parameter	Description
label	A custom label assigned to the incident
method	`shared`: The incident was shared automatically because the hotline was in the user’s emergency contacts `imported`: The incident was manually imported into the hotline by one of the admins
created_at	The time at which the incident was shared or imported
incident	Incident dictionary

Incident Dictionary

Parameter	Description
web_url	The web panel for the incident
created_at	The time at which Parachute received the new incident’s activation message, according to Parachute’s clock
client_created_at	The time at which the user activated Parachute, according to the user’s clock
ended_at	The time at which Parachute received the incident’s ended message, according to Parachute’s clock
client_ended_at	The time at which the user ended Parachute, according to the user’s clock
user	A dictionary with the user’s info
locations	A chronologically ordered list of locations. See Locations
video	A dictionary with information on the video received. See Video Dictionary
custom_data	A chronologically ordered list of custom data. See Custom Data Dictionary

Location Dictionary

Parameter	Description
created_at	The time at which Parachute received the location update, according to Parachute’s clock
client_created_at	The time at which the location update was generated, according to the user’s clock

Video Dictionary

Live and On-Demand incident video is provided in two formats:

HTTP Live Streaming for maximum compatibility with mobile devices. This is the recommended video format for streaming incident video and will be edge-cached
Standard MPEG-4 container. This is the recommended video format for downloading incident video. It will not be edge-cached and should not be used for streaming

Parameter	Description
mp4_container_url	A web url to the MP4 container video. The MP4 container has its `moov` atom moved to the font to enable fast start.
event_playlist_url	A web url to the HLS live event playlist. The event playlist is ended only if the user has ended the Parachute incident
vod_playlist_url	A web url to the HLS video on demand (VOD) playlist

Custom Data Dictionary

Custom data is an extensible way to attach any timestamped data to an incident. Custom data can be set in real time, e.g. through devices connected to the Parachute app, or post-incident, e.g. through a post-processing script running an image processing algorithm. Anyone can attach custom data to an incident, but only the author can delete custom data. Custom data may be publicly available or private to each organization

Parameter	Description
created_at	The time at which Parachute received the data, according to Parachute’s clock
client_created_at	The time at which the user generated the data, according to the user’s clock. For data added post-incident, this field should be left blank
type	The type of data attached
provider	The generator or provider of data attached
data	A dictionary of custom data

Composite


curl -H 'Authorization: Token $api_key'
  "$base/hotlines/026YAeAzkBZjro75cpDUMw/composites/CPVTiHgcrIdl6jMcuWEJuQ.json"


{
  "name": "Protest Composite 1",
  "status": "done",
  "created_at": "2016-01-01T00:00:00.000Z",
  "updated_at": "2016-01-01T00:00:00.000Z",
  "web_url": "https://platform.parachute.live/web/composites/CPVTiHgcrIdl6jMcuWEJuQ",
  "video": {
    "mp4_container_url":"https://platform.parachute.live/web/composites/CPVTiHgcrIdl6jMcuWEJuQ/video.mp4"
  },
  "composite_containments": [
    {
      "label": "Protest Angle 1",
      "short_label": "1",
      "order": 0,
      "clock_skew": 0.4,
      "incident_share": {
        "label":"Protest Angle 1",
        "method": "shared",
        "created_at": "2016-01-01T00:00:00.000Z",
        "incident": {  
          "path":"/incidents/S3Z8WuRCOI2_mSSRxujmLA",
          "web_url":"https://parachute.live/web/S3Z8WuRCOI2_mSSRxujmLA",
          "created_at": "2016-01-01T00:00:00.000Z",
          "client_created_at": "2016-01-01T00:00:00.000Z",
          "ended_at": "2016-01-01T00:00:00.000Z",
          "client_ended_at":"2016-01-01T00:00:00.000Z",
          "user": {
            "name": "Person 1"
          },
          "locations": [
            {
              "created_at": "2016-01-01T00:00:00.000Z",
              "client_created_at": "2016-01-01T00:00:00.000Z",
              "latitude": "40.7007216017257",
              "longitude": "-73.9871011714297",
              "horizontal_accuracy": "65.0",
              "vertical_accuracy": "2016-01-01T00:00:00.000Z",
              "altitude": "13.0"
            }
          ],
          "video": {
            "mp4_container_url":"https://platform.parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/video.mp4",
            "event_playlist_url":"https://parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/playlists/event.m3u8",
            "vod_playlist_url":"https://parachute.live/web/incidents/S3Z8WuRCOI2_mSSRxujmLA/playlists/vod.m3u8"
          },
          "custom_data": [
            {
              "created_at": "2016-01-01T00:00:00.000Z",
              "client_created_at": "2016-01-01T00:00:00.000Z",
              "type": "heartrate",
              "provider": "apple_watch",
              "data": {}
            }
          ]
        }
      }
    }
  ]
}

Get all data on a composite

HTTP Request

GET <composite_path>

Composite Dictionary

Parameter	Description
name	The name (title) of the composite
status	An opaque string representing the status of the compositing process. `done`: The composite is ready for viewing and the composite video has been created Not `done`: The composite is not ready for viewing and the composite video has not been created
created_at	The timestamp at which the composite was created
updated_at	The timestamp at which the composite was last updated. The composite will not reflect any updates to incidents after this time
web_url	The web panel for the composite

Video Dictionary

Composite video is provided in a single format:

Standard MPEG-4 container. Depending on your account, this may or may not be edge-cached

Parameter	Description
mp4_container_url	A web url to the MP4 container video. The MP4 container has its `moov` atom moved to the font to enable fast start.

Composite Containment Dictionary

A composite containment holds the properties describing the containment of the incident share in the composite, e.g. the order at which the incident share appears on the screen.

Parameter	Description
label	The label provided to the incident for the purposes of this composite. Unless explicitly set by the user, the label of the composite containment is copied from the label of the incident
short_label	An abbreviated label used to identify the incident inside the composite
order	The order in which the incident appears in the composite. By default, incidents are ordered chronologically from left to right and top to bottom
clock_skew	The clock skew of the incident relative to the master clock of the composite. The clock skew can be set manually on composite creation.

See Incident Share

Event Webhook

curl -X POST 
  -H 'Content-Type: application/json' 
  -d '{ 
    "name":"event_key", 
    "guid":"MKMnRkAzHUiSJeXLlpuoLQ", 
    "created_at":"2016-01-01T00:00:00.000Z",
    "hotline":
    {
      "path":"/hotlines/026YAeAzkBZjro75cpDUMw"
    },
    "organization":
    {
      "name": "Demo Organization"
    },
    "route":
    {
      "path":"/hotlines/026YAeAzkBZjro75cpDUMw/routes/3RQpUDCJJ2pGImBxPH3lge"
    },
    "event_key":{} 
    }'
  https://demo.org/parachute_endpoint/events

Event webhooks are capable of delivering the full firehose of events associated with a Hotline in real time to a Custom Endpoint you configure via the Dashboard’s Endpoints page. For a webhook to be called, a Route to the Custom Endpoint must be added to a Hotline and the Route’s rules must match. Events are not throttled. Parachute imposes a 15-second timeout for a Custom Endpoint to respond. Only 2xx HTTP status codes are considered to be valid, and redirects are not followed.

The Hotline’s “Routes” tab displays each Route configured for the Hotline, as well as the rules for when each Route is called.

Each webhook call is logged at the Hotline’s “Events” tab.

HTTP Request to Custom Endpoint

POST <custom_endpoint_url>

Event Dictionary

Parameter	Description
name	The name of the event. Clients must ignore event names they do not recognize. A sample implementation would have a top-level switch statement. The name of the event is also the key by which additional information on the event is accessed. E.g. an event of name `event_key` may provide additional data under the `event_key` key
guid	An ID that is globally unique for the event within the scope of `name`. In rare circumstances, events may be delivered more than once. Endpoint developers should anticipate this scenario by using the event’s guid
created_at	The timestamp at which the event was created
hotline	The hotline for which the event was generated
organization	The organization for which the event was generated
route	The route for which the event was generated
event_key	A dictionary containing the information about the event (the payload of the event). The `event_key` is the value of the `name` key. The payload of the event is guaranteed to contain the path to the resource generating the event. For convenience, the payload of the event may contain data beyond what is covered in this documentation to alleviate the need to perform an extra query on the resource

{
  "name":"new_incident_share",
  "guid":"MKMnRkAzHUiSJeXLlpuoLQ",
  "created_at":"2016-01-01T00:00:00.000Z",
  "new_incident_share": {
    "incident_share":{
      "path": "/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA"
    }
  }
}

Delivered when a new incident is shared with the hotline

See Incident Share

New Location Event

{
  "name":"incident_share_new_location",
  "guid":"MKMnRkAzHUiSJeXLlpuoLQ",
  "created_at":"2016-01-01T00:00:00.000Z",
  "incident_share_new_location": {
    "incident_share":{
      "path": "/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA"
    }
  }
}

Delivered when a new location is received for an incident

See Incident Share

New Video Keyframe Event

{
  "name":"incident_share_new_video_keyframe",
  "guid":"MKMnRkAzHUiSJeXLlpuoLQ",
  "created_at":"2016-01-01T00:00:00.000Z",
  "incident_share_new_video_keyframe": {
    "incident_share":{
      "path": "/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA"
    }
  }
}

Delivered when a new video keyframe is received for an incident. Keyframes are defined as H.264 Instantaneous Decoder Refresh I-frames. The Parachute apps will typically generate one keyframe every 150 frames or 5 seconds.

See Incident Share

New Custom Data Event

{
  "name":"incident_share_new_custom_data",
  "guid":"MKMnRkAzHUiSJeXLlpuoLQ",
  "created_at":"2016-01-01T00:00:00.000Z",
  "incident_share_new_custom_data": {
    "incident_share":{
      "path": "/hotlines/026YAeAzkBZjro75cpDUMw/incident_shares/GQXeER5vpLunSyqJcQZfVA"
    }
  }
}

Delivered when new custom data is received for an incident

See Incident Share

New User Event

{
  "name":"hotline_new_user",
  "guid":"MKMnRkAzHUiSJeXLlpuoLQ",
  "created_at":"2016-01-01T00:00:00.000Z",
  "hotline_new_user": {
    "user":{
      "name": "Person 1",
      "email": "person1@gmail.com",
      "added_at": "2016-01-01T00:00:00.000Z"
    }
  }
}

Delivered when a new user adds the hotline to their emergency contacts.

User Dictionary

See Hotline Users

General

Versioning

Authentication

Profile

HTTP Request

Organization Dictionary

Hotline

Hotline Overview

HTTP Request

Hotline Dictionary

Hotline Users

HTTP Request

User Dictionary

Hotline Incidents

HTTP Request

Incident Share Dictionary

Hotline Composites

HTTP Request

Composite Dictionary

Incident Share

HTTP Request

Incident Share Dictionary

Incident Dictionary

Location Dictionary

Video Dictionary

Custom Data Dictionary

Composite

HTTP Request

Composite Dictionary

Video Dictionary

Composite Containment Dictionary

Incident Share Dictionary

Event Webhook

HTTP Request to Custom Endpoint

Event Dictionary

New Incident Share Event

Incident Share Dictionary

New Location Event

Incident Share Dictionary

New Video Keyframe Event

Incident Share Dictionary

New Custom Data Event

Incident Share Dictionary

New User Event

User Dictionary