API reference

Route messages

Buyer and seller conversations about a route.

3 operationsBase URL https://packetexchange.io/api/v1Postman collection

List your route conversations

GET/api/v1/route-messages/threads

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

The other party is shown by a label, never by account.

Response 200

Field	Type	Description
`data`required	object[]	-
`routeId`requireddata[].routeId	string (uuid)	-
`buyerId`requireddata[].buyerId	string (uuid)	-
`role`requireddata[].role	string	-One of `buyer`, `seller`
`routeName`requireddata[].routeName	string	The listing name as a buyer reads it: generated by the platform, never the seller's text, and ending in the listing reference (e.g. "Niger Mobile · Ref 7K2Q", "A-Z Voice · Premium · Full CLI · Ref 3MX9"). Your own listings keep the name you gave them.
`otherParty`requireddata[].otherParty	string	-
`unread`requireddata[].unread	integer	-
`total`requireddata[].total	integer	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get one route conversation

GET/api/v1/route-messages/{routeId}/{buyerId}

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Parameters

Name	In	Type	Description
`routeId`required	path	string	-
`buyerId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`routeId`requireddata.routeId	string (uuid)	-
`buyerId`requireddata.buyerId	string (uuid)	-
`role`requireddata.role	string	-One of `buyer`, `seller`
`routeName`requireddata.routeName	string	The listing name as a buyer reads it: generated by the platform, never the seller's text, and ending in the listing reference (e.g. "Niger Mobile · Ref 7K2Q", "A-Z Voice · Premium · Full CLI · Ref 3MX9"). Your own listings keep the name you gave them.
`otherParty`requireddata.otherParty	string	-
`messages`requireddata.messages	object[]	-
`id`requireddata.messages[].id	string (uuid)	-
`routeId`requireddata.messages[].routeId	string (uuid)	-
`buyerId`requireddata.messages[].buyerId	string (uuid)	-
`mine`requireddata.messages[].mine	boolean	-
`body`requireddata.messages[].body	string	-
`readAt`requireddata.messages[].readAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.messages[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Send a message about a route

POST/api/v1/route-messages

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Contact details (emails, phone numbers, links, handles) are refused. Sellers must pass buyerId to start a thread.

Request body (application/json)

Field	Type	Description
`routeId`required	string (uuid)	-
`body`required	string	-max 4000 chars
`buyerId`	string (uuid)	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routeId`requireddata.routeId	string (uuid)	-
`buyerId`requireddata.buyerId	string (uuid)	-
`mine`requireddata.mine	boolean	-
`body`requireddata.body	string	-
`readAt`requireddata.readAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`senderId`requireddata.senderId	string (uuid)	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/route-messages" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>",
  "body": "Hello from Acme"
}'

Run it here with a test key.