Forms API

The Forms API is available under /apis/v1/forms and requires a Ration bearer token. Forms may be visible through ownership or a Ration share grant.

Authorization: Bearer <ration_access_token>
Content-Type: application/json

Form model

Form responses are wrapped in a form object. A form includes its id, title, description, sections/questions, status and acceptance state, author data, sharing/access configuration, and builder mechanics such as conditional logic and question settings.

Question and section definitions are sent within the form body. Keep question IDs stable when updating an existing form so submitted answers and analytics continue to align with the intended fields.

Authoring CRUD

GET /apis/v1/forms/presets returns the available detailed-builder presets, each with key, label, and summary.

POST /apis/v1/forms/draft creates a saved starter draft. Send method: "detailed" with a preset, or method: "assisted" with a description. Optional audience: "external" initializes external/link access. The response contains form, note, and generated.

Method	Path	Description
GET	/apis/v1/forms	List visible forms in a forms array.
POST	/apis/v1/forms	Create a form and return 201 with a form object.
GET	/apis/v1/forms/:id	Read a form. Shared forms also return shared: true.
PATCH, PUT	/apis/v1/forms/:id	Update the builder definition and return the form.
DELETE	/apis/v1/forms/:id	Delete a form and return it.

Example minimal form:

{
  "title": "Product feedback",
  "description": "Tell us what you think.",
  "sections": [
    {
      "id": "section-1",
      "title": "Feedback",
      "questions": [
        { "id": "q1", "type": "short_text", "label": "What worked well?", "required": true }
      ]
    }
  ]
}

Publishing lifecycle

Method	Path	Request	Response
POST	/:id/publish	—	Published form.
POST	/:id/archive	—	Archived form.
POST	/:id/unarchive	—	Restored form.
POST	/:id/accepting	accepting Boolean.	Updated form.

Paths in this table are relative to /apis/v1/forms. Publishing makes a form available according to its configured access mode; archiving stops its normal lifecycle. accepting: false closes response collection without deleting the form.

Submit and review responses

Submit as an authenticated user

POST /apis/v1/forms/:id/submit

{
  "answers": {
    "q1": "The search workflow was very clear."
  },
  "device_type": "mobile",
  "locale": "en"
}

Field	Type	Required	Description
answers	Object	Yes	Keys are form question IDs; values must satisfy their question type and validation.
device_type	String	No	Responding device classification.
locale	String	No	Respondent locale.
metadata	Object	No	Additional client metadata.

Ration derives respondent ID, name, email, and source from the bearer-authenticated user. Success returns 201 with a response object; validation errors return 422 with error: "validation_failed" and an errors object.

Read responses and analytics

Method	Path	Response
GET	/:id/responses	Responses array; use supported list query parameters for pagination/filtering.
GET	/:id/responses/:response_id	One response object.
GET	/:id/analytics	Analytics object aggregated for the form questions.

These paths are relative to /apis/v1/forms and require form-owner access.

Export responses

Method	Path	Result
GET	/:id/export.csv	CSV attachment named responses-<form-id>.csv.
GET	/:id/export.xlsx	XLSX attachment named responses-<form-id>.xlsx.

Paths are relative to /apis/v1/forms.

Sharing, attachments, and report builder

Form sharing and uploaded answers

Method	Path	Request / response
POST	/:id/share	Optional expires_at; creates a share link and returns the form.
DELETE	/:id/share	Revokes the form share link and returns the form.
POST	/:id/share/regenerate	Replaces the form share link and returns the form.
POST	/:id/attachments	Multipart request with required file; returns 201 and a file descriptor.

The file descriptor contains secure_id, filename, content_type, size, and url. The hard attachment limit is 25,000,000 bytes; per-question upload limits may be smaller.

Saved reports

The visual report builder is now available to API clients. Its persisted report spec is the definition behind the draggable report layout.

Method	Path	Request / response
GET	/:id/report_snapshot	Current materialized per-question snapshot, or snapshot: null.
GET, POST	/:id/reports	List reports, or create one with required name and spec.
GET, PUT, DELETE	/:id/reports/:report_id	Read, update (name, spec), or delete a saved report.
POST	/:id/reports/:report_id/share	Set read-only viewers with emails or shared_with.
GET	/:id/reports/:report_id/share	List report viewers in shared_with.
POST	/:id/report.xlsx	Export client-computed report sheets to XLSX; optional name.

Paths are relative to /apis/v1/forms.

Reports shared with the caller

Method	Path	Result
GET	/apis/v1/reports/shared	Reports shared read-only with the caller.
GET	/apis/v1/reports/shared/:report_id	Saved report specification.
GET	/apis/v1/reports/shared/:report_id/responses	Response data needed to render the shared report.
GET	/apis/v1/reports/shared/:report_id/form	Read-only form definition for the shared report.

Errors

Status	Meaning
401	Missing or invalid bearer authentication.
404	Form or response not found, or not visible to the caller.
422	Invalid form definition, validation failure, invalid ID, no changes, or an unavailable lifecycle operation.