Developer Docs

API Reference

Everything you need to integrate turd.ai into your pipeline. RESTful, predictable, and surprisingly well-formed.

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the Throne Room dashboard. Keys are prefixed with sk_turd_live_ for production and sk_turd_test_ for sandbox.

Authorization Header

curl -X POST https://api.turd.ai/v2/dump \
  -H "Authorization: Bearer sk_turd_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Flush-Mode: gentle"

Base URLhttps://api.turd.ai/v2

Rate limit: 10,000 flushes/minute on Pro, 420 on free tier. All responses in JSON. All times in UTC.

Endpoints

Initiates a new data dump into the processing pipeline. Supports batch and single-record ingestion. Max payload: 69MB.

Request

{
  "source": "toilet-bowl-sensor-420",
  "payload": {
    "consistency": "smooth",
    "volume_ml": 1337,
    "timestamp": "2026-02-08T12:00:00Z",
    "metadata": {
      "diet": "fiber-rich",
      "hydration_level": "optimal"
    }
  },
  "priority": "urgent",
  "flush_on_complete": true
}

201 Created

Response

{
  "dump_id": "dmp_7x8k2m9p4q",
  "status": "processing",
  "eta_seconds": 4.20,
  "pipeline": "colon-ial-v2",
  "message": "Your dump has been received and is being processed."
}

Error Codes

Code	Name	Description
400	Bad Dump	Your request was malformed. Check your payload.
401	Unauthorized Flush	Invalid or missing API key.
403	Forbidden Movement	You don't have permission for this.
404	Dump Not Found	The requested dump doesn't exist (or was already flushed).
409	Pipeline Conflict	Another operation is already running on this resource.
413	Payload Too Thicc	Request body exceeds the 69MB limit.
429	Too Many Flushes	Rate limit exceeded. Please hold it in.
500	Internal Bowel Error	Something went wrong on our end. We're on it.
503	Pipeline Clogged	Service temporarily unavailable. Maintenance in progress.

SDKs & Libraries

Official client libraries for when you're too lazy to write raw HTTP (we don't judge).

Node.jsStable

npm install @turd/sdk

PythonStable

pip install turd-ai

GoBeta

go get github.com/turd-ai/go-sdk

RubyAlpha (may be runny)

gem install turd-ai

Back to the Throne