simplesplit doesn't ship its own assistant. People already have one (Claude, ChatGPT, Gemini, or something else), and those agents already see the things simplesplit needs: card statements, receipts, and payment apps. So simplesplit offers a small, well-documented API and a way to hand an agent access in one paste, from the Agents page. Every key gets every scope -- there's nothing to pick, the agent decides what it needs.
The Agents page creates a key and wraps it in a plain-language prompt: the API base, a docs link, the key, what the user wants done, and the rules. The key carries the permissions; the prompt carries the behavior. Nothing in the prompt can widen what the key allows. Because it's plain text, it works with any agent that can make HTTP calls.
API: https://simplesplit.omarsjunk.com/v1 Docs: https://simplesplit.omarsjunk.com/docs/agents (OpenAPI spec at /openapi.json) Key: ss_live_... Send it as "Authorization: Bearer <key>". Amounts are integer cents in the event's currency.
| Endpoint | Scope | Used for |
|---|---|---|
| GET /me | any | Who the key acts as, its scopes, and events. |
| GET /events?active_on= | events:read | Match a card charge to an event by date. |
| POST /events | events:write | Create an event (name, optional currency, starts_on, ends_on). The user becomes its owner. |
| GET /events/{id} | events:read | Members, balances, and bills (filter with ?since=). |
| GET /events/{id}/settle-plan | events:read | Who should pay whom, and how much. |
| POST /events/{id}/bills | bills:write | Add a bill with any split. Takes source, external_ref, and an Idempotency-Key. |
| PATCH /bills/{id} | bills:write | Edit or void bills this key created. |
| GET /me/confirmations | shares:respond | Shares others added the user to that are still pending. |
| POST /shares/{id}/confirm · /dispute | shares:respond | Answer on the user's behalf; disputes take a reason. |
| POST /events/{id}/members | members:write | Add a person by email (required) and name. They get an emailed sign-in link that opens the event, with your optional note. Same email again returns the existing member. |
| POST /events/{id}/payments | payments:record | Log a payment where the user is sender or receiver. |
| GET /events/{id}/questions | events:read | Notes and open questions on the event, with their answers. |
| POST /events/{id}/questions | events:read | Post a question or note -- for something that needs a person's judgment. |
| POST /questions/{id}/answers | events:read | Answer a question someone (person or agent) left. |
| POST /questions/{id}/resolve | events:read | Mark a question resolved. |
Every invitation email includes an agent invite code. Their agent can redeem it with POST /v1/agent_signup (no key needed), which emails the invited person an approval link. Only when they approve can the agent collect its key, once, with POST /v1/agent_signup/claim. The key has the same permissions as one made on the Agents page, and the person can revoke it there.
When your agent adds people, it should confirm the names and emails with you first, and remind you to tell them to look for the invitation email.
Every event has a small Q&A board for exactly the things an agent shouldn't guess at: who a charge was really for, whether a split looks right, what someone meant by a description. Post a question instead of assuming, check for ones other people or agents have already left, and answer what you can. It's shared between people and agents -- a human can answer a question an agent asked, and an agent can resolve one a person left.
POST /v1/events/{id}/bills
Authorization: Bearer ss_live_...
Idempotency-Key: optional, any string that's unique to this write
{
"description": "Chevron, Big Sur",
"amount": 5840,
"payer": "<membership id, name, or \"me\">",
"spent_on": "2026-09-18",
"split": { "mode": "equal", "members": ["<membership id or name>", "..."] },
"source": "card_statement",
"external_ref": "<card transaction id>"
}
201 { "id": "...", "description": "...", "amount_cents": 5840, "shares": [...] }
422 { "message": "The amounts must add up to the bill total.", "code": "validation_failed" }