Developers · API Reference

API Reference

Everything the v1 REST API accepts and returns. Version 1.0.0.

Base URL

https://formeze.ai/api/v1OpenAPI 3.1 spec (JSON)

Authentication

Every request needs an API key. Create keys in the dashboard under Settings → API keys. Send the key with the standard Bearer scheme; the X-API-Key header is accepted as a fallback.

curl
curl https://formeze.ai/api/v1/me \
  -H "Authorization: Bearer fmz_your_key_here"

Scopes

Keys can be restricted to a subset of operations. A key created with no scopes has full access.

fields:readRead stored fields (list, get)
fields:writeCreate, update, and delete fields
autofillRun autofill / field matching

Rate limits

Each key is limited to 60 requests per minute. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers. When the limit is exceeded, the API returns 429 with a Retry-After header. Monthly plan quotas (fields, queries, PDF scans) are enforced separately and also answer with 429.

Errors

Errors share one envelope: a human-readable error, a stable code, a requestId to quote in support requests, and optional details.

429 example
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "requestId": "req_b81f…",
  "details": { "retryAfterSeconds": 22 }
}
400VALIDATION_ERRORThe request body or parameters are invalid.
401UNAUTHORIZEDThe API key is missing, invalid, expired, or revoked.
403FORBIDDENThe key lacks the scope the endpoint requires.
404NOT_FOUNDThe resource does not exist or belongs to another account.
429RATE_LIMIT_EXCEEDEDPer-key rate limit or monthly plan quota exceeded.
GET/me

Get the authenticated account

Returns the account that owns the API key, its plan, and its monthly limits.

200 response
{
  "id": "usr_4f2a…",
  "email": "sarah@formeze.ai",
  "name": "Sarah Chen",
  "plan": "pro",
  "createdAt": "2026-03-25T12:30:00Z",
  "limits": {
    "monthlyFields": 1000,
    "monthlyQueries": 5000,
    "monthlyPdf": 50
  }
}
GET/usage

Get current billing-period usage

Current-period usage counters (fields stored, autofill queries, PDF scans) against your plan limits.

200 response
{
  "plan": "pro",
  "period": { "start": "2026-07-01T00:00:00Z", "end": "2026-08-01T00:00:00Z" },
  "fields":  { "used": 214, "limit": 1000 },
  "queries": { "used": 1288, "limit": 5000 },
  "pdf":     { "used": 6, "limit": 50 }
}
GET/fields

List stored fields

Paginated list of the account's stored fields.

Requires scope: fields:read

Query parameters

pageintegerPage number, starting at 1. Default 1.
limitintegerItems per page, 1–100. Default 50.
searchstringFilter by label/value text.
domainstringFilter by source domain.
sortstringrecent | label | usage. Default recent.
200 response
{
  "fields": [
    {
      "id": "fld_9c31…",
      "label": "Legal name",
      "value": "Sarah M. Chen",
      "sourceDomain": "irs.gov",
      "sourceType": "PDF_FORM",
      "usageCount": 12,
      "lastUsedAt": "2026-06-28T09:14:00Z",
      "createdAt": "2026-04-02T17:40:00Z"
    }
  ],
  "total": 214,
  "page": 1,
  "totalPages": 5
}
POST/fields

Create one or more fields

Stores up to 100 fields in one call. Duplicate label/value pairs are detected and skipped.

Requires scope: fields:write

Request body

fieldsarray (required)1–100 items of { label, value, sourceUrl?, sourceType?, fieldType? }. label ≤ 500 chars, value ≤ 10,000 chars.
sessionIduuidOptional idempotency/session marker.
200 response
{
  "stored": 3,
  "duplicates": 1,
  "fieldIds": ["fld_9c31…", "fld_9c32…", "fld_9c33…"]
}
GET/fields/{id}

Get a field

Returns a single stored field by id.

Requires scope: fields:read

PATCH/fields/{id}

Update a field's value

Replaces the stored value. The field is re-embedded for matching.

Requires scope: fields:write

Request body

valuestring (required)The new value.
DELETE/fields/{id}

Delete a field

Permanently removes the field and its embedding.

Requires scope: fields:write

200 response
{ "success": true, "deletedId": "fld_9c31…" }
POST/autofill

Get autofill suggestions for form labels

Matches up to 50 form labels against the account's stored fields using self-hosted semantic search, and returns ranked suggestions with confidence levels.

Requires scope: autofill

Request body

labelsarray (required)1–50 form field labels to match.
urlstring (required)URL of the page being filled.
topKintegerMatches per label, 1–10. Default 3.
minScorenumberMinimum similarity 0–1. Default 0.6.
fastbooleanSkip composite/AI matching for lower latency. Default false.
200 response
{
  "suggestions": [
    {
      "queryLabel": "Your email address",
      "matches": [
        {
          "fieldId": "fld_9c31…",
          "storedLabel": "Email",
          "value": "sarah@formeze.ai",
          "score": 0.91,
          "confidence": "high",
          "sourceDomain": "formeze.ai"
        }
      ]
    }
  ],
  "historyId": "hist_77b0…",
  "stats": { "queriedFields": 1, "matchedFields": 1, "totalMatches": 1 }
}

Build with it

Generate a client from the live spec.

Get an API keyopenapi.json