Publishing

Publish a text story as the pilot

Publishes a text story by the pilot of a grant that holds stories.write, with the subject standard, or flight with an origin and a destination, two different airport codes of 3 or 4 letters and digits. Any other subject, a flight without both airports, or either airport on a standard story is 400 invalid_request. A story lives 48 hours. 201 for a new story; 200 with replayed true for a retry of the same client_ref and body, which publishes nothing. A pilot holds at most five active stories, whoever published them: a sixth is 409 story_cap, and its client_ref stays free. See the Publishing tag for the client_ref, mentions, the allowance of 5 stories per grant per rolling 24 hours and removals. A grant that is revoked, unknown or another partner’s answers 404 not_found; a grant, or a token, without stories.write is 403 scope_missing.

POST

partner

grants

{grant_id}

stories

Publish a text story as the pilot

curl --request POST \
  --url https://{devApiHost}/v1/partner/grants/{grant_id}/stories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_ref": "logbook-entry-20261107-02",
  "subject": "flight",
  "caption": "Heading east tonight.",
  "origin": "KJFK",
  "destination": "EGLL"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_ref: 'logbook-entry-20261107-02',
    subject: 'flight',
    caption: 'Heading east tonight.',
    origin: 'KJFK',
    destination: 'EGLL'
  })
};

fetch('https://{devApiHost}/v1/partner/grants/{grant_id}/stories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/{grant_id}/stories"

payload = {
    "client_ref": "logbook-entry-20261107-02",
    "subject": "flight",
    "caption": "Heading east tonight.",
    "origin": "KJFK",
    "destination": "EGLL"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "story_id": "4c7d2e90-1a6b-4f38-9d25-6e0b3a8c1f77",
  "replayed": true
}

{
  "story_id": "4c7d2e90-1a6b-4f38-9d25-6e0b3a8c1f77",
  "replayed": false
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "personal_contact"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "scope_missing"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Request conflicts with an earlier operation.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "story_cap"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "unprocessable",
    "message": "Request cannot be applied.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "mentions_not_allowed"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "publication_throttled"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials. Request a token from the token endpoint of the identity provider's domain (https://{cognito-domain}/oauth2/token, with HTTP Basic client authentication) and send it as a Bearer token. Production uses auth.mypilotindex.com. The sandbox uses the dev environment's Cognito domain, which is given to the partner with its sandbox credential. A token carries only the scopes the partner was approved for.

Path Parameters

grant_id

string<uuid>

required

Body

application/json

Maximum 4096 bytes. Exactly client_ref, subject and caption, and for a flight origin and destination; unknown or repeated members are rejected.

client_ref

string

required

The partner's own name for this create, unique per partner and kind of publication. Send the same ref to retry.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9._:-]{1,64}$

subject

enum<string>

required

Available options:

standard,

flight

caption

string

required

The story's text, up to 200 UTF-16 units after surrounding whitespace is trimmed. No control characters but line breaks and tabs, and no @handle or @all.

Required string length: 1 - 200

origin

string

Required on a flight and refused on a standard story. An airport code of 3 or 4 letters and digits.

destination

string

Required on a flight and refused on a standard story. A code other than the origin.

Response

A retry of a create already made; nothing was published.

story_id

string<uuid>

required

The story; a removal names it.

replayed

boolean

required

True when this client_ref had already made the story and nothing was published.

⌘I

Publish a text story as the pilot

curl --request POST \
  --url https://{devApiHost}/v1/partner/grants/{grant_id}/stories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_ref": "logbook-entry-20261107-02",
  "subject": "flight",
  "caption": "Heading east tonight.",
  "origin": "KJFK",
  "destination": "EGLL"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_ref: 'logbook-entry-20261107-02',
    subject: 'flight',
    caption: 'Heading east tonight.',
    origin: 'KJFK',
    destination: 'EGLL'
  })
};

fetch('https://{devApiHost}/v1/partner/grants/{grant_id}/stories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/{grant_id}/stories"

payload = {
    "client_ref": "logbook-entry-20261107-02",
    "subject": "flight",
    "caption": "Heading east tonight.",
    "origin": "KJFK",
    "destination": "EGLL"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "story_id": "4c7d2e90-1a6b-4f38-9d25-6e0b3a8c1f77",
  "replayed": true
}

{
  "story_id": "4c7d2e90-1a6b-4f38-9d25-6e0b3a8c1f77",
  "replayed": false
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "personal_contact"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "scope_missing"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Request conflicts with an earlier operation.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "story_cap"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "unprocessable",
    "message": "Request cannot be applied.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "mentions_not_allowed"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "correlation_id": "0af7651916cd43dd8448eb211c80319c",
    "reason": "publication_throttled"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

Overview

Grants

Jobs

Publishing

Insights

Certificates

Webhooks

Publish a text story as the pilot

Authorizations

Path Parameters

Body

Response