Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
π Add a migration guide from the private API to v1 (#3290)
Luke Vella6c084a9cc4ba
diff --git a/apps/docs/api-reference/migrating-from-the-private-api.mdx b/apps/docs/api-reference/migrating-from-the-private-api.mdxnew file mode 100644index 000000000..dc15129a4--- /dev/null+++ b/apps/docs/api-reference/migrating-from-the-private-api.mdx@@ -0,0 +1,440 @@+---+title: "Migrating from the private API"+description: "Move an integration from /api/private to /v1, endpoint by endpoint."+---++`/v1` replaces the unversioned private API at `https://app.rallly.co/api/private`. The private API is frozen: it still answers, but it receives no new fields or endpoints, and everything new lands on `/v1` only.++Your API keys, poll IDs, invite links and rate limits carry over unchanged. What changes is the base URL, the request and response shapes, and how errors look.++## Summary of changes++| Area | Private API | v1 |+| --- | --- | --- |+| Base URL | `https://app.rallly.co/api/private` | `https://api.rallly.co/v1` |+| Authentication | `Authorization: Bearer <key>` | Unchanged |+| Rate limits | 60 per minute, 5,000 per day, per space | Unchanged |+| Create poll status | `200 OK` | `201 Created` |+| Poll shape | `dates` or `slots` in the request, `options` in the response | `kind` plus `options` on both sides; each request option is the response option without its `id` |+| Time zone field | `timezone` (response), `slots.timezone` (request) | `timeZone` at the top level of both |+| Date options | `startTime` at UTC midnight with `duration: 0` | `date` as `YYYY-MM-DD` |+| Organizer | `user: { name, image }` | `organizer: { id, name, email, image }` |+| Poll settings in responses | Not returned | `requireEmail`, `hideParticipants`, `hideScores`, `disableComments`, `allowTentativeVotes` |+| `participantCount` | List items only | Every poll response |+| `updatedAt` | Not returned | Every poll response |+| Unknown request fields | Ignored | Rejected with `VALIDATION_ERROR` |+| Validation errors | Validator output with the request body echoed back | `{ "error": { "code", "message" } }` |+| Unknown routes and crashes | Plain text | The same JSON envelope |+| Update poll (`PATCH`) | Closes a poll | Removed, no replacement |+| Interactive docs page | `/api/private/docs` | This site; the spec stays at `/v1/openapi` |++## Global changes++### Base URL++Replace the host and prefix. The poll paths under it are the same, with two exceptions: `PATCH /polls/{pollId}` is removed, and `/docs` has no v1 equivalent. Both are covered below.++```text+https://app.rallly.co/api/private/polls β https://api.rallly.co/v1/polls+```++### Error envelope++Every v1 failure is JSON with the same shape, including cases the private API answered in plain text or with the validator's raw output. Branch on `error.code`; `error.message` is for humans.++<CodeGroup>++```json Private API (schema validation)+{+ "success": false,+ "error": [+ {+ "expected": "string",+ "code": "invalid_type",+ "path": ["title"],+ "message": "Invalid input: expected string, received undefined"+ }+ ],+ "data": { "dates": ["2027-03-01"] }+}+```++```json v1+{+ "error": {+ "code": "VALIDATION_ERROR",+ "message": "title: Invalid input: expected string, received undefined"+ }+}+```++</CodeGroup>++| Private API | v1 | Note |+| --- | --- | --- |+| `400` validator output, no code | `400 VALIDATION_ERROR` | One field per sentence in `message`, separated by semicolons |+| `400 INVALID_INPUT` | `400 VALIDATION_ERROR` | `kind` is required, so the "neither dates nor slots" case is a schema error |+| `400 DUPLICATE_DATES` | Not an error | Duplicate dates are removed |+| `400 NO_OPTIONS_GENERATED` | `400 VALIDATION_ERROR` | The message names `generators` |+| `422 TRANSITION_NOT_AVAILABLE` | Removed | The update endpoint is gone |+| `404 Not Found` plain text | `404 NOT_FOUND` | Unknown route or method |+| `400 Malformed JSON in request body` plain text | `400 VALIDATION_ERROR` | |+| `500 Internal Server Error` plain text | `500 INTERNAL_ERROR` | |++`UNAUTHORIZED`, `INVALID_AUTHORIZATION_HEADER`, `SPACE_NOT_PRO`, `ORGANIZER_NOT_MEMBER`, `TOO_MANY_OPTIONS`, `INAPPROPRIATE_CONTENT`, `POLL_NOT_FOUND`, `RATE_LIMIT_EXCEEDED` and `SERVICE_UNAVAILABLE` keep their status codes and meanings. See [Errors](/api-reference/errors) for the full list.++### Strict request bodies++The private API silently dropped fields it did not know, including `spaceId`, which it accepted but never used. v1 rejects any field outside the documented schema with `VALIDATION_ERROR`. Remove `spaceId` and any other extra fields before switching.++### The poll resource++Every endpoint that returns a poll (`POST /polls`, `GET /polls`, `GET /polls/{pollId}`) returns the same v1 shape. Compared with the private API:++- `timezone` is renamed `timeZone`.+- `user` is replaced by `organizer`, which adds `id` and `email`.+- `kind` is added: `date` or `time`. It tells you which option shape to expect.+- `updatedAt` is added. Compare it between reads to notice changes.+- The five poll settings are returned as booleans.+- `participantCount` is on every poll, not only list items.+- Options in a `date` poll carry `date` instead of `startTime` and `duration: 0`. Options in a `time` poll are unchanged.++<CodeGroup>++```json Private API+{+ "data": {+ "id": "Xk3pQ9vLm2Ab",+ "title": "Team offsite",+ "description": null,+ "location": null,+ "timezone": null,+ "status": "open",+ "createdAt": "2026-09-10T12:00:00.000Z",+ "user": { "name": "Jessie Smith", "image": null },+ "options": [+ {+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "startTime": "2027-03-01T00:00:00.000Z",+ "duration": 0+ }+ ],+ "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",+ "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"+ }+}+```++```json v1+{+ "data": {+ "id": "Xk3pQ9vLm2Ab",+ "title": "Team offsite",+ "description": null,+ "location": null,+ "timeZone": null,+ "status": "open",+ "kind": "date",+ "createdAt": "2026-09-10T12:00:00.000Z",+ "updatedAt": "2026-09-10T12:00:00.000Z",+ "organizer": {+ "id": "cm3f7d1qa0000t2k9c6b8h4jr",+ "name": "Jessie Smith",+ "email": "[email protected]",+ "image": null+ },+ "requireEmail": false,+ "hideParticipants": false,+ "hideScores": false,+ "disableComments": true,+ "allowTentativeVotes": true,+ "participantCount": 0,+ "options": [+ { "id": "cm5h8x2k40000q9l4f7e2d3an", "date": "2027-03-01" }+ ],+ "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",+ "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"+ }+}+```++</CodeGroup>++## Endpoints++### Create a poll++`POST /api/private/polls` β `POST /v1/polls`++**Status code.** v1 responds `201 Created` instead of `200 OK`. A client that checks for exactly `200` will treat every successful create as a failure.++**Request.** The private API chose the poll type from whether you sent `dates` or `slots`. v1 takes an explicit `kind` and puts every option under `options`. Each request option is the response option without its `id`: `{ date }` for a date poll, `{ startTime, duration? }` for a time poll. The body is strict, so the other response fields (`id`, `status`, `createdAt`, `participantCount` and so on) must not be sent.++Date polls:++<CodeGroup>++```json Private API+{+ "title": "Team offsite",+ "dates": ["2027-03-01", "2027-03-02", "2027-03-03"]+}+```++```json v1+{+ "title": "Team offsite",+ "kind": "date",+ "options": [+ { "date": "2027-03-01" },+ { "date": "2027-03-02" },+ { "date": "2027-03-03" }+ ]+}+```++</CodeGroup>++Time polls: the `slots` wrapper is gone. `duration` and `timeZone` move to the top level, explicit times become `options` objects, and slot generators move to their own `generators` array.++<CodeGroup>++```json Private API+{+ "title": "Project kickoff",+ "location": "Zoom",+ "slots": {+ "duration": 60,+ "timezone": "Europe/London",+ "times": [+ "2027-03-01T09:00:00",+ {+ "startDate": "2027-03-08",+ "endDate": "2027-03-12",+ "days": ["mon", "wed"],+ "startTime": "14:00",+ "endTime": "17:00",+ "interval": 90+ }+ ]+ }+}+```++```json v1+{+ "title": "Project kickoff",+ "kind": "time",+ "location": "Zoom",+ "timeZone": "Europe/London",+ "duration": 60,+ "options": [{ "startTime": "2027-03-01T09:00:00" }],+ "generators": [+ {+ "startDate": "2027-03-08",+ "endDate": "2027-03-12",+ "days": ["mon", "wed"],+ "from": "14:00",+ "to": "17:00",+ "interval": 90+ }+ ]+}+```++</CodeGroup>++Field by field:++| Private API | v1 | Note |+| --- | --- | --- |+| `dates: [...]` | `kind: "date"`, `options: [{ date }]` | Duplicates are removed instead of rejected |+| `slots.duration` | `duration` | Optional in v1 when every option carries its own `duration`; required when `generators` is set |+| `slots.timezone` | `timeZone` | |+| `slots.times` (string entry) | `options: [{ startTime, duration? }]` | Each slot may override the poll `duration`, which the private API could not do |+| `slots.times` (generator entry) | `generators: [...]` | |+| generator `startTime` | generator `from` | |+| generator `endTime` | generator `to` | |+| generator `days` | generator `days` | Optional in v1; defaults to every day |+| `spaceId` | Removed | Was ignored; now rejected |+| `title` | `title` | Capped at 255 characters |++Everything else (`description`, `location`, `requireEmail`, `hideParticipants`, `hideScores`, `disableComments`, `allowTentativeVotes`, `organizer`) is unchanged. The interpretation of a `startTime` without an offset is also unchanged: wall clock time in `timeZone` when set, floating otherwise.++**Generator validation.** The private API expanded a generator and only then failed with `NO_OPTIONS_GENERATED` if nothing came out. v1 rejects an impossible generator up front with `VALIDATION_ERROR` naming the field: `to` not later than `from`, a daily window shorter than `duration`, or a date range containing none of the listed days. Times in a generator are `HH:mm`; the private API also accepted seconds.++**Response.** The full poll, in the [v1 shape](#the-poll-resource).++### List polls++`GET /api/private/polls` β `GET /v1/polls`++**Request.** Unchanged. `status`, `cursor` and `limit` work the same way, and `nextCursor` is still returned beside `data`.++**Response.** Each item is the full [v1 poll](#the-poll-resource). The private API's list items already carried `participantCount`; the rest of the new fields are additions, and the renames (`timezone`, `user`, date options) apply here too.++### Get a poll++`GET /api/private/polls/{pollId}` β `GET /v1/polls/{pollId}`++**Request.** Unchanged.++**Response.** The [v1 poll](#the-poll-resource). Note that `participantCount` is now included, so a client that called both `GET /polls/{pollId}` and `GET /polls/{pollId}/results` just to count participants can drop the second call.++### Update a poll++`PATCH /api/private/polls/{pollId}` β **removed**++<Warning>+There is no v1 endpoint that changes a poll's status. Its only supported use was closing a poll with `{ "status": "closed" }`.+</Warning>++Polls close on their own once every option is in the past. To close a poll earlier, or to reopen one, use the app. If your integration polled results and stopped once the poll was closed, keep reading `status` from `GET /polls/{pollId}/results`; that part is unchanged.++### Get poll results++`GET /api/private/polls/{pollId}/results` β `GET /v1/polls/{pollId}/results`++**Request.** Unchanged.++**Response.** Three changes:++- `kind` is added at the top level.+- Options in a `date` poll carry `date` instead of `startTime` and `duration: 0`, matching the poll resource.+- `votes` is dense. The private API omitted any vote type with zero votes, so an option nobody voted on had `votes: []`. v1 lists every vote type the poll offers, in display order, with `count: 0` where nobody chose it. A client that summed `votes` or looked a type up by `type` keeps working; a client that treated an empty array as "no votes" must check the counts instead.++<CodeGroup>++```json Private API+{+ "data": {+ "pollId": "Xk3pQ9vLm2Ab",+ "status": "open",+ "participantCount": 2,+ "options": [+ {+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "startTime": "2027-03-01T00:00:00.000Z",+ "duration": 0,+ "votes": [{ "type": "yes", "count": 2 }],+ "score": 2002,+ "isTopChoice": true+ },+ {+ "id": "cm5h8x2k40001q9l4b8f3e4bo",+ "startTime": "2027-03-02T00:00:00.000Z",+ "duration": 0,+ "votes": [],+ "score": 0,+ "isTopChoice": false+ }+ ],+ "highScore": 2002+ }+}+```++```json v1+{+ "data": {+ "pollId": "Xk3pQ9vLm2Ab",+ "kind": "date",+ "status": "open",+ "participantCount": 2,+ "options": [+ {+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "date": "2027-03-01",+ "votes": [+ { "type": "yes", "count": 2 },+ { "type": "ifNeedBe", "count": 0 },+ { "type": "no", "count": 0 }+ ],+ "score": 2002,+ "isTopChoice": true+ },+ {+ "id": "cm5h8x2k40001q9l4b8f3e4bo",+ "date": "2027-03-02",+ "votes": [+ { "type": "yes", "count": 0 },+ { "type": "ifNeedBe", "count": 0 },+ { "type": "no", "count": 0 }+ ],+ "score": 0,+ "isTopChoice": false+ }+ ],+ "highScore": 2002+ }+}+```++</CodeGroup>++`score`, `isTopChoice` and `highScore` are computed the same way today, but v1 documents `score` as opaque: sort by it and use `isTopChoice` or `highScore` to find the leaders, but do not decode it into vote counts or compare it across polls. Vote types are an open set in v1, so tolerate a `type` you do not recognise.++### Get poll participants++`GET /api/private/polls/{pollId}/participants` β `GET /v1/polls/{pollId}/participants`++**Request.** Unchanged.++**Response.** `data` is the array itself. The private API wrapped it in an object with `pollId`; v1 drops the wrapper, since you already know the poll ID from the URL. The participant fields (`id`, `name`, `email`, `createdAt`) and the ordering (oldest response first) are unchanged.++<CodeGroup>++```json Private API+{+ "data": {+ "pollId": "Xk3pQ9vLm2Ab",+ "participants": [+ {+ "id": "cm5j2r8wb0003q9l4a1x6p0zt",+ "name": "Jessie Smith",+ "email": "[email protected]",+ "createdAt": "2026-09-11T08:30:00.000Z"+ }+ ]+ }+}+```++```json v1+{+ "data": [+ {+ "id": "cm5j2r8wb0003q9l4a1x6p0zt",+ "name": "Jessie Smith",+ "email": "[email protected]",+ "createdAt": "2026-09-11T08:30:00.000Z"+ }+ ]+}+```++</CodeGroup>++### Delete a poll++`DELETE /api/private/polls/{pollId}` β `DELETE /v1/polls/{pollId}`++Unchanged. Responds `200` with `{ "data": { "id", "deleted": true } }`, or `404 POLL_NOT_FOUND`.++### OpenAPI document and docs page++`GET /api/private/openapi` β `GET /v1/openapi`++The spec moves with the API. The Scalar page at `/api/private/docs` has no v1 equivalent; this site is the reference. Both spec endpoints are public and need no key.++## Checklist++1. Change the base URL to `https://api.rallly.co/v1`.+2. Accept `201` from `POST /polls`.+3. Rewrite create requests: add `kind`, replace `dates` and `slots` with `options` and `generators`, rename `timezone` to `timeZone` and the generator's `startTime` and `endTime` to `from` and `to`, and remove `spaceId` and any other undocumented fields.+4. Read `timeZone` instead of `timezone`, and `organizer` instead of `user`, in every poll response.+5. Branch on `kind` when reading options: `date` for date polls, `startTime` and `duration` for time polls.+6. In results, stop treating an empty `votes` array as "no votes"; read the counts.+7. Read participants from `data` directly.+8. Parse every error as `{ "error": { "code", "message" } }` and drop any handling of the private API's validator output, `DUPLICATE_DATES`, `NO_OPTIONS_GENERATED` and `TRANSITION_NOT_AVAILABLE`.+9. Remove any call to `PATCH /polls/{pollId}`.diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex 85a48df16..8334e7309 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -83,7 +83,8 @@"api-reference/authentication","api-reference/rate-limits","api-reference/errors",- "api-reference/changelog"+ "api-reference/changelog",+ "api-reference/migrating-from-the-private-api"]},{