Skip to main content
API docs by Redocly

Pigeon Protocol API

Info/Context

Type: API documentation
Audience: Pigeon Protocol users and third-party developers
Purpose: An API reference for the fictitious Pigeon Protocol service, a global delivery network that lets users send messages via carrier pigeon. (Not a functional API, sadly... although if any pigeon breeders happen to be reading this, let's talk!)

You can use the Pigeon Protocol API to dispatch pigeon couriers directly from your command line. Every message you submit is automatically assigned to one of our Pigeon Protocol partners for delivery—and since our courier network spans all seven continents, this means you can send messages to recipients anywhere in the world.

Processing queue

When you submit a message to the Pigeon Protocol API via the Create new message endpoint, your message gets added to our processing queue.

If a message is still in the processing queue, you can use the Edit queued message and Delete queued message endpoints to modify or cancel your message. However, after a pigeon courier has initiated delivery, you won't be able to modify or cancel that message; you can use the Check message status endpoint beforehand to determine whether your message is still in the processing queue (and therefore still possible to modify or cancel).

Authentication

The Pigeon Protocol API uses request-level authentication via Basic auth. To authenticate a request, provide an Authorization header with the value Basic base64(username:password). For example, if your Pigeon Protocol Auth ID is feather and your Pigeon Protocol Auth Key is secret, your Authorization header should be set to Basic ZmVhdGhlcjpzZWNyZXQ=.

Create new message

Adds a new message to the Pigeon Protocol processing queue.

Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

Request Body schema: application/json
required
required
object

Information about the destination where our pigeon courier should send your message.
Note that this object has two children: recipientId and address. You must include at least one of these parameters, and we recommend including both whenever possible.

required
object

Information about the message to send via Pigeon Protocol.

object

Information about when you'd like our pigeon courier to deliver your message. If you include both a min and max value, they must be at least 16 hours apart and no more than 168 hours apart.

requestedCourier
Array of strings

Any specific pigeon courier(s) who you'd like to deliver the message on your behalf. Must be an array of pgnId values listed in order from highest preference to lowest preference.
If no pgnId value is specified, we'll send whichever courier is closest to your recipient's address at the time. (But don't worry—we promise that all of our couriers are top notch.)

object

Other options related to your message and its delivery.

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "message": {
    },
  • "timeframe": {
    },
  • "requestedCourier": [
    ],
  • "extras": {
    }
}

Response samples

Content type
application/json
{
  • "msgId": "4prDjddvmLpDA2A2",
  • "status": "queued",
  • "eta": "2022-03-18T09:30:00.000Z",
  • "cost": 0.15
}

Check message status

Queries the status of the specified message in the Pigeon Protocol system. Depending on your message's status, this endpoint will return different response types with status-specific data.

There are four possible statuses:

  • queued: Your message is still in the Pigeon Protocol's processing queue and awaiting delivery.
  • enroute: A pigeon courier is in the process of delivering your message.
  • delivered: A pigeon courier has successfully delivered your message.
  • refunded: Your message was deleted or otherwise ineligible for delivery. A refund has been applied to your Pigeon Protocol account.
Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

msgId
required
string
Example: 8504913

The ID of the message whose status you'd like to query. This must match the value of the msgId field in the response body returned by the Create new message endpoint when you initially submitted your message to the Pigeon Protocol API.

Responses

Response samples

Content type
application/json
Example
{
  • "msgId": "4prDjddvmLpDA2A2",
  • "status": "queued",
  • "eta": "2022-03-18T09:30:00.000Z",
  • "cost": 0.15
}

Edit queued message

Modifies the specified message in the Pigeon Protocol processing queue. You can edit any of the message's parameters, including its recipient, contents, and delivery options.

Note that updating certain parameters may increase or decrease the cost of your message.

Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

msgId
required
string
Example: 8504913

The ID of the message you'd like to edit. This must match the value of the msgId field in the response body returned by the Create new message endpoint when you initially submitted your message to the Pigeon Protocol API.

Request Body schema: application/json
required
msgId
required
string

The message's unique Pigeon Protocol ID. This must match the value of the msgId field in the response body returned by the Create new message endpoint when you initially submitted your message to the Pigeon Protocol API.

required
object

Any message information you'd like to edit. This object must follow the same core structure as the request body of the Create new message endpoint, but you can omit any children/parameters whose values you don't want to change.

Responses

Request samples

Content type
application/json
{
  • "msgId": "4prDjddvmLpDA2A2",
  • "msgInfo": {
    }
}

Response samples

Content type
application/json
{
  • "msgId": "4prDjddvmLpDA2A2",
  • "status": "queued",
  • "eta": "2022-03-22T09:30:00.000Z",
  • "cost": 0.12
}

Cancel queued message

Deletes the specified message in the Pigeon Protocol processing queue.

If your message is deleted successfully, we'll apply a refund to your Pigeon Protocol account.

Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

msgId
required
string
Example: 8504913

The ID of the message you'd like to cancel. This must match the value of the msgId field in the response body returned by the Create new message endpoint when you initially submitted your message to the Pigeon Protocol API.

Responses

Response samples

Content type
application/json
{
  • "msgId": "4prDjddvmLpDA2A2",
  • "status": "refunded",
  • "cost": 0.15
}

Check courier availability

Queries the status of a specified pigeon courier.

If you don't include a pgnId value in your request, this endpoint will return the status of all pigeon couriers in the region associated with your Pigeon Protocol account.

Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

query Parameters
pgnId
string
Example: pgnId=CPL593H

The alphanumeric ID of the pigeon courier whose status you'd like to query.

Responses

Response samples

Content type
application/json
Example
{
  • "pgnId": "CPL953H",
  • "pgnStatus": "busy",
  • "region": "US_SW",
  • "variety": "mondain"
}

Send tip to courier

Gives a thimble of birdseed to the specified courier. For each tip you send, a $0.05 USD charge will be billed to your account.

Note that this endpoint does not expect a request body; instead, use the pgnId query parameter to specify the courier of your choosing.

Authorizations:
pgnProtocolAuth
path Parameters
account
required
string
Example: featherfan92

The username of your Pigeon Protocol account.

query Parameters
pgnId
required
string
Example: pgnId=CPL593H

The alphanumeric ID of the pigeon courier who you'd like to tip.

Responses