Throwing, as an API.

Introduction

The Yeeterprise API is organized around REST. It has predictable, resource-oriented URLs, accepts application/json request bodies, returns JSON responses, and uses standard HTTP verbs and response codes. The one non-standard guarantee: nothing you send goes up and stays there.

Authentication

Authenticate with your secret API key in the Authorization header as a Bearer token. Keys carry the environment in the prefix: sk_live_ for production throws, sk_test_ for the sandbox (where objects are thrown but never actually leave the origin).

Authorization: Bearer sk_live_9f2c••••••••••••••••a71b

Quickstart

Initiate your first governed throw. This models the arc, clears the payload against the registry, and — if compliant — commits it to the ground with a certificate.

curl https://api.yeeterprise.com/v1/throws \
  -H "Authorization: Bearer sk_live_9f2c…a71b" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "a slightly overripe banana",
    "origin": "desk-4F",
    "target_zone": "bin-north",
    "force": "governed"
  }'

{
  "id": "thr_0Kp9c2Ba71b",
  "object": "throw",
  "status": "in_flight",
  "compliance": { "registry_cleared": true, "class": null },
  "trajectory": { "apex_cm": 142, "time_to_ground_s": 0.71 },
  "regret": 0,
  "certificate_url": "https://api.yeeterprise.com/v1/throws/thr_0Kp9c2Ba71b/certificate"
}

Throws

A throw is the core object: one governed act of downward force, from release to ground contact, with its trajectory and compliance verdict attached.

Request body

Trajectories

Model an arc before you commit to it. Returns apex, time-to-ground, and a confidence interval — no object leaves the origin.

// POST /v1/trajectories/model
{
  "mass_g": 118,
  "release_velocity_ms": 3.4,
  "angle_deg": 38
}
// → { "apex_cm": 142, "time_to_ground_s": 0.71, "confidence": 0.992 }

Compliance checks

Query the Do-Not-Yeet registry directly. Every POST /v1/throws runs this automatically, but you can pre-flight a payload to fail fast and keep your regret metric clean.

{
  "error": {
    "type": "do_not_yeet",
    "code": "DNY-0002",
    "message": "Payload matches a protected class: a sleeping cat.",
    "resolution": "Do not yeet. There is no override. This is the whole point."
  }
}

Webhooks

Subscribe to lifecycle events so your systems learn the instant an object reaches the ground. Payloads are signed with your endpoint's secret; verify the Yeet-Signature header before trusting a body.

Rate limits

Limits are per API key, by plan. Exceeding a limit returns 429 with a Retry-After header. Objects do not queue in the air.

Errors & status codes

Yeeterprise uses conventional HTTP status codes. Codes in the 2xx range mean the object is on its way down; 4xx means it never should have gone up.

SDKs

Official libraries wrap authentication, retries with idempotency, and webhook signature verification.

# Node.js
npm install @yeeterprise/node
# Python
pip install yeeterprise
# Go
go get github.com/yeeterprise/yeeterprise-go

import Yeeterprise from "@yeeterprise/node";
const y = new Yeeterprise("sk_live_9f2c…a71b");

const throw_ = await y.throws.create({
  payload: "a stress ball, retired",
  origin: "desk-4F",
  force: "governed",
});
console.log(throw_.status, throw_.regret); // "in_flight" 0