# For Google Forms — API Reference

Versioned machine API for creating Google Forms from plain text.
Base URL: `https://for-google-forms.surveysai.com/api/v1/forgoogleforms`
Machine-readable spec: [`/api/v1/forgoogleforms/openapi.json`](https://for-google-forms.surveysai.com/api/v1/forgoogleforms/openapi.json)

## Quickstart

```bash
# 1. Log in with Google at https://for-google-forms.surveysai.com/ and create
#    an API key in the dashboard (API keys section). Keys look like fgf_...

# 2. Parse / check a form (free):
curl -X POST https://for-google-forms.surveysai.com/api/v1/forgoogleforms/parse \
  -H "Authorization: Bearer fgf_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"form_text": "Customer Feedback\n*Full Name [text]\nRating [linear_scale]"}'

# 3. Create the real Google Form (billed, 10 credits; PRO plans free):
curl -X POST https://for-google-forms.surveysai.com/api/v1/forgoogleforms/forms \
  -H "Authorization: Bearer fgf_YOUR_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-op-42" \
  -d '{"form_text": "Customer Feedback\n*Full Name [text]"}'
```

## Authentication

`Authorization: Bearer fgf_...` — see [auth guide](forgoogleforms-auth-guide.md).
Scopes: `forms:read`, `forms:write`, `validate`, `credits:read`.

## Endpoints

| Method | Path | Auth / scope | Billed |
|---|---|---|---|
| GET | `/capabilities` | public | — |
| GET | `/pricing` | public | — |
| GET | `/openapi.json` | public | — |
| POST | `/parse` | `validate` | free |
| POST | `/validate` | `validate` | free; `use_llm: true` → 2 credits |
| GET | `/forms` | `forms:read` | free |
| POST | `/forms` | `forms:write` | 10 credits |
| GET | `/me` | any key | free |
| GET | `/credits/ledger` | `credits:read` | free |
| POST | `/credits/checkout` | any key | — (payment) |

All request bodies are JSON. Form input is the plain-text format described in
[`QUESTION_TYPES.md`](../QUESTION_TYPES.md) (summary at `/llms.txt`).

### POST /forms

Body: `{"form_text": "..."}`. Optional header `Idempotency-Key: <string>` —
repeated calls with the same key return the original result without creating
or charging again. Responses:

- `201` — `{status, data: {form_id, google_form_id, form_url, question_count, warnings, charged_credits}}`
- `200` — replay of a previous idempotent call (`data.replayed: true`)
- `402` — insufficient credits; body contains x402-style `accepts` array with
  top-up instructions (see [payments guide](forgoogleforms-payments-guide.md))
- `409` — `google_account_not_linked`: the key's owner must log in once via
  the web so the service can store a Google refresh token
- `422` — parse errors in `form_text` (fix and retry)
- `429` — key's daily credit budget exceeded

### Errors

All errors: `{"status": "error", "error": "<code>", "message": "..."}` with
appropriate HTTP status. `503 api_disabled` means the operator kill-switch is on.

## Rate limits

Default 120 requests/hour per API key (creation endpoints lower). Per-action
credit budgets can be set per key (`daily_credit_limit`).