Throwing, as an API.

Introduction

The Yeeterprise API is organized around REST, with predictable resource-oriented URLs, application/json bodies, JSON responses, and standard HTTP verbs and 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. The prefix carries the environment: sk_live_ for production, sk_test_ for the sandbox (where objects are thrown but never 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 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, release to ground contact, with trajectory and compliance verdict attached.

Request body

Trajectories

Model an arc before committing. 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 regret 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 moment 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 one returns 429 with a Retry-After header. Objects do not queue in the air.

Errors & status codes

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

SDKs

Official libraries wrap authentication, idempotent retries, 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