API quickstart

One endpoint in, typed fields out: POST /api/v1/extract returns every field as {value, type, confidence, p_null} plus a document-level needs_review flag. Three steps below — the curl example runs as-is once you have a key.

1 · Get an API key

curl -X POST https://extract.redsugartree.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

curl -X POST https://extract.redsugartree.com/api/v1/reveal-key \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

2 · Call the extract endpoint

curl -X POST https://extract.redsugartree.com/api/v1/extract \
  -H "Authorization: Bearer eex_free_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"doc_type":"invoice","input":{"text":"INVOICE INV-2291\nVendor: Acme Ltd\nInvoice date: 2026-11-01\nDue date: 2026-11-30\nCurrency: USD\nLine items:\n- Design retainer (Nov 2026): 1000.00\n- Extra revisions: 80.00\nTax: 0.00\nTotal due: 1080.00"}}'

{
  "doc_type": "invoice",
  "data": {
    "total":       { "value": 1080.00, "type": "number", "confidence": 0.98, "p_null": 0.01 },
    "tax":         { "value": 0.00,    "type": "number", "confidence": 0.95, "p_null": 0.04 },
    "currency":    { "value": "USD",   "type": "text",   "confidence": 0.99, "p_null": 0.00 },
    "vendor":      { "value": "Acme Ltd", "type": "text", "confidence": 0.99, "p_null": 0.00 },
    "invoice_date":{ "value": "2026-11-01", "type": "date", "confidence": 0.97, "p_null": 0.02 },
    "due_date":    { "value": "2026-11-30", "type": "date", "confidence": 0.96, "p_null": 0.03 },
    "line_items":  { "value": [ { "description": "Design retainer (Nov 2026)", "amount": 1000.00 },
                                { "description": "Extra revisions", "amount": 80.00 } ],
                     "type": "list", "confidence": 0.94, "p_null": 0.05 }
  },
  "needs_review": false,
  "truncated": false,
  "usage": { "tokens_in": 655, "cost_usd": 0.0000655 },
  "generated_by": "ai"
}

Request reference

Input rules

• Pick exactly one input kind: text (any plain string), image_b64 (PNG / JPEG / WebP, base64), or file_url (http/https URL — plain text, images, and PDFs with a text layer).
• Request body max 2 MB — larger → 422 input_too_large.
• text longer than 50,000 chars is truncated and flagged "truncated": true (never an error).
• file_url must be http/https; fetched server-side with a 10s timeout. Images (jpg/png/webp) go through vision; PDF is supported only when it has an extractable text layer — the text is extracted server-side and run through the text path. Scanned / image-only PDFs → 422 unsupported_input (extract the text client-side and send it as text).
• Missing fields are returned as value: null with a high p_null — absence is information, not an error.
• Invoice totals are reconciled against line_items in our code (1% tolerance); a mismatch only sets needs_review, never fails the request.

Rate limits

10 requests/second sustained per key with a burst of 20. Over the limit → 429 rate_limited with a Retry-After header. Limits are enforced per key; different keys never affect each other. A free-tier edge firewall rule (Bot Fight Mode + WAF rate limiting on /api/*) backs this up.

Error codes

Every error uses the same body: {"error":{"code":"…","message":"…"}}.

422 sub-codes

Built-in schemas

Custom schema example

doc_type=custom with a two-field schema — the response contains exactly the fields you declare:

curl -X POST https://extract.redsugartree.com/api/v1/extract \
  -H "Authorization: Bearer eex_free_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "custom",
    "schema": {
      "fields": [
        { "name": "po_number",  "type": "text",   "required": true, "hint": "Purchase order number" },
        { "name": "amount_due", "type": "number", "required": true, "hint": "Total amount due" }
      ]
    },
    "input": { "text": "PO-4471\nVendor: Acme Ltd\nAmount due: 2400.00 USD" }
  }'

Response shape (same contract as the built-ins, only your two fields):

{
  "doc_type": "custom",
  "data": {
    "po_number":  { "value": "PO-4471", "type": "text",   "confidence": 0.97, "p_null": 0.02 },
    "amount_due": { "value": 2400.00,   "type": "number", "confidence": 0.95, "p_null": 0.03 }
  },
  "needs_review": false,
  "truncated": false,
  "usage": { "tokens_in": 128, "cost_usd": 0.0000128 },
  "generated_by": "ai"
}

Pricing

Only successful 200 responses consume quota. 4xx/5xx never do. Running out → 402 quota_exceeded, never a silent downgrade. All tiers include confidence + p_null on every field.

All endpoints

Questions? support@redsugartree.com · Back to the homepage

Terms of Service · Privacy policy · Refund policy · Contact