Build on Nifty
This page covers what the Nifty API supports, how to test an integration, what the limits are, and where to get help.
If you already know what you are building, go straight to Getting started.
What you can build
Everything runs against one host, https://openapi.niftypm.com, and there are
three shapes of integration.
A script or automation for your own workspace. You authenticate with a Personal Access Token and the API acts as you, with your team membership and your role's permissions. This is the right shape for a nightly export, an internal dashboard, a migration, or anything else where you own both ends.
An app that other teams connect to. You register an OAuth 2.1 client and
take each team through the authorization-code flow with PKCE; a member approves
the access at a consent screen, picks the workspace, and you get an access
token that acts for that workspace. Two things to design around from the start:
the granted scope is clamped to the approving member's role and re-clamped
on every refresh, so ask for least privilege and treat a 403 as a normal
outcome rather than a bug; and refresh tokens rotate and are single-use, so
storing the newest one is a correctness requirement, not a nicety.
Authorization (OAuth 2.1) has the whole flow.
Something that reacts to changes. Register a webhook over the
v3 API and Nifty posts events to an HTTPS endpoint you control. Deliveries are
signed, a webhook only ever fires for the workspace it was created in, and you
can pin its apiVersion to a dated value so the payload shape holds still
while the API moves on. The event catalogue is the list of
what you can subscribe to, and GET /api/v3/webhooks/{id}/deliveries tells you
why one auto-disabled. There is no published streaming endpoint — webhooks are
how changes reach you without polling.
Two boundaries worth knowing before you commit to a design:
- Some resources are legacy-only.
templates,apps,usersandinviteshave no v3 counterpart; an integration that needs them stays on/api/v1.0for those calls. The rest of the mapping is in Migrating from v1. - An OAuth app cannot reach all of the legacy surface. Some legacy routes
answer
403to a fine-grained token. The covered segments are listed on Authentication.
Where to get help
- r/NiftyPM — the Nifty community, and the best place for "has anyone built…" and "is this supposed to…" questions.
- Help Center — product documentation, including how the API fits the rest of Nifty.
- team@niftypm.com — for anything account- or workspace-specific, and for a bug you think is ours.
Sandbox and testing
There is no separate sandbox host. The API has one host and one set of data: what you write is written, and your colleagues will see it. There are two ways to try things safely.
Use your own token against the reference. Create a token in Nifty under Settings → API Tokens → New token, then save it on the API tokens page here. Every Test panel in the reference then calls the real API as you, so you can read a live response before you write a line of code. The token stays in your browser and is sent nowhere except the request you trigger.
Sign up a second Nifty workspace and point your integration at that. A
workspace is the isolation boundary that already exists: it has its own data,
its own tokens, and its own webhooks, and none of them reach across. Testing
writes against a workspace you created for the purpose is how you exercise
POST, PATCH and DELETE without touching anything real.
Limits and higher limits
Every request passes two sliding-window limiters, and the numbers — per method, per bucket — are on Rate limits. One thing about which limit you are spending matters more than the numbers if you are building for other people's workspaces:
- Reads and most writes are charged to your token. Both
GET,POSTandPATCHbuckets are keyed on the access token. An OAuth grant issues one token per authorisation, so one customer's requests never spend another customer's allowance, or yours. DELETEalso spends a bucket keyed on the client IP. For a hosted integration the client IP is your own server's address — shared by every workspace you serve from it — so size delete traffic against all of your customers at once, not one at a time.
The published limits apply to every API token. If they block a legitimate integration, write to team@niftypm.com and describe the traffic.
Listing your app
An OAuth client works as soon as you register it and a team authorises it. The integrations catalogue in Nifty (Settings → App Center) is maintained by Nifty and is not open to submissions.
To tell people what you built, post it on r/NiftyPM or write to team@niftypm.com.
Staying informed
- Changelog — every v3 release.
- Versioning — what can change under
/api/v3without warning, what cannot, and the date v1.0 stops serving requests. - r/NiftyPM — where changes worth interrupting you for get announced.