API Reference

Everything you need to touch programmatically. The PPToucher API is RESTful, idempotent, and fully consensual. All requests are made over HTTPS and remembered forever.

Authentication

Authenticate with a bearer token. Keep it secret. Anyone holding your token can touch on your behalf, and the audit log does not care about your feelings.

curl https://api.pptoucher.com/v1/pps \
  -H "Authorization: Bearer pk_live_do_not_commit_this"

Tokens beginning with pk_test_ touch a simulated fleet of PPs. They report enjoying it, but they are only mocks.

Your First Touch

Install the SDK, then reach out.

npm install @pptoucher/sdk

import { PPToucher } from "@pptoucher/sdk";

const ppt = new PPToucher(process.env.PPTOUCHER_KEY);

const touch = await ppt.touch("pp_9f2c8a17", {
  mode: "gentle",     // start gentle. always start gentle.
  consent: true,      // required. non-negotiable. see Errors.
});

console.log(touch.latency_ms); // 142, on a good day

POST/v1/touch

Touches a PP. The fundamental operation. Everything else is bookkeeping.

Field	Type	Description
`target`	string	The PP to touch. Must exist. Must be yours to touch.
`mode`	enum	`gentle` \| `firm` \| `executive`. See Touch Modes.
`consent`	boolean	Must be `true`. There is no default. There will never be a default.
`lingering_ms`	integer	Optional. How long to linger, in milliseconds. Values over 5000 require an Enterprise plan and a conversation.
`async`	boolean	If `true`, returns immediately while the touch completes in the background. The PP will know when it happens.

Include an Idempotency-Key header to guarantee a PP is touched exactly once, no matter how many times you ask. Asking many times is normal. We understand.

GET/v1/pps

Lists PPs visible to your organization. Supports pagination, filtering, and the query parameter ?status=untouched, which our largest customers poll with a frequency we have chosen not to publish.

GET/v1/touches/:id

Retrieves a single touch event, including timestamp, mode, duration, initiating principal, and the full chain of custody. Every touch is recorded. Every touch has always been recorded. This became important in 2019.

DEL/v1/touches/:id

Returns 501 Not Implemented.

{
  "error": "not_implemented",
  "message": "What's touched cannot be untouched."
}

This is documented behavior, not a roadmap item. Please stop opening tickets. Please stop calling. The touch happened. It is part of you now, and part of the audit log, which is the same thing.

Touch Modes

Mode	Latency	Description
`gentle`	~142ms	The default. Recommended for first touches, sensitive PPs, and Mondays.
`firm`	~89ms	For PPs that have been touched before and know what they're getting into.
`executive`	varies	The touch is delegated, the outcome is announced in a meeting, and nobody can say who actually did the touching. Enterprise only.

Rate Limits

Free tier: 10,000 touches per month. Professional: unlimited, within reason. If you exceed what we privately consider reasonable, nothing happens, but we do discuss you.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9858
X-RateLimit-Reset: 1784563200
X-Touch-Advisory: pace yourself

Errors

Code	Meaning
`400`	Malformed touch. Slow down and read the docs.
`402`	Your free touches are spent. They always go faster than you think.
`403`	`consent` was not `true`. The request was rejected and logged. Forever. We mean forever.
`404`	PP not found. It may have been decommissioned, or it may simply not want to be found.
`409`	PP is currently being touched by another process. Wait your turn.
`423`	PP has requested space. Respect it. Retry-After will tell you when, if ever.
`429`	Too many touches. Even a PP needs a moment.
`451`	Unavailable for legal reasons. See the 2019 Settlement FAQ. Do not see anything else.