Send to Nifty API

With Nifty Plus, other apps, scripts and services such as Zapier can send things to your Nifty. They send each item to Nifty Plus, and your copy of Nifty collects it, even when your Nifty isn't reachable from the internet. Unlike the Nifty API, this API can only add things, so a token for it can't read your data.

Make a token

Make a token for each app that sends things to Nifty, so you can stop one without stopping the others.

1. Open Settings → Connections → Send to Nifty API.
2. Choose New token.
3. Type a name for the app that will use it, such as "Zapier".
4. Choose Add token.
5. Choose Copy token. Nifty shows the token only until you leave the page, and keeps only its last four characters.

Treat a token like a password, because anyone who has it can send things to your Nifty. To stop a token working, choose the trash button beside it, then choose Revoke token. You can have up to 20 tokens, and make up to 10 a day. Each token shows when it was last used, to the hour.

The examples on this page keep the token in a variable.

export NIFTY_SEND_TOKEN=nsk_…

To check that a token works without sending anything, ask for GET /v1/token. It answers with the token's name, or with the same error sending something would get.

curl https://api.nifty.fyi/v1/token -H "Authorization: Bearer $NIFTY_SEND_TOKEN"

Send a task

curl https://api.nifty.fyi/v1/tasks \
  -H "Authorization: Bearer $NIFTY_SEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Renew passport", "deadline_on": "2026-11-30", "list": "Admin", "source": "My script"}'

{ "id": "01k7z9d3f8g2h4j6k8m0n2p4q6", "kind": "task", "status": "waiting", "received_at": "2026-10-20T13:05:00.000Z" }

The id is the task's ID in Nifty once it's added. Keep it if you want to ask what became of the task later.

What you can send

Route	Body	Fields
POST /v1/tasks	JSON	title (required), description (Markdown), start_on, deadline_on, expires_on, list, project, assignee
POST /v1/notes	JSON	title or body (at least one; the body is Markdown, or plain text with "format": "text"), category, tags, people, projects
POST /v1/events	JSON	title and date (required); for a timed event, start_time and end_time (both required) and time_zone; all_day, location, notes
POST /v1/documents	Form, or JSON with file_url (by its link)	file (a PDF, or a PNG, JPEG or WebP image of at least 200 × 200 pixels; not HEIC), and metadata (JSON): name, folder, dated_on, people, projects
POST /v1/emails	Form, or JSON with file_url	file (an .eml email, added with any PDFs it has attached), and metadata (JSON): folder, people, projects

Every item can also have a source, your app's name, up to 50 characters. Nifty shows it in the item's details, such as "Sent to Nifty by My script, 20 Oct 2026 at 14:05". Without one, it shows as sent by its token's name. Dates are YYYY-MM-DD and times HH:MM.

An event is added to My Nifty Calendar, in your own time zone unless you give a time_zone such as Europe/London. An all-day event leaves out start_time, end_time and time_zone. A note's body or a task's description over 32 KB is added as plain text.

To send a document, send a form with the file and its details.

curl https://api.nifty.fyi/v1/documents \
  -H "Authorization: Bearer $NIFTY_SEND_TOKEN" \
  -F "[email protected]" \
  -F 'metadata={"folder": "Bills/Energy", "dated_on": "2026-10-01"};type=application/json'

Send a file by its link

When an app has a link to the file rather than the file itself, send the link as file_url, with the details beside it, as JSON. Nifty Plus downloads the file straight away.

curl https://api.nifty.fyi/v1/documents \
  -H "Authorization: Bearer $NIFTY_SEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/bills/energy.pdf", "folder": "Bills/Energy"}'

• The link must be https, and lead straight to the file. A web page about the file, such as a share page, gets 422.
• A link to an IP address, to localhost or to Nifty's own addresses, or with a port, user name or password in it, gets 422. Up to 3 redirects are followed.
• The file is named from the server's Content-Disposition, or else from the link.
• If the file's server can't be reached, answers with a server error, or takes more than 30 seconds in all, the answer is 502 file_url_unreachable. Try again later. Any other answer that isn't the file, such as a 404, gets 422.
• Sending the same request again with the same Idempotency-Key doesn't download the file again.

The full description of this API is in its OpenAPI file.

How Nifty files what you send

You can't know the IDs of your lists, projects and people, so give their names instead. When Nifty collects an item, it looks for each name, ignoring upper and lower case.

• A list, category, folder or a task's project: The item goes there if you have one with that name. Give a folder inside another as a path, such as Bills/Energy.
• People and projects on a note, document or email: A note mentions them in its last paragraph, and a document is linked to them.
• A person: Give their email address, name or alias. If more than one person matches, Nifty leaves the person out.
• A tag: Nifty uses the tag with that name, or makes a new one.

Nifty doesn't make anything else. When a name matches nothing, it's left out, and the item goes in the usual place. For example, a document goes to Unsorted, and a task has no list or project. A task is in a list or a project, so when both match, it goes in the list. When its assignee is you, it isn't delegated.

Ask what became of an item

Each item waits on Nifty Plus until your Nifty collects it, which it does every 2 minutes while it's running. To collect items straight away, choose Check now in Settings → Connections → Send to Nifty API. To find out what happened to an item, ask with its ID.

curl https://api.nifty.fyi/v1/deposits/01k7z9d3f8g2h4j6k8m0n2p4q6 -H "Authorization: Bearer $NIFTY_SEND_TOKEN"

The status is one of these:

Status	What it means
waiting	Nifty hasn't collected it yet.
added	It's in Nifty.
skipped	Nifty couldn't add it. It may not have passed Nifty's checks (for example, an event's time doesn't exist on that day), or it was sent before Nifty Plus moved to another copy of Nifty.
expired	Nifty didn't collect it within 7 days, so Nifty Plus deleted it.

Nifty Plus remembers what became of an item for 30 days after it's collected or expires. After that, asking gets 404 not_found. Settings → Connections → Send to Nifty API also tells you when items couldn't be added.

Send safely more than once

If a request fails partway, you can't tell whether the item arrived. Send an Idempotency-Key header, such as a UUID, and send the same request again with the same key. Nifty Plus remembers a key for 7 days, and answers a repeat with the first item and Idempotent-Replayed: true, rather than adding a second one. The same key with a different request gets 422 idempotency_key_reused. Each token has keys of its own, so two apps can't clash.

Limits and errors

• Each token can make 60 requests a minute, and all of an account's tokens 300 together. More gets 429 rate_limited, so wait for the seconds Retry-After gives.
• A file can be up to 20 MB, and an item's other details up to 256 KB. More gets 413 too_large.
• Up to 470 items sent through the API, and 1 GB of them in all, can wait to be collected. Forwarded emails have room of their own.
• A form needs a Content-Length, as curl and most HTTP libraries send. Without one, it gets 411 length_required.

Errors are JSON, as {"error": {"code": "…", "message": "…"}}. A 422 invalid names each field's problem in details, and nothing is sent. These errors mean something needs doing first:

Error	What to do
401 invalid_token	Check the token. It may have been revoked.
403 not_entitled	Renew the Nifty Plus subscription, then try again.
409 not_ready	Nifty hasn't finished connecting to Nifty Plus. Open Nifty, then try again.
502 file_url_unreachable	The server with the file failed or didn't answer. Try again later.
507 full	Nifty needs to collect what's waiting first. Open Nifty, then try again.

How your items are kept

Each item is encrypted as soon as it arrives, with a key that only your copy of Nifty has, so nobody at Nifty can read it while it waits. Nifty Plus deletes an item once your Nifty has collected it, or after 7 days. If you move Nifty Plus to another copy of Nifty, items that were waiting for the old copy can't be opened by the new one.