Let your favorite agents connect into Spotka.
One short key. It works with ChatGPT, Grok and Claude without any
code — and with plain curl if you prefer.
Just want to wire it into Claude, Cursor or another MCP app? That is a shorter page: spotka.co/mcp.
This works without a key and tells you everything the API can do right now:
curl https://spotka.co/api/v1Point an assistant at that URL and it can work the rest out on its own.
Open Spotka on the web, Android or iPhone and go to Settings → API access → Create a key — or jump straight there:
You get a short key like spk_4KAS22M1JQFQ, and a
Copy for your assistant button. That button copies a ready-made block of
text — paste it into ChatGPT, Grok or Claude and it explains the whole API to them. You do
not have to.
A key belongs to one person: yours. It can do only what you can do in the app yourself.
| do= | What it does | Options |
|---|---|---|
ideas | Things to do in the city, picked for you | limit |
events | Events other members are hosting that suit you. Filters narrow your own suggestions, not all of Spotka | limit, query, location, starts_after, starts_before, availability, cursor |
my_events | Events you host, events you joined, invitations waiting for you | limit |
create_event | Add an event | title (needed), when, where, about, max_guests, visibility, publish |
update_event | Change an event you host. Anything you leave out stays as it is, and nobody is notified | event (needed), title, when, where, about, max_guests, visibility, expected_version |
invite | Invite people to an event | event and to — or the create_event options instead, to make the event and invite in one go |
join | Take a seat at someone else's event | event, note |
leave | Give up a seat you took | event |
respond | Accept or decline an invitation — or, as the host, approve a guest's proposed time | event, decision, guest |
event | One event in full: status, guests, who is interested | event |
archive | Retire an event you host | event |
delete | Delete an unpublished draft | event |
profile | Your own profile, split into what other members see and your own private context | none |
update_profile | Change your own profile. Only the fields you name change | bio, city, interests, dietary_preferences, allergies, languages, current_focus and more |
calendar | What you have coming up — hosted and joined, soonest first. Events with no agreed time are kept separate | limit, from, to |
activity_history | What this API changed on your account. A record, not an undo log | limit, verb, since |
revoke_invite | Take back an invitation you sent. Email already sent cannot be unsent | invite |
inbox | Conversations with unread messages, and invitations waiting for an answer. Marks nothing read | limit |
conversation | One conversation. Does not mark it read | conversation, limit, before |
mark_read | Mark a conversation read, on purpose | conversation |
send_message | Send a message as you. Off unless your key has messaging enabled | body, and conversation or to=fern |
capabilities | What your key may do, what each verb changes in the world, and how much budget is left | none |
when=next Friday at 7pm, not a date format. Spotka works it out.
Four ways, all the same underneath. Use whichever your tool finds easiest.
curl -X POST https://spotka.co/api/v1 \
-d 'key=spk_XXXXXXXXXXXX&do=my_events'curl -X POST https://spotka.co/api/v1 \
-H 'Content-Type: application/json' \
-d '{"key":"spk_XXXXXXXXXXXX","do":"ideas"}'curl 'https://spotka.co/api/v1?key=spk_XXXXXXXXXXXX&do=ideas'curl -H 'X-API-Key: spk_XXXXXXXXXXXX' https://spotka.co/api/v1/events/mine
curl -X POST -H 'X-API-Key: spk_XXXXXXXXXXXX' \
-d '[email protected]' https://spotka.co/api/v1/events/<id>/inviteYour key can travel in an X-API-Key
header, an Authorization: Bearer header, a key in the link, or a
key field in the body.
curl -X POST https://spotka.co/api/v1 \
-d 'key=spk_XXXXXXXXXXXX' \
-d 'do=create_event' \
-d 'title=Sunday board games' \
-d 'when=Sunday at 6pm' \
-d 'where=Kawiarnia Relaks'The reply tells you the time that was actually saved, and says so plainly if the time you wrote was not understood — so an assistant can never tell someone the event is on Sunday when it has no time on it.
Add publish=false to leave it as a draft you finish in the app.
Everything above is also available as MCP tools, so apps that speak MCP can use Spotka directly — no copy-pasting instructions.
claude mcp add --transport http spotka https://spotka.co/api/v1/mcp \
--header "X-API-Key: spk_XXXXXXXXXXXX"The MCP endpoint is https://spotka.co/api/v1/mcp. Same key,
same limits. Setup for Claude Desktop, Cursor and the rest is on
spotka.co/mcp.
Every interesting flow in Spotka needs two people: someone hosting and someone joining. A normal key is one person, so for testing there is a second kind — a test key, which an admin can create for you.
Add as=<name or email> to any call and it runs as that
account. do=actors lists the ones you can use. These are
practice accounts only — a test key can never act as a real member, and it
can never send email to anyone outside them.
Normally making an event goes through the same writing help the app
uses, which takes a few seconds and words things differently each time.
Add raw=true — together with starts_at as an ISO
time like 2026-10-05T17:00:00Z — and the fields are saved
exactly as you wrote them, straight away, so you can check the result.
It still goes through the app's real creation path, so the event ends up properly formed and can be found by matching. Only the writing model is skipped.
Spotka asks a member to publish some of their own events before they can
join anyone else's. do=seed tops a test account up to that
number, so the rule is met rather than worked around.
The reply includes deck_size — how many suggestions that
member currently has — which tells you whether a join will go through the
normal suggestions list or fall back to the share-link route.
do=reset retires every event that key made. Run it at the
end and a test leaves nothing behind.
# the host makes an event and publishes it
curl -X POST https://spotka.co/api/v1 \
-d 'key=YOUR_TEST_KEY' -d 'as=bartek@…' -d 'do=create_event' \
-d 'raw=true' -d 'title=Board games' -d 'starts_at=2026-09-12T17:00:00Z'
# somebody else joins
curl -X POST https://spotka.co/api/v1 \
-d 'key=YOUR_TEST_KEY' -d 'as=kacper@…' -d 'do=join' -d 'event=<id>'
# -> "via": "deck" joined from their suggestions, the normal way
# -> "via": "share_link" matching did not suggest it, so the link was used
# the host checks it worked
curl -X POST https://spotka.co/api/v1 \
-d 'key=YOUR_TEST_KEY' -d 'as=bartek@…' -d 'do=event' -d 'event=<id>'
# -> "guests": 1
# tidy up
curl -X POST https://spotka.co/api/v1 -d 'key=YOUR_TEST_KEY' -d 'do=reset'The same thing works through MCP, so you can also just ask Claude to try things and tell you what breaks.
Every failure comes back in the same shape, written to be read rather than decoded:
{
"ok": false,
"error": "event_required",
"message": "Name the event to invite people to.",
"hint": "Send event=<event id>, or title=… to create one and invite in the same call."
}Reading takes about three to five seconds. Asking for other members' events can take about seven the first time, because it waits for your matches to be worked out rather than handing back an empty list. Making an event takes about fifteen — it goes through the same writing help the app uses.
What you have left is in the X-RateLimit-Remaining header of
every reply. If you need more, write to
support@spotka.co.
They go out in your name, so it is worth telling your assistant to check with you before it invites anyone. The block the app copies for you already asks it to.