---
name: form-plume-api
description: Automate and manage a Form Plume workspace through its authenticated REST API. Use when creating or configuring forms programmatically, reading or updating submissions, managing webhooks or integrations, retrieving analytics or usage, or building server-side Form Plume automation. Do not use for a website form that only needs to submit visitor data to its public endpoint.
---

# Automate Form Plume with the API

Use the Form Plume management API for server-side workspace automation. Follow the [API guide](https://formplume.com/docs/api.md) and treat the machine-readable [OpenAPI specification](https://api.formplume.com/v1/openapi.json) as the source of truth for paths, methods, request bodies, response schemas, and enums.

## Decide whether this skill applies

Use this skill when the user wants to:

- create, inspect, or configure forms programmatically;
- list, search, update, export, or otherwise act on submissions;
- manage email settings, autoresponders, webhooks, integrations, spam controls, or blocklists;
- retrieve analytics or usage; or
- build a server-side script, service, CI workflow, or agent that manages Form Plume.

Do **not** use the management API merely to receive a visitor's form submission. Public website forms post to `POST https://api.formplume.com/f/{public_slug}` without an organization API key. For that work, use the [form-building skill](https://formplume.com/SKILL.md).

A task may use both skills, but keep the two flows separate: browser code submits to `/f/{public_slug}`; trusted server-side automation calls `/v1/*`.

## Before coding

1. Read the relevant [API documentation](https://formplume.com/docs/api.md) and inspect the current OpenAPI operation before implementing it. Do not invent endpoints, fields, enum values, SDKs, or response shapes.
2. Determine whether the task is read-only or requires writes. Prefer a `read`-scope key for GET-only work. Use a `full`-scope key only when the requested workflow must create, update, or delete resources.
3. Have the user create an organization key under **API Keys** in the Form Plume dashboard if one is not already available. Do not ask them to paste the secret into chat or source code; have them provide it through a secret manager or the `FORMPLUME_API_KEY` environment variable.
4. Verify the key before a longer workflow by calling `GET /v1/api-keys/current`. Confirm that it belongs to the intended organization and has the required scope.
5. Clarify the intended workspace, form, filters, and mutation before acting when they are not already clear from the request or API response. Never guess opaque resource IDs.

Organization API keys are not public form slugs and are not per-form access keys. Never place an organization API key in browser code, mobile app bundles, logs, screenshots, generated output, or source control.

## Make API requests

Use this base URL unless the user explicitly provides another environment:

```txt
https://api.formplume.com/v1
```

Authenticate every request with the organization key:

```bash
curl -sS https://api.formplume.com/v1/api-keys/current \
  -H "Authorization: Bearer $FORMPLUME_API_KEY"
```

- Send and accept JSON unless the OpenAPI operation specifies another content type.
- Check the HTTP status before trusting or parsing the response body.
- Treat IDs and cursors as opaque strings. Do not derive, shorten, or modify them.
- Follow cursor pagination until `next_cursor` is `null` when the user asks for the complete result set. Pass the cursor back verbatim.
- Use RFC 3339 UTC timestamps and the exact snake_case field names and enum values from OpenAPI.
- Handle the documented JSON error envelope. Surface its stable error code, message, and field pointer when present.
- On `429`, honor `Retry-After`. Retry only operations that are safe to repeat; check the operation's idempotency behavior before retrying a write.
- Request only the data needed for the task and avoid printing submission content or other personal data unnecessarily.

The API allows 300 requests per minute per organization key. See [API rate limits](https://formplume.com/docs/api/rate-limits.md) for retry behavior and [API errors](https://formplume.com/docs/api/errors.md) for the error contract.

## Apply changes safely

- Inspect the current resource before updating it. Preserve settings the user did not ask to change.
- Preview or summarize the exact target and effect before irreversible or high-impact operations such as deleting submissions or forms, erasing submitter data, rotating webhook secrets, or bulk updates.
- Do not broaden a read task into a write. Do not change billing, organization membership, invitations, or API keys through the API; those require a dashboard session.
- Keep API calls in trusted server-side code. If the user's application needs browser-side form delivery, use the public submission endpoint instead.
- When an official MCP tool already represents the requested operation and the user is working through an MCP-capable agent, the [Form Plume MCP server](https://formplume.com/docs/api/mcp.md) is an alternative interface over the same management API. The same scope and secret-handling rules apply.

## Verify and report

1. Verify writes with a follow-up GET when the API exposes one.
2. For list or export work, report the filters used and whether every cursor page was processed.
3. Report the resources read or changed without revealing the API key or unnecessary personal data.
4. State any remaining dashboard-only step, such as creating a key, changing billing, or managing organization members.
5. Remove temporary output containing sensitive submission data and confirm that no secret was written to the repository.