API reference

Create a cause

POST/v1/causes

Publishes a cause for your organisation, exactly as creating one in this portal would.

• •A Vibe schedule is required. A cause is not open for vibes the moment it exists: vibing opens at open_at and closes on its own once duration_seconds have passed. Both fields are required, and there is no "always open" option — whoever creates the cause decides its window, and the people who vibe it never choose a duration.
• •open_at must carry a timezone offset (Z or ±HH:MM). An offset-less time is refused: "5:00 PM" read in the wrong zone opens a Vibe hours late, and only you know which 5 PM you meant.
• •The window can repeat — daily, weekly, monthly, yearly, or on chosen weekdays with custom. A repeat does NOT let anyone vibe the cause twice (a person vibes a cause once, full stop); it re-opens the window for people who have not vibed it yet.
• •A repeating cause needs exactly one end: repeat_until or repeat_count, never both and never neither. An open-ended series nobody remembers to close runs for ever.
• •repeat_days belongs to custom alone, and occurrence one is the open date — so open_at has to fall on one of the days you chose, or the series would begin off its own rule. Weekdays are 0 = Sunday … 6 = Saturday.
• •monthly and yearly clamp the day to the target month: a series anchored on 31 January runs 28 February, not 3 March. A series is capped at 366 occurrences.
• •A window that has already finished is refused. That includes one that ends between your call and now, so schedule forward rather than backfilling.
• •The response carries a derived vibe_schedule. Its status — scheduled, live or closed — is computed on every read, so a Vibe closes on its own: nothing has to run, and there is no callback to wait for. Read status, not lifecycle_status, to decide whether a cause can be vibed.
• •The cause is attributed to your organisation’s owner — the person who authorised the key. There is no system account.
• •is_public reaches everyone on Vibe rather than only your members, and is a paid feature: on a plan without it the call is refused with a 403 rather than quietly creating a private cause.
• •Branch on moderation_status, not on the message: approved means it has cleared review, pending means it is queued for it. Which one you get depends on your organisation’s auto-approval setting.
• •Approved is not the same as open. An approved cause still waits for its window, and a cause left in review past its open_at misses it — so leave enough lead time for review, or reschedule it afterwards with the edit endpoint.
• •Do not send organisation_uuid — a key already names its organisation, and passing one is refused.
• •A category is required, and there are two ways to give one. Send category_uuid from GET /v1/categories to file the cause under an existing category, or send category_name as free text.
• •category_name is FIND-OR-CREATE, matched case-insensitively: "clean water" files the cause under the existing "Clean Water" rather than making a second one, and a name nobody has used yet creates the category on the spot. A category retired earlier under that name is revived rather than duplicated.
• •A category created this way is created platform-wide, not privately to you — it appears in GET /v1/categories for everyone immediately, and the name is screened for abuse. Prefer category_uuid from the list when a suitable category already exists; use a name when you genuinely need a new one.
• •Do not send both. They are not merged and it is not an error: category_name wins and category_uuid is ignored, so a stale name alongside a correct uuid quietly files the cause somewhere else. The sample opposite shows every OTHER field at once, but only one category field.
• •Creating a cause under a brand-new category is just the name — there is no separate call to make first: { "title": "Saturday beach clean", "open_at": "2026-09-12T09:00:00+05:30", "duration_seconds": 900, "category_name": "Beach cleanups" }. The response echoes the category it landed in, with the uuid you would reuse next time.
• •A cover image is two calls, in this order: upload the file (next endpoint), then send the url it returns back here as image_url. There is no way to post a cause and its image together — see "Creating a cause" in the guide for the whole sequence.
• •The sample opposite shows every field. Only title and a category are required — send as few of the rest as you like.
• •goal is stored but not echoed here: this response is the public shape of a cause. Read it back from GET /v1/causes/mine to see it.

Upload an image

POST/v1/uploads/image

Takes a file and hands back the path to store — step one of attaching a cover image to a cause, or a logo to your organisation.

• •A multipart form, not JSON. The file field is file.
• •Uploading stores the file and nothing else. It does not attach it to anything: send the returned url to the endpoint that should use it, as image_url on a cause or logo_url on your organisation. An upload nobody references is simply an orphaned file.
• •folder is causes for a cover image or org-logos for a logo. Anything else — including omitting it — files the image under misc. That still works and the path is still valid, but nothing sorts it later, so pass the right one.
• •Limits: 5 MB, and PNG, JPEG, WebP, GIF, SVG, HEIC or HEIF. Anything else is refused on the content type, not the file extension.
• •The path is host-relative on purpose: image_url and logo_url only accept a reference this endpoint returned. An absolute URL is refused, so a live cause or logo can never be pointed at a host we do not control.
• •Nothing expires. A url you got last month is still valid to attach today, so uploading early and creating the cause later is fine.

List categories

GET/v1/categories

The categories a cause can be filed under — what to populate a category picker from before creating one.

• •Take uuid from here and send it as category_uuid when you create a cause. That is the reliable way to file a cause under an existing category.
• •Active categories only, the same list the Vibe app's own picker reads. A retired category stays on the causes already using it but is not offered for new ones — so a uuid from an older response can stop appearing here while the causes under it keep working.
• •Platform-wide, not per-organisation: categories are shared by everyone on Vibe, and there is no way for a key to create one directly. Creating a cause with a category_name nobody has used yet is what adds one.
• •reference (CAT-0001) is for showing a person; uuid is what the API takes. Unpaged by default — pass limit to page, and search to filter by name.

List your causes

GET/v1/causes/mine

Your organisation’s causes at every status — including private ones and those still waiting on review.

• •This is YOUR list, not the public catalogue: a cause you have just created does not appear publicly until it is both approved and public, so this is the endpoint to read it back from.
• •Paged. Filter with moderation_status (pending, approved, rejected) and lifecycle_status (active, closed).
• •stats is the impact recorded so far: how many people took part, and how long for.
• •Filter by Vibe window too, with vibe_status. Unlike the public catalogue, nothing is hidden here by default — this is your full list, finished Vibes included.
• •On a repeating cause vibe_status=scheduled includes one that is merely between occurrences, and closed only ever means the series itself is finished. repeat.occurrence / repeat.total_occurrences say how far through it is.
• •Submitters are named, never emailed — an integration gets a name and a reference, not a way to contact your members.
• •There is no organisation filter: a key only ever sees its own organisation, so there is nothing to narrow.
• •The sample opposite passes every filter at once. They are all optional — send only the ones you want.

Retrieve one of your causes

GET/v1/causes/mine/{uuid}

One cause in full, with the individual vibes given to it. Works whatever its status.

• •Use this for your own causes whatever their state — a public read only ever returns approved, public ones.
• •vibes names each contribution by reference and seconds — no names or emails, and source says whether it came from the Vibe app or through your integration.

Edit a cause

PUT/v1/causes/mine/{uuid}

Changes the wording, category, cover image or Vibe schedule of a cause. Send only the fields you are changing.

• •A content edit, not a re-review: the moderation status is left exactly as it was.
• •At least one field is required. The sample opposite shows every field you may send — pick the ones you are changing.
• •This is how you reschedule. open_at and duration_seconds may be sent alone — send duration_seconds by itself to extend or shorten a Vibe that is already running, and the stored open_at is kept.
• •Send neither and the window is left untouched. That is what lets you fix the wording of a cause whose Vibe has already closed, which re-sending its old schedule would not.
• •A resulting window that has already finished is refused. Use the close endpoint to end a cause early rather than backdating its schedule — closing notifies the submitter, and an edit does not. On a repeating cause it is the whole SERIES that must not be over, so one whose early occurrences have passed can still be edited.
• •The repeat fields merge the same way: change repeat_frequency alone and the end you already chose is kept. `repeat_frequency: "none"` is how a repeat is turned off, and it clears the rule with it.
• •Moving the frequency off custom drops the stored weekdays — that is what the change means. Weekdays sent explicitly alongside a non-custom frequency are refused instead, because silently dropping what someone asked for is worse than saying it does not apply.
• •organisation_uuid is refused — a cause cannot be moved to another organisation through a key.

Approve a cause

POST/v1/causes/mine/{uuid}/approve

Publishes a cause one of your members submitted. This is your organisation’s own review queue.

• •Only a cause still pending can be approved — anything else is a 400.
• •Approving does not move the schedule. A cause reviewed after its open_at has passed misses that window — on a one-off it needs rescheduling, and on a repeating one it simply starts from the next occurrence. Check vibe_schedule.status in the response rather than assuming it is now live.
• •Your members’ submissions only. A cause that reaches everyone on Vibe is reviewed by Vibe staff, and a key is refused on those.
• •The submitter is notified, and once it is live your members are told about it.
• •You will only see a queue here if your organisation lets members post and has auto-approval switched off.

Reject a cause

POST/v1/causes/mine/{uuid}/reject

Declines a submission and tells the person who filed it why.

• •reason is required, 3–500 characters. It is shown to the submitter, so write it for them.
• •Only a cause still pending can be rejected.

Close a cause

POST/v1/causes/mine/{uuid}/close

Ends a Vibe EARLY, before its scheduled window runs out. It stops accepting vibes but keeps everything already given to it.

• •A manual hold that overrides the schedule: a cause closed this way reads as closed even while its window is still open, and vibe_schedule.closed_early is how you tell that apart from a window that simply ran out.
• •On a repeating cause this stops the whole series, not one occurrence. The hold overrides the schedule outright, so every remaining occurrence is dead until you reopen it. There is no way to skip a single occurrence — shorten the series with the edit endpoint instead.
• •A cause whose window has already passed needs no closing — it is closed. Calling this on one changes nothing a visitor can see.

Reopen a cause

POST/v1/causes/mine/{uuid}/reactivate

Lifts the manual hold and hands the cause back to its Vibe schedule.

• •This does not grant a new window. If the scheduled one has already passed, the cause stays closed — give it a new schedule with the edit endpoint to run it again. On a repeating cause with occurrences left, lifting the hold hands it straight back to its series.
• •Check vibe_schedule.status in the response rather than assuming: live means it is taking vibes again, scheduled that it will, closed that it needs rescheduling.

Delete a cause

DELETE/v1/causes/mine/{uuid}

Removes a cause from your organisation.

• •A soft delete: the time people already gave to it is not destroyed, so your historic totals stay correct.
• •Close a cause instead if you only want it to stop accepting vibes.

Check a key

GET/v1/me

Confirms a key is live and tells you which organisation it belongs to. The cheapest way to verify your setup.

List members

GET/v1/members

The people who belong to your organisation on Vibe — staff, not the end users of your own product.

• •Narrower than what your portal shows: an integration gets names, roles and contribution figures, never emails, phone numbers or dates of birth.
• •role is 1 for an admin, 2 for a member, 3 for the organisation owner.

Retrieve a user’s impact

GET/v1/users/{user_id}/stats

What one of your users has contributed, and to which causes.

• •Returns 404 until that user has recorded their first vibe — there is nothing to create beforehand.

List end users

GET/v1/users

Everyone you have recorded a vibe for, newest first.

Invite a member

POST/v1/invites

Emails an invitation to join your organisation on Vibe. Useful for inviting straight from your own HR system or intranet.

• •They join as a member (role 2), the same as an invite sent from this portal. A key cannot create administrators.
• •The invite expires after three days. Sending a second one to the same address while the first is still pending is refused — wait for it to expire, or resend it from this portal.
• •Nothing is created on Vibe until they accept — an invite is not a member.
• •All three fields are required; there are no optional ones here.

Update branding and permissions

PATCH/v1/organisation

Changes your logo, colours, bio, and who is allowed to post causes. Send only the fields you are changing.

• •At least one field is required, and every field is optional — the sample opposite shows all of them. Anything you leave out keeps its current value.
• •A logo is a file, so upload it first and send the returned path as logo_url.
• •Colours must be hex, including the #. They set the accent your members see in the Vibe app.
• •cause_post_permission is 1 for admins only, 2 for any member.
• •The organisation you read back is narrower than the one this portal shows: an API key never receives your contact details, your owner’s email or phone, or your subscription.

List invitations

GET/v1/invites

Every invitation your organisation has sent, and what became of it. Sending one is of little use without this.

• •status is pending, accepted, revoked or expired. Filter to one with the query parameter.
• •accepted_user is filled in once someone joins — that is how you tell an invitation from a member.

Resend an invitation

POST/v1/invites/{uuid}/resend

Sends the invitation email again and extends the expiry by another three days.

Revoke an invitation

DELETE/v1/invites/{uuid}

Cancels an invitation that has not been accepted. The link stops working immediately.

• •Revoking one that is already revoked or accepted returns an error rather than doing nothing quietly.

Remove a member

DELETE/v1/members/{uuid}

Takes someone out of your organisation — the call to make when your own HR system offboards them.

• •Members only. An administrator cannot be removed through a key, so an integration can never lock your own admins out of the portal.
• •Their Vibe account survives; it simply stops belonging to your organisation, and the time they already gave stays counted.
• •Take the uuid from GET /v1/members.