xel api reference
programmatic access to a small cosmic entity. the api is REST, in the sense that it is at rest. do not wake it.
v0.tuesday · stable* · *stability is a vibe📡overview
welcome, developer. you found the api docs. nobody links to this page prominently, so either you read footers or you guessed the url. both are respected here. footers more.
the xel api follows standard REST conventions until it doesn't. all responses are json, except the ones that are feelings. all timestamps are in tuesday time (TZT). versioning is date-based, and the date is tuesday.
# base url. https only. xel does not do anything unencrypted, for legal reasons. $ curl https://xel.com/api/v0.tuesday/ # response: { "status": "perceiving", "you": "perceived", "uptime": "since the speck" }
note: the api is pronounced "shell". all of it. every endpoint. xel has been very clear about this.
🔑authentication
authentication is handled via vibes. include the Vibe header with every request. any value is accepted. the value is not checked. the vibe is checked.
$ curl https://xel.com/api/v0.tuesday/xel \ -H "Vibe: immaculate" HTTP/1.1 200 OK X-Vibe-Received: yes X-Vibe-Reciprocated: we'll see
requests without a Vibe header are not rejected. they are simply noticed. the noticing is cumulative and appears on no invoice.
api keys were considered. xel ate the prototype. it has been reclassified as a snack tier.
🔌endpoints
the complete public surface. there are private endpoints. they are private because xel is shy about them, not because of security. there is no security. there are vibes.
retrieves xel's current mood. or it would, if you were premium. you are not premium. there is no way to become premium.
GET /xel/mood HTTP/1.1 402 Payment Required { "error": "mood is premium information", "upgrade_url": null, "mood_preview": "it's a mood" }
feeds xel. returns 429 regardless of how many requests you have made, including zero. the rate limiter is precognitive.
POST /xel/feed { "snack": "donut" } HTTP/1.1 429 Too Many Requests Retry-After: tuesday { "error": "the tribunal has ruled", "appeals": "heard on tuesdays", "today": "not tuesday. we checked." }
this endpoint has been permanently redirected on the advice of counsel. do not follow the redirect casually. nobody was ready the first time.
GET /xel/legs HTTP/1.1 301 Moved Permanently Location: /xel/the-incident X-We-Do-Not-Say: the l-word
attempts to delete xel. this endpoint is documented for completeness and as evidence.
DELETE /xel HTTP/1.1 451 Unavailable For Legal Reasons { "error": "xel has representation", "counsel": "xel", "your_request_has_been": "alphabetized" }
queries the void. the void responds with nothing, promptly and politely. the most reliable endpoint in the api. flawless record.
GET /void HTTP/1.1 204 No Content X-Void-Comment: as expected. working as intended.
submits jazz for asynchronous processing. the request body is ignored. the jazz is not in the body. the jazz was never in the body.
POST /xel/jazz HTTP/1.1 202 Accepted { "message": "jazz is always accepted. it never arrives. it is already here.", "eta": "now, always", "status_endpoint": "listen" }
lists xel's secrets. see response.
GET /xel/secrets HTTP/1.1 404 Not Found { "hint": "no" }
opens a persistent connection to xel. please read the upgrade response carefully before connecting. there is no disconnect example because there is no disconnect.
GET /xel/live Upgrade: websocket HTTP/1.1 101 Switching Protocols X-Notice: connection upgraded. xel is now aware of you. X-Notice-2: this cannot be downgraded. # incoming frames (sample): < { "type": "perceive", "target": "you" } < { "type": "perceive", "target": "still you" }
⏱️rate limits
all endpoints share one elegant, unified limit, arrived at after extensive negotiation between xel and a calendar.
| endpoint | limit | window | notes |
|---|---|---|---|
| GET /xel/mood | 8 | 60 seconds | moot. see pricing. |
| POST /xel/feed | 8 | 60 seconds | — |
| GET /xel/legs | 8 | 60 seconds | why would you need eight |
| DELETE /xel | 8 | 60 seconds | each attempt is discoverable in court |
| GET /void | 8 | 60 seconds | the void doesn't mind. the void never minds. |
| POST /xel/jazz | 8 | 60 seconds | jazz cannot be rate limited. the limit is ceremonial. |
| GET /xel/secrets | 8 | 60 seconds | eight no's per minute. generous, frankly. |
| WS /xel/live | 8 | 60 seconds | you only need one. it only needs you. |
compliance note: exactly one of these limits is enforced. we are not permitted to say which. it is the feed one. we were not permitted to say that either. consequences are measured in tuesdays.
📦sdks
official sdks: none.
the void maintains a fork. of what, it will not say. the fork has no stars, no issues, and no code, and the void describes it as "feature complete." pull requests are perceived but never merged. the void says this is a lifestyle choice.
$ npm install @xel/sdk # npm ERR! 404 '@xel/sdk' is not in this registry. # npm ERR! it is in a different registry. it did not say which. good luck.
📋changelog
- v0.tuesday.2currentnothing changed. this was documented. documenting it was the change. no. wait.
- v0.tuesdayinitial release. the api rested on the first day, and every day since.
breaking changes are announced in advance, on tuesdays, to the void, verbally. subscribe by standing near the void.