Use the Uplup API and API keys

What this does

Uplup has a REST API at https://api.uplup.com/api/v1. With it you can list and create quizzes and forms, add and edit questions, read responses and analytics, change quiz scoring and design, manage webhooks, read your account limits and run random name picker wheels. Every request carries a Bearer token, which is either an API key you create in a workspace or an OAuth access token an app obtained when you authorised it (the MCP server works that way).

This article covers the keys and the rules. The full endpoint reference with code samples in six languages is at uplup.com/api.

How to generate an API key

1. Open the workspace you want the key for and click Integrations in the left sidebar.
2. Switch to the API Keys tab.
3. Click Generate New API Key.
4. Give it a name so you remember what it is for, and choose Read Only or Read & Write.
5. Click Create and copy the key straight away. It is shown once and cannot be retrieved later.

Keys start with uplup_live_ or uplup_test_ followed by 32 characters. You can create as many as you need, and you can revoke any of them from the same tab.

A key belongs to one workspace

Every key is created inside a workspace and stays bound to it. You must own that workspace or be an accepted team member to create a key there. Everything you see through the key is that workspace’s: its quizzes and forms, its wheels, its webhooks and its saved themes. A team member sees the owner’s forms through the key, and none of your other workspaces are visible through it, so create a separate key in each workspace you want to reach. If the person who created a key later leaves the workspace, the key stops working and the API answers 401.

How to use the API key

Send the key in the Authorization header as a Bearer token: the word Bearer, a single space, then the key. Send JSON bodies with Content-Type: application/json. For example:

GET https://api.uplup.com/api/v1/forms?type=quiz&sort=created_desc&limit=20
Authorization: Bearer uplup_live_your_key_here
Content-Type: application/json

Successful responses look like {"success": true, "data": ...}, and list endpoints add total, limit and offset. Errors look like {"success": false, "message": "..."} with a matching HTTP status: 400 for a bad parameter, 401 for a missing or invalid key, 403 for a permission or plan problem, 404 when the item is not in your workspace and 429 when you are over the rate limit.

Read versus write

There are two permission levels. A Read Only key can call every GET endpoint and the responses export. Every other call (POST, PATCH, PUT and DELETE) needs a Read & Write key. If a read-only key tries to create or change anything, the API answers 403 with the message This token has read access only. OAuth tokens follow the same rule through their read and write scopes. Give each key the minimum it needs: a dashboard that only pulls responses should run on a Read Only key.

Rate limits

Each key or token may make 600 requests an hour, on every plan. Every authenticated response carries three headers so your code can pace itself: X-RateLimit-Limit (600), X-RateLimit-Remaining (requests left in the current hour) and X-RateLimit-Reset (the Unix time the window resets). Going over returns 429 with a Retry-After header holding the seconds to wait. If you need more, contact support.

What depends on your plan

API access itself is on every plan, including Free, and whether a key can write depends on the permission you chose, not the plan. Two things follow the workspace owner’s plan:

• Exporting responses (POST /forms/{form_id}/submissions/export) needs Pro or higher. On Free the call returns 403 with upgrade_required: true.
• Webhooks need Pro or higher, and a workspace can hold up to 25 of them. See Webhooks.

Responses also count against the plan’s monthly allowance (10 a month on Free, 1,000 on Pro, 10,000 on Business). On Free, responses beyond the allowance come back as locked rows: is_hidden is true and the email and answers are left out, and the list carries hidden_count. GET /account reports your plan as free, pro or business together with the limits and features that apply.

The main endpoints

Endpoint	What it does
GET /forms	List quizzes and forms. Parameters: type (form, quiz or all), sort (created_desc, created_asc or title), limit (1 to 100), offset.
POST /forms	Create a quiz or form: title, content_type (form or quiz), presentation_mode (multi-page, card-form or single-page), language, custom_url.
GET /forms/{form_id}	One form with its full document.
PATCH /forms/{form_id}	Change the title, description, language, custom URL or presentation mode, or send a whole document.
POST /forms/{form_id}/clone	Duplicate a form, with an optional title for the copy.
POST /forms/{form_id}/publish	Publish or unpublish with published: true or false.
/forms/{form_id}/fields	List, add, update, delete and reorder questions. Field types use the builder’s camelCase names, for example multipleChoice, shortAnswer, email.
GET /forms/{form_id}/submissions	Responses, with sort (newest, oldest, highest_score, lowest_score), filter_country and filter_passed.
POST /forms/{form_id}/submissions/export	Export as csv (default) or json. Pro or higher.
GET /forms/{form_id}/analytics	Views, responses and conversion rate for a period of 7d, 30d, 90d or all. The /submissions variant groups counts by day, week or month.
/forms/{form_id}/quiz/settings	Read or merge quiz settings: pass mark, timer, retakes, question behaviour, results display, lead capture and personality types.
GET /forms/{form_id}/quiz/results and /quiz/leaderboard	Per-attempt score, max score, percentage and pass status, and the top attempts ranked by percentage.
/webhooks	Create and manage webhook subscriptions, send a test, rotate the secret and read the delivery log. Pro or higher.
GET /account	Plan, usage, limits and features of the workspace behind the key.
/wheels	Random name picker wheels: entries, settings, spins, results and sharing.

Every endpoint, parameter and response shape is documented at uplup.com/api.

Security

• Never embed the API key in client-side code (a web page or a mobile app). Call the Uplup API from a server you control.
• Scope each key to the minimum it needs. If a key only needs to read responses, make it Read Only.
• Rotate keys periodically. Generate a new one, switch your code to it, then revoke the old one in the API Keys tab.
• Use a uplup_test_ key while you are developing and keep live keys for production.