Skip to content
Documentation navigation

Start here

Product

Integrations

SDK

MCP

SDK HTTP API

Use these endpoints to integrate in-app feedback with Upweight. The response fields below are exhaustive allowlists.

Branding configuration and capacity errors

GET /api/v1/config accepts the publishable key without a user header and creates no customer. Its exhaustive response is data.branding.visible (boolean), data.branding.url (string), and data.ttl_seconds (3600). Responses send Cache-Control: private, max-age=3600 and Vary: authorization; existing IP/key limits apply. Invalid, missing, or revoked keys retain the invalid_key 401 envelope.

The branding URL is fixed to https://upweight.dev/?utm_source=ios_sdk&utm_medium=feedback_sheet&utm_campaign=powered_by, with no tenant or customer identifiers. visible is false only for a currently paid workspace with an explicit saved hide preference; downgrade makes branding visible without deleting the preference.

Client implementation contract: cache per publishable key, invalidate on key change, fetch at configure and sheet open if stale, and default visible without fresh valid config. Expired hidden cache must become visible offline; failures do not renew freshness. Validate HTTPS and exact upweight.dev host before linking. This server contract does not establish that a new Swift binary has been released.

Free retains 25 feedback posts across all origins/statuses with no reset. Creation beyond capacity returns 403 feedback_limit_reached in the existing error envelope; rejected creation stores no post or incidental customer/source/vote. Deletion frees capacity, archive/close do not. Existing votes/comments remain available under existing abuse limits. Paid workspaces have no plan post cap. Config adds no fields to feedback-creation success responses.

Requests and identity

Base URL: https://upweight.dev. Base path: /api/v1. Use HTTPS, Accept: application/json, and Content-Type: application/json for JSON bodies.

Every endpoint requires Authorization: Bearer <publishable-key>. All endpoints except exact GET /api/v1/config also require X-Upweight-User: <stable user ID>. The key begins with upw_pk_ and identifies the workspace and workspace-connected app; clients cannot select another tenant or app in the body.

The user header is trimmed, then must contain 1–255 characters and no control characters. Missing, blank, too long or invalid values return missing_user (400). RevenueCat anonymous IDs such as $RCAnonymousID:example are accepted. Use your host app’s stable user ID; it should match your RevenueCat appUserID only when RevenueCat is connected. RevenueCat is optional. Changing the ID through identify() does not merge identities on the server.

GET requests only look up a customer and never create a user. For an unknown ID, voted_by_me is false and updates are empty. Writes upsert the workspace-scoped SDK customer. An SDK identity satisfies the board's sign-in-to-vote requirement, but is not proof of the app user's identity.

Endpoints

All paths below are relative to /api/v1. IDs are UUID strings. Times are ISO8601 UTC strings. Fields below are exhaustive response allowlists, not examples of a larger payload.

MethodPathParametersSuccess statusResponse
GET/configNo user header required200{data: {branding: {visible: boolean, url: string}, ttl_seconds: 3600}}
GET/itemsQuery: sort, status, cursor, limit (see pagination)200{data: [item], next_cursor: string or null}
POST/itemsJSON: title (string, 3–160 characters), body (string, at most 20,000 characters)201{data: item}
POST/items/:id/votePath: item UUID; no body200{vote_count: integer, voted_by_me: true}
DELETE/items/:id/votePath: item UUID; no body200{vote_count: integer, voted_by_me: false}
GET/me/updatesQuery: optional since (ISO8601 timestamp)200{data: [{id, title, status, changed_at}], server_time}
PATCH/meJSON: optional email (string, valid email, at most 160 characters), display_name (string, at most 80 characters), email_status_updates (boolean)200{data: {app_user_id, display_name, has_email, email_status_updates}}

An item contains only id, title, body, status, vote_count, voted_by_me and updated_at. The body is the stored description; vote count is the raw count, never a weighted score. Display name can be null; has_email and email_status_updates are booleans.

Suggestions follow the web board's creation and moderation path: open status, customer_submission source, and an automatic author vote. Voting and unvoting are idempotent: repeated requests do not add duplicate votes or decrement below the actual count.

Item and vote endpoints return 403 board_disabled when public feedback is disabled. The /me endpoints still work. Foreign, missing, archived or merged items are not exposed.

Pagination

sort defaults to top; supported values are top and new. Optional status accepts only open, planned, in_progress and shipped. Archived and merged items are excluded.

limit defaults to 20 and is capped at 50. Pagination uses database keysets, not offsets:

  • top: raw vote count descending, creation time descending, ID descending.
  • new: creation time descending, ID descending.
  • The API's top sort does not use the web board's in-memory source-count tiebreak.

Treat next_cursor as opaque. Pass it unchanged as cursor on the next request, retaining the same sort and filters. Null means there is no next page. Its encoding is unpadded base64url of JSON with s (sort), v (raw vote count), t (creation time in ISO8601) and i (UUID). A malformed cursor or one whose sort differs from the request returns 422 validation_failed. Invalid sort or status also returns 422. Vote changes between requests can change ordering; the cursor is not a snapshot.

Updates

since defaults to 30 days before the request. At most 50 rows are returned: the latest change per item after since into a public status, for items the customer currently has a customer vote on. Archived and merged items are excluded. Bad timestamps return 422 validation_failed. There is no cursor on this endpoint. server_time is an ISO8601 server timestamp.

Profile and email privacy

PATCH email is write-only and unverified, reserved only for ship notifications, and never matched to RevenueCat. When ship notifications are enabled, opted-in customers who still vote on an eligible shipped item can receive ship emails, including at unverified SDK addresses. It cannot attract subscription revenue or merge customers. The response never echoes an email, including an existing verified web email; has_email reports presence only.

A verified web email cannot be changed from the app: 422 with errors.email: ["cannot be changed from the app"]. An email already held by another workspace customer returns 422 with errors.email: ["is already in use"]; nothing is merged. email_status_updates is the ship-notification preference, not email verification.

Success fixtures

Items page (200)

{
  "data": [
    {
      "id": "123e4567-e89b-42d3-a456-426614174000",
      "title": "Home Screen widgets",
      "body": "Show my progress on the Home Screen.",
      "status": "open",
      "vote_count": 1,
      "voted_by_me": true,
      "updated_at": "2026-10-05T09:00:00Z"
    }
  ],
  "next_cursor": null
}

Created item (201)

{
  "data": {
    "id": "123e4567-e89b-42d3-a456-426614174000",
    "title": "Home Screen widgets",
    "body": "Show my progress on the Home Screen.",
    "status": "open",
    "vote_count": 1,
    "voted_by_me": true,
    "updated_at": "2026-10-05T09:00:00Z"
  }
}

Vote on (200)

{
  "vote_count": 1,
  "voted_by_me": true
}

Vote off (200)

{
  "vote_count": 0,
  "voted_by_me": false
}

Profile (200)

{
  "data": {
    "app_user_id": "demo-user",
    "display_name": "Alex",
    "has_email": true,
    "email_status_updates": true
  }
}

Updates (200)

{
  "data": [
    {
      "id": "123e4567-e89b-42d3-a456-426614174000",
      "title": "Home Screen widgets",
      "status": "shipped",
      "changed_at": "2026-10-06T09:00:00Z"
    }
  ],
  "server_time": "2026-10-06T09:01:00Z"
}

Errors

Errors use {"error":{"code":"…","message":"…"}}. For validation_failed, a top-level errors map contains field names and arrays of messages. Clients branch on code and HTTP status, not human-readable message text.

CodeHTTP statusMeaning
invalid_key401Missing, malformed, unknown or revoked publishable key
missing_user400Missing or invalid X-Upweight-User
not_found404Missing or inaccessible resource, including another workspace's item
rate_limited429Limit exceeded; Retry-After header gives seconds to wait
validation_failed422Invalid body, cursor, since, sort or status
board_disabled403Public feedback disabled (items and votes only)
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid SDK key"
  }
}
{
  "error": {
    "code": "missing_user",
    "message": "Missing or invalid user"
  }
}
{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed"
  },
  "errors": {
    "title": [
      "should be at least 3 character(s)"
    ]
  }
}
{
  "error": {
    "code": "board_disabled",
    "message": "Public feedback is disabled"
  }
}

Rate limits

Defaults per 60 seconds: 120 requests per IP before authentication, 600 per key after authentication, and 30 writes per key+user (all non-GET requests). The global endpoint limiter also applies and returns the same JSON 429 envelope for /api/v1. Honour Retry-After seconds; do not immediately retry a denied request.

Security model

The publishable key ships in your app binary. It selects your workspace and app; it does not prove who the app user is. Made-up IDs that do not match a RevenueCat customer have no subscription and can only add free votes, never revenue weight. However, someone who knows a real app user ID could impersonate it; not all malicious votes are guaranteed to be unweighted.

Limits apply per IP, per key, and per user for writes. Owners can remove votes and rotate keys. The publishable key is not an identity-verification mechanism.

SDK-supplied email is write-only and unverified; it never attracts RevenueCat revenue and never merges into a verified web sign-in. Because the key is public, someone could attach an address they do not own; writes are bounded per key and per IP because user IDs can be made up freely. When ship notifications are enabled, opted-in current customer voters can receive ship emails at these unverified addresses. Delivery is permanently deduplicated per customer and per normalized (trimmed, lowercased) email address for each item, including after reopening and shipping again or changing the customer's address. Claims are retained; ambiguous provider outcomes are not retried, so delivery is not guaranteed. Every ship email includes one-click unsubscribe that disables shipped-update emails for that workspace customer (email_status_updates=false), not an address-wide unsubscribe or email verification. An "already in use" response can reveal, at a rate-limited pace, that an address is registered on this board.

Rotate by releasing a new app version with the new key. Up to two keys can remain active during the overlap. Once old versions can safely stop using the previous key, use Revoke key for the previous key. Revocation breaks requests from binaries still using it. Creating a third active key revokes the oldest. Plaintext keys are shown once; only hashes and prefixes are stored. Do not put secret RevenueCat credentials in the client.

Response privacy guarantee

No SDK response ever returns revenue, subscription, weighting or classification data. This includes errors and updates. The public SDK shows plain vote counts only. Revenue is non-public. The authenticated management screens show revenue only for the workspace owner; an organisation admin role alone does not grant access to those screens. Authorised owner and admin MCP clients can receive revenue and classification counts. Imported App Store reviews never receive RevenueCat weighting.

See the SDK overview for key management, the Swift guide for iOS setup, and shipped-update emails for delivery eligibility.

Last reviewed