API examples

These examples all use the same rules:

Base URL: https://formspring.io/api/v1
Auth header: Authorization: Bearer <token>
Tokens are ability-scoped. A read-only example needs forms:read; a workflow that edits submissions also needs submissions:write.
The REST API and MCP server use the same token abilities, so the permission model is identical whether code or an agent makes the call.

JavaScript

List forms, then fetch the newest inbox submissions for the first form. Required abilities: forms:read, submissions:read.

const token = process.env.FORMSPRING_TOKEN;
const baseUrl = 'https://formspring.io/api/v1';

async function api(path, options = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/json',
      'Content-Type': 'application/json',
      ...(options.headers ?? {}),
    },
  });

  if (!response.ok) {
    throw new Error(`${response.status} ${await response.text()}`);
  }

  return response.json();
}

const forms = await api('/forms?per_page=10');
const firstForm = forms.data[0];

if (firstForm) {
  const submissions = await api(`/forms/${firstForm.id}/submissions?folder=inbox&per_page=5`);
  console.log(submissions.data);
}

Python

Mark a submission as spam after your own review queue decides it should be hidden. Required abilities: submissions:read, submissions:write.

python

import os
import requests

TOKEN = os.environ["FORMSPRING_TOKEN"]
BASE_URL = "https://formspring.io/api/v1"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {TOKEN}",
    "Accept": "application/json",
    "Content-Type": "application/json",
})

form_id = "frm_01H..."
submission_id = "subm_01H..."

response = session.put(
    f"{BASE_URL}/forms/{form_id}/submissions/{submission_id}",
    json={"status": "spam"},
    timeout=10,
)
response.raise_for_status()

print(response.json()["data"])

Go

Create a webhook for a form and save the one-time signing secret. Required ability: webhooks:write.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	token := os.Getenv("FORMSPRING_TOKEN")
	formID := "frm_01H..."

	body, _ := json.Marshal(map[string]any{
		"label":    "Production webhook",
		"provider": "webhook",
		"url":      "https://example.com/formspring",
	})

	req, _ := http.NewRequest(
		http.MethodPost,
		"https://formspring.io/api/v1/forms/"+formID+"/webhooks",
		bytes.NewReader(body),
	)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	if res.StatusCode >= 300 {
		panic(res.Status)
	}

	var payload struct {
		Secret string `json:"secret"`
	}
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	fmt.Println("Save this once-only webhook secret:", payload.Secret)
}

Handling permission failures

403 means the token authenticated but does not carry the required ability. Check the reference table for the endpoint, then mint a new token with the smallest ability set that covers the workflow.

402 means the current team plan does not include the API feature. Upgrade in Billing, then retry with the same token.

For full endpoint shapes, use the OpenAPI spec, the interactive API explorer, or the reference pages for forms, submissions, webhooks, billing, AI insights, and tokens.