Developer API

Manage forms, submissions and stats programmatically over the Nisuform RPC API with a Bearer API key.

Create an API key

Keys are shown once at creation. Copy it straight into your secrets.

Open Account > Developer in the dashboard and create a key. Keys start with nfa_, are shown once at creation and are stored hashed. Treat them like passwords: put them in environment variables, never in client-side code.

Authentication

Send the key as a Bearer token on every request:

Authorization: Bearer nfa_YOUR_KEY

Endpoint and protocol

The API is a compact RPC surface at https://api.nisuform.dev/rpc. A procedure call is the base URL plus the procedure name:

GET procedures take their input as a URL-encoded JSON data query parameter
POST procedures take their input as a JSON request body
Responses are plain JSON

Procedures

Forms

Procedure	Method	Input	Returns
`forms.list`	GET	none	`{ forms }`
`forms.create`	POST	`{ name }`	Form
`forms.get`	GET	`{ id }`	Form
`forms.update`	POST	`{ id, ...fields }`	Form
`forms.delete`	POST	`{ id }`	`{ ok: true }`
`forms.regenerateKey`	POST	`{ id }`	Form

forms.update accepts name, status (active or paused), emoji, notifyEnabled, notifyEmail, notifySubject, notifyFromName and redirectUrl. All fields are optional.

Submissions

Procedure	Method	Input	Returns
`submissions.list`	GET	`{ formId, filter?, limit?, offset? }`	`{ items, total, unreadCount }`
`submissions.get`	GET	`{ formId, id }`	Submission
`submissions.setFlags`	POST	`{ formId, id, read?, starred?, isSpam? }`	Submission
`submissions.delete`	POST	`{ formId, id }`	`{ ok: true }`

filter is one of all, unread, starred, spam. limit is 1 to 100, default 20.

Stats

Procedure	Method	Input	Returns
`stats.overview`	GET	`{ days?, formId? }`	`{ totals, series }`

days is 7, 30 or 90. totals includes accepted submissions and spam blocked; series is a daily count array.

API keys

Procedure	Method	Input	Returns
`developer.keys.list`	GET	none	`{ keys }`
`developer.keys.create`	POST	`{ name }`	Key with `key` value, shown once
`developer.keys.revoke`	POST	`{ id }`	`{ ok: true }`

Examples

List your forms:

curl "https://api.nisuform.dev/rpc/forms.list?data={}" \
  -H "Authorization: Bearer nfa_YOUR_KEY"

Create a form:

curl -X POST "https://api.nisuform.dev/rpc/forms.create" \
  -H "Authorization: Bearer nfa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact form"}'

Read the latest submissions for a form:

curl "https://api.nisuform.dev/rpc/submissions.list?data=%7B%22formId%22%3A%22FORM_ID%22%2C%22limit%22%3A5%7D" \
  -H "Authorization: Bearer nfa_YOUR_KEY"

Errors

Errors return a JSON body with a code and a matching HTTP status:

Status	Code	Cause
400	`BAD_REQUEST`	Invalid input, check field formats
401	`UNAUTHORIZED`	Missing, invalid or revoked key
404	`NOT_FOUND`	Unknown form, submission or key id

NoteIDs are UUIDs. Copy them from the dashboard URL or from the forms.list response.