--- url: https://docs.codefox.ai/connect/pampas-api.md --- # Use the Pampas API This page lets you work with Pampas forms from your own code: list and create forms, publish them, read their responses, export them as CSV and invite people to fill them in. For what Pampas is, see [Pampas](/apps/pampas/). The API lives on Pampas's own address under `/api/v1`, for example `https://forms.example.com/api/v1`. Two descriptions come with it, both behind a key: * `GET /api/v1/openapi.json`: the OpenAPI 3.1 document. * `/api/docs`: a page that lists every endpoint and which key scope it needs. Someone signed in to Pampas can open it in the browser without a key. ## Before you start * Someone who **can manage** Pampas creates the key, in Pampas's **Settings**, under **Server**. ## Create a key 1. In Pampas, open **Settings**. 2. Under **API keys**, enter a **Label** for what will use the key. 3. Choose a **Scope**: `read` can only fetch; `readwrite` can also create and change. 4. Select **Create key**. The key starts with `pfk_` and is shown once: copy it now. A key acts as the person who made it. It stops working (401) when that person is removed or loses access to Pampas, and at once when the key is revoked. ```bash export PAMPAS=https://forms.example.com/api/v1 export KEY=pfk_... curl -s "$PAMPAS/forms" -H "Authorization: Bearer $KEY" ``` ## Read forms and responses | Call | What it returns | |---|---| | `GET /forms` | Every form, newest first: `id`, `key`, `name`, `status` (`draft`, `published`, `closed`), `testMode`, `publishedVersion`. | | `GET /forms/{id}` | One form with its `workingDefinition` and `definitionRevision`. | | `GET /forms/{id}/responses` | Its responses, newest first: `id`, `status`, `submittedAt`, `testMode`, `suspectedSpam`, `verifiedEmail`, `recipientEmail`. | | `GET /forms/{id}/responses/{rid}` | One response with its answers (`fieldKey`, `label`, `text`, and signed download links for uploaded files). | | `GET /forms/{id}/summary` | The same numbers as the form's summary in Pampas. | The forms, responses and deliveries lists come 25 to a page (`limit` up to 100); pass `nextCursor` back as `cursor` for the next page. On `GET /forms/{id}/responses`: * `filter` is `all` (the default), `spam` or `deleted`; * `verified=yes` or `verified=no` keeps responses with or without a verified email; * `recipient_id` keeps one invited person's responses; * `q` searches the answer text (2 to 200 characters, up to 50 results, no paging). The responses list includes test responses. The summary leaves them out of a live form, and a CSV export always leaves them out. ## Export responses as CSV 1. Start the export: ```bash curl -s -X POST "$PAMPAS/forms/$FORM/exports" -H "Authorization: Bearer $KEY" ``` The answer is `{ "id": ..., "status": "pending" }`. A `read` key can do this. 2. Ask for its status with `GET /exports/{id}` until `status` is `done` (or `failed`). 3. Download the CSV from the `url` in that answer. The URL is signed and needs no key; it expires with the file, seven days after the export finishes (`expiresAt`). The CSV leaves out test responses and includes suspected spam. ## Create and publish a form These calls need a `readwrite` key. 1. Create the form: ```bash curl -s "$PAMPAS/forms" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"name":"Event sign-up"}' ``` `key` (the form's address name: lower-case letters, digits and `_`, starting with a letter) comes from `name` when you leave it out; a `key` already in use is a 409. `test_mode: true` creates it in test mode. You can also pass a `definition`: anything Pampas does not recognise is removed and listed in the answer's `stripped`. Without one, the form starts empty. 2. Change the definition with `PUT /forms/{id}/definition`, sending the whole `definition` and the `revision` you last read (`definitionRevision`). If someone saved in between, the answer is 409 `revision_conflict`: read the form again and retry. The shape of a definition is the `workingDefinition` that `GET /forms/{id}` returns. 3. Publish it with `POST /forms/{id}/publish`. Publishing needs a decision on how long to keep responses: pass `{"retention": {"responseDays": 365}}` (`"responseDays": null` keeps them indefinitely), or save one in Pampas first. Without one the answer is 422 `retention_required`. `POST /forms/{id}/unpublish` closes the form to new responses. ## Invite people to fill it in * `POST /forms/{id}/recipients` adds up to 1000 people at once in `recipients`, each with `email` and an optional `name`. `auth_mode` is required: `link` or `otp` (a code by email). Optionally add `single_use`, `expires_at` and `prefill` (answers filled in in advance, by field key). Bad addresses and people already on the form are counted, not refused. Adding people sends nothing yet. * `POST /forms/{id}/reminders` sends now: it invites everyone not yet invited and reminds those who have not answered. * `GET /forms/{id}/recipients` lists them. Invitations go by email, so email must be set up on the server. See [email on the server](/self-host/email). ## Destinations Destinations (where each response is sent, such as a webhook) are set up in Pampas. The API can list them (`GET /forms/{id}/destinations`, with addresses shortened and no secrets), turn one on or off or change a Fennec destination's field mapping (`PATCH /forms/{id}/destinations/{did}` with `enabled` or `mapping` only), and read the delivery log (`GET /forms/{id}/deliveries`). ## Limits and errors * Each key may make 120 calls a minute. Deleting a response and closing a form share a stricter limit of 20 an hour. Every answer to a valid key carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers, and a 429 says how long to wait. * A body that carries a form definition may be up to 2 MB. * Errors are `application/problem+json` (RFC 9457). Problems a program can act on carry a `code`, such as `revision_conflict`, `retention_required` or `definition_invalid`. A 403 with a `read` key means the call needs `readwrite`. Agents connected through [the AI gateway](/connect/gateway) reach the same actions as tools: see [Pampas agent tools](/reference/agent-tools/pampas).