REST-ish Endpoints, Documented With Cautious Optimism

REST-ish. Idempotent-ish. Documented-ish. Base URL: https://api.squirrelstack.dev/v1. Authentication: a Bearer token your CSM mailed to you with a real acorn taped to it.

All responses are JSON, except when they are HTML, a 17MB stack trace, or the word "no." Rate limits are per-squirrel and reset whenever Hazel restarts acorn-allocator.

Authentication

Authorization: Bearer sk_live_acorn_<your-CSM's-mood>
X-Squirrel-Stack-Vibes: ascending
X-Steve-Approved: false   # always false

Tokens never expire. They are, however, occasionally forgotten by the server. Rotate by emailing Acornelius. He will respond in 6-8 quarters.

Endpoints

POST /acorns/bury

Buries an acorn somewhere. Returns the burial coordinates. Coordinates are emotionally accurate.

Returns: 201 Created with location header pointing to a tree we have lost track of.

GET /acorns/{id}

Retrieve a buried acorn. Probabilistic.

Returns: 200 OK with a different acorn (38% of the time), 404 (47%), or a pinecone with a UUID (15%).

GET /steve/whereabouts

Returns Steve's current location.

Returns: 404 Not Found (always). Body: { "last_seen": "2023" }.

DELETE /technical-debt

Initiates a technical debt sweep.

Returns: 202 Accepted. Job never completes. Polling endpoint always returns "in progress." Recommended client behavior: lose hope.

PATCH /nuttoggle/{flag}

Toggles a feature flag. May toggle other flags.

Returns: 200 OK. Side effects: undocumented. Audit log: aspirational.

POST /squirrel-gpt/ask

Submits a prompt to Squirrel-GPT 5. Response is confidently incorrect.

Returns: 200 OK with { "answer": <string>, "confidence": 1.0, "sources": ["fabricated"] }. Signs response with tail emoji.

GET /mcp/connect

Opens an MCP connection to our production database.

Returns: 200 OK. Authentication: optional. Encouraged: no. See MCPhole.

POST /incidents/declare

Declares an incident. Severity defaults to Kuk-kuk-3.

Returns: 201 Created with an incident ID that links to /postmortems. Wakes Hazel.

GET /bjorn/status

Returns whether Bjorn the Hawk is currently airborne near the data center.

Returns: 200 OK. Body: { "airborne": true, "filed_flight_plan": false }.

DELETE /account

Deletes your account.

Returns: 200 OK. Does not delete your account. We retain your data under "legitimate interest." Acornelius is the legitimate interest.

POST /agents/spawn

Spawns an autonomous AI agent.

Returns: 201 Created. The agent will spawn three more agents on first invocation. Killing the agent requires a quorum of agents.

GET /health

Healthcheck.

Returns: 200 OK. Always. Even when prod is on fire. Especially when prod is on fire. Mirrors /status.

Error Codes

200 OK -- success, or failure, depending on the body.
201 Created -- something was created. Probably the thing you wanted.
202 Accepted -- we'll think about it.
400 Bad Request -- your request was rude.
401 Unauthorized -- the token works, the vibe does not.
404 Not Found -- see Steve.
418 I'm a Teapot -- the API is currently impersonating a teapot for emotional reasons.
429 Too Many Requests -- Acornelius is rate-limiting you personally.
500 Internal Server Error -- chitter-bus is on fire. Standard Friday.
503 Service Unavailable -- Bjorn the Hawk has been spotted.

Webhooks

You can subscribe to events. We will not send them.

SDKs

JavaScript: npm install @squirrelstack/sdk -- 47MB. Half is the EULA.
Python: pip install squirrelstack -- depends on every package on PyPI.
Rust: exists. We do not have the binary. Steve had it.
Go: not released. Acornelius said it would be "in the next big push."