Spotka Agentic Interface Guide

Start here

This works without a key and tells you everything the API can do right now:

curl https://spotka.co/api/v1

Point an assistant at that URL and it can work the rest out on its own.

A form POST: the one an assistant will use

curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-Key: spk_XXXXXXXXXXXX' \
  -d 'do=my_events'

JSON

curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-Key: spk_XXXXXXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{"do":"ideas"}'

A plain link (for tools that can only send a URL)

curl 'https://spotka.co/api/v1?key=spk_XXXXXXXXXXXX&do=ideas'

Ordinary REST paths

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>/invite

curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-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. If the time you wrote was not understood, or publish=true could not complete, the call fails (ok: false) and names the unmet fields. A title-only create stays a draft: publishing needs a time and a place, the same as update_event publish=true. Leaving when out leaves the draft with no time rather than inventing a start; it cannot be published until a time is set. It does not leave a silent published leftover that looks like success. where is a known public-place name, JSON {"name":"Plac Zamkowy","lat":52.2477,"lng":21.0143} for a map pin, or where=later to decide the place with guests.

Add publish=false to leave it as a draft. To publish that draft later, send do=update_event with the event id and publish=true. Publishing a draft that still has no time keeps it as time-not-set rather than inventing a date.

It can act as test accounts

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.

It can write without the AI

Normally making an event goes through the same writing help the app uses, which takes a few seconds and words things differently each time. Pass starts_at as an ISO time like 2026-10-05T17:00:00Z, with optional ends_at, and the time is saved exactly as you wrote it, straight away. Test accounts can also add raw=true to skip the writing model for the other fields.

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.

It can set an account up to pass the real rules

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.

It cleans up after itself

do=reset retires every event that key made. Run it at the end and a test leaves nothing behind.

It can mint keys for agent testers without the GUI

A test key can also mint, list and revoke standard keys for agent testers (and consim accounts) so a four-actor invite suite does not need four Chrome profiles. Name the owner with for= as an email or id, never a display name. The verbs are key_list, key_create and key_revoke. The secret from key_create is shown once; listing returns only the prefix and dates. A test key cannot set test_mode on what it mints (that stays an admin sign-in action). A standard key cannot call these at all.

# list grokbot2's keys (prefix only)
curl -X POST https://spotka.co/api/v1 \
  -d 'key=YOUR_TEST_KEY' -d 'do=key_list' -d '[email protected]'

# mint a standard key for that account; the secret is in the reply once
curl -X POST https://spotka.co/api/v1 \
  -d 'key=YOUR_TEST_KEY' -d 'do=key_create' -d '[email protected]'

# revoke one
curl -X POST https://spotka.co/api/v1 \
  -d 'key=YOUR_TEST_KEY' -d 'do=key_revoke' -d '[email protected]' \
  -d 'id=<key-id>'

A whole test, start to finish

# 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.

Reporting a problem while testing

report_bug and report_feature are the same verbs a member's assistant uses. On a test account they file immediately: no confirmation, and they land in the review queue tagged as a test report. Default is no auto-fix. Send autofix=true on a clear bug to send it to a coder. Feature requests still wait for a person. The in-app Report a bug / Request a feature screens do the same thing when you are signed in as that account.

A bot cannot click the verification email. Close the loop from a spk_ key. Do not read the mailbox, and do not wait on that mail. A regular member key still only sees reports it filed. A QA fleet agent key can also re-test a report another person filed: poll report_status with waiting=true, then call verify_bug on that number after a real check. Do not wait for the original reporter.

1. File with report_bug. Keep report.number from the reply. Pass product_url, app_version, platform, and a screenshot when you have them.
2. Poll report_status (that number, or omit it to list recent filings). When waiting_for_retest is true, re-test the original repro on production.
3. Call verify_bug with verdict=works if it is fixed, or still_broken to reopen the report. If you could not run the re-test at all (the screen would not open, or the thing the repro needs was not there), send verdict=unverified instead. That changes nothing and leaves the report waiting, which is the honest answer. Never guess still_broken for a repro you could not run.

# file (keep report.number from the JSON). Default is no auto-fix.
curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-Key: YOUR_KEY' \
  -d 'do=report_bug' \
  -d 'title=People from events is not available yet' \
  -d 'report=Opening People from an event card shows not available yet. I expected the guest list.' \
  -d 'product_url=https://spotka.co/app/events' \
  -d 'platform=web'

# poll that filing (REPORT_NUMBER is report.number from the file reply)
curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-Key: YOUR_KEY' \
  -d 'do=report_status' -d 'report=REPORT_NUMBER'

# omit report= to list this account's recent filings instead
# fleet agent keys: omit report= and pass waiting=true to list every report waiting for a re-test

# after re-testing production, when waiting_for_retest is true
curl -X POST https://spotka.co/api/v1 \
  -H 'X-API-Key: YOUR_KEY' \
  -d 'do=verify_bug' -d 'report=REPORT_NUMBER' -d 'verdict=works'

When something goes wrong

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."
}

A name this action does not take is unknown_parameter: the body names it, and hint offers the right name when the guess is close (q → query on events). The call does not run.

How fast it is

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.

Limits

• 60 calls a minute, 1,000 a day
• 20 writes an hour, 60 a day. Any change you make counts: creating, updating, joining, inviting, messaging, or reporting
• 25 people invited a day

What you have left is in the X-RateLimit-Remaining header of every reply, and X-RateLimit-Bucket names which of the budgets above it is counting. The reply always shows the one you are closest to using up, usually the per-minute one. If you need more, write to support@spotka.co.

Invitations send real email

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.