API Docs
Introduction
Pilotship offers a REST API that allows you to programmatically read and write items to your team newsletter.

All requests must use HTTPS and the base url is: https://api.pilotship.com

For POST requests, all data must be JSON in the body of the request. The content-type header must be set to application/json
Authorization
Authorization is handled using personal API Keys.
You must include your key in the request header like so: authorization: api_key=YOUR_API_KEY
You can create, modify, and delete keys here: settings/api-keys
Uniqueness
Items are considered unique by their serviceName and serviceId. A hash is created by concatenating these values. If one of these values is not present, a hash is created from the entire item. You are encouraged to use a serviceName and serviceId whenever possible.
Questions?
If you have questions about the API, please join our developers Google group or just send an email to dan@pilotship.com
Methods
/teams/teamId/items
POST https://api.pilotship.com/teams/teamId/items
This method adds items to a team newsletter. In the request body, supply an array of Item Types as defined below. You can add up to 20 items at a time of different types. While many properties are not required, you are encouraged to populate as many as possible.
Item Types
Property Name
Value
Description
Required
type
"event"
yes
title
string
The title of the event.
yes
timestamp
datetime
When the event starts. Must be a Unix millisecond timestamp.
yes
endTimestamp
datetime
When the event ends. Must be a Unix millisecond timestamp.
url
string
A link to this resource. The URL scheme must be HTTP or HTTPS.
summary
string
A longer description of the event. Maximum characters is 1000.
createdTimestamp
datetime
When the event was created. Must be a Unix millisecond timestamp.
serviceName
string
The service the event comes from. Events from the same service will be grouped together. Maximum 30 characters.
serviceId
string
A unique identifier for the event. This is typically the id provided from the service it came from. Maximum 128 characters.
author
string
The full name of the person who created this event. Maximum 100 characters.
authorEmail
string
The email address of the author who created this event. Maximum 100 characters.
authorId
string
A unique identifier for the author who created this event. This is typically the id provided from the service it came from. Maximum 128 characters.
attendees
list
A list of people who will attend this event. Each item must be a valid email address string.
recurrence
string
Does this event recur? Accepted values are daily, weekly, monthly, yearly.
recurringEventId
string
If this event recurs, add a recurringEventId to group recurring events together. Maximum 128 characters.
allDay
boolean
Does the event last all day. Default is false.
boost
number
Not all items will be included in the newsletter. To help us prioritize, you can include a boost score. Accepted values are 0 (no boost), 1 (small boost), 2 (large boost).
[
  {
    "type": "event",
    "title": "Company Offsite",
    "createdAt": 1513031988480
  }
]
Property Name
Value
Description
Required
type
"document"
yes
url
string
A link to this resource. The URL scheme must be HTTP or HTTPS.
yes
title
string
The title of the document. Maximum characters is 200.
timestamp
datetime
When the document was shared, published, or posted. Must be a Unix millisecond timestamp.
category
string
The category of this document. The only valid value is web.
summary
string
A longer description of the document. Maximum characters is 1000.
serviceName
string
The service the document comes from. Documents from the same service will be grouped together. Maximum 30 characters.
serviceId
string
A unique identifier for the document. This is typically the id provided from the service it came from. Maximum 128 characters.
author
string
The full name of the person who shared, published or posted this document. Maximum 100 characters.
authorEmail
string
The email address of the person who shared, published or posted this document. Maximum 100 characters.
authorId
string
A unique identifier for the person who shared, published or posted this document. This is typically the id provided from the service it came from. Maximum 128 characters.
image
string
A link to an image associated with this document. The URL scheme must be HTTP or HTTPS.
icon
string
A link to an icon associated with this document. The URL scheme must be HTTP or HTTPS.
boost
number
Not all items will be included in the newsletter. To help us prioritize, you can include a boost score. Accepted values are 0 (no boost), 1 (small boost), 2 (large boost).
[
  {
    "type": "document",
    "title": "https://example.com/a-great-document"
  }
]
Property Name
Value
Description
Required
type
"metric"
yes
title
string
The title of the metric. Metrics from the same serviceName will be grouped by title.
yes
timestamp
datetime
When the metric occurred. Must be a Unix millisecond timestamp.
yes
value
number
The value of the metric.
yes
previousValue
number
The previous value this metric was at.
previousTimestamp
datetime
When the previous value of this metric occurred. Must be a Unix millisecond timestamp.
averageValue
number
The average expected value of this metric.
category
string
The category of this metric. Valid values are kpi, money, none
unit
string
The unit of this metric. Valid values are $, €, ¥, seconds, milliseconds, count, percent, none
aggregationPeriod
string
The aggregation period of time this metric covers. Valid values are day, week, month, quarter, year, none
url
string
A link to this resource. The URL scheme must be HTTP or HTTPS.
summary
string
A longer description of the metric. Maximum characters is 1000.
serviceName
string
The service the metric comes from. Metrics from the same service will be grouped together. Maximum 30 characters.
serviceId
string
A unique identifier for this metric value. This is typically the id provided from the service it came from. Maximum 128 characters.
author
string
The full name of the person responsible for this metric. Maximum 100 characters.
authorEmail
string
The email address of the person responsible for this metric. Maximum 100 characters.
authorId
string
A unique identifier for the person responsible for this metric. This is typically the id provided from the service it came from. Maximum 128 characters.
boost
number
Not all items will be included in the newsletter. To help us prioritize, you can include a boost score. Accepted values are 0 (no boost), 1 (small boost), 2 (large boost).
[
  {
    "type": "metric",
    "title": "pageViews",
    "createdAt": 1513031988480,
    "value": 3000
  }
]
Property Name
Value
Description
Required
type
"product"
yes
title
string
The title of the product.
yes
category
string
The product category. Valid values are project_new, task_complete.
yes
timestamp
datetime
When the product category occurred. Must be a Unix millisecond timestamp.
yes
summary
string
A longer description of the product category. Maximum characters is 1000.
url
string
A link to this resource. The URL scheme must be HTTP or HTTPS.
serviceName
string
The service the product comes from. Products from the same service will be grouped together. Maximum 30 characters.
serviceId
string
A unique identifier for the product. This is typically the id provided from the service it came from. Maximum 128 characters.
author
string
The full name of the person who is responsible for this product category. Maximum 100 characters.
authorEmail
string
The email address of the person who is responsible for this product category. Maximum 100 characters.
authorId
string
A unique identifier for the person who is responsible for this product category. This is typically the id provided from the service it came from. Maximum 128 characters.
boost
number
Not all items will be included in the newsletter. To help us prioritize, you can include a boost score. Accepted values are 0 (no boost), 1 (small boost), 2 (large boost).
[
  {
    "type": "product",
    "title": "New Landing Page",
    "createdAt": 1513031988480,
    "category": "project"
  }
]
Property Name
Value
Description
Required
type
"quote"
yes
summary
string
The quote text. Maximum 1000 characters.
yes
author
string
The full name of the person who said this quote. Maximum 100 characters.
yes
timestamp
datetime
When the quote was said. Must be a Unix millisecond timestamp.
yes
url
string
A link to this resource. The URL scheme must be HTTP or HTTPS.
serviceName
string
The service the quote comes from. Maximum 30 characters.
serviceId
string
A unique identifier for the quote. This is typically the id provided from the service it came from. Maximum 128 characters.
authorEmail
string
The email address of the person who said this quote. Maximum 100 characters.
authorId
string
A unique identifier for the person who said this quote. This is typically the id provided from the service it came from. Maximum 128 characters.
boost
number
Not all items will be included in the newsletter. To help us prioritize, you can include a boost score. Accepted values are 0 (no boost), 1 (small boost), 2 (large boost).
[
  {
    "type": "quote",
    "summary": "We are the best!",
    "author": "Kan Dantor"
  }
]