API Documentation

Endpoint

POST https://api.nimblyjson.com/v1/transform

All requests go to this single endpoint. The mode parameter determines behavior.

Request Format

{
  "mode": "extract" | "risk" | "tasks" | "email",
  "text": "Your input text here...",
  "schema": { ... },     // Required for 'extract' mode only
  "options": {
    "language": "en",    // Output language (default: en)
    "strict": true,      // Reject extra fields (default: true)
    "max_output_tokens": 500
  }
}

Mode: extract

Define your own schema. Get back validated JSON matching it exactly.

// Request
{
  "mode": "extract",
  "text": "Invoice #INV-0193 Total £120.50 Date 2026-01-20",
  "schema": {
    "invoice_number": "string",
    "total": "number",
    "currency": "string",
    "date": "date"
  }
}

// Response
{
  "ok": true,
  "mode": "extract",
  "data": {
    "invoice_number": "INV-0193",
    "total": 120.5,
    "currency": "GBP",
    "date": "2026-01-20"
  },
  "meta": { "request_id": "...", "latency_ms": 245 }
}

Supported types: string, number, boolean, date (YYYY-MM-DD), array, string[], object

Mode: risk

Analyze contracts and policies for risks, obligations, and deadlines.

// Request
{
  "mode": "risk",
  "text": "This agreement may be terminated by either party with 30 days written notice. Licensee shall pay all fees within 15 days of invoice date. Late payments accrue 1.5% monthly interest."
}

// Response
{
  "ok": true,
  "mode": "risk",
  "data": {
    "risk_level": "medium",
    "summary": "Standard service agreement with termination and payment terms.",
    "obligations": ["Pay fees within 15 days of invoice"],
    "deadlines": [{"description": "Termination notice", "date": ""}],
    "red_flags": ["1.5% monthly late payment interest"],
    "recommended_actions": ["Negotiate longer payment terms", "Review termination clause"]
  }
}

Mode: tasks

Convert meeting notes into structured action items.

// Request
{
  "mode": "tasks",
  "text": "Team standup Jan 20: Sarah will finish the API docs by Friday. Mike needs to review the security audit results ASAP. Next sync on Monday."
}

// Response
{
  "ok": true,
  "mode": "tasks",
  "data": {
    "summary": "Team standup covering API docs and security audit review.",
    "action_items": [
      {"task": "Finish API docs", "owner": "Sarah", "due_date": "2026-01-24", "priority": "medium"},
      {"task": "Review security audit results", "owner": "Mike", "due_date": "", "priority": "high"}
    ],
    "next_meeting": "2026-01-27"
  }
}

Mode: email

Generate professional emails from brief descriptions.

// Request
{
  "mode": "email",
  "text": "Ask the landlord to fix the broken heating. Been waiting 2 weeks. Be polite but firm."
}

// Response
{
  "ok": true,
  "mode": "email",
  "data": {
    "subject": "Follow-up: Heating Repair Request",
    "body": "Dear [Landlord],\n\nI hope this message finds you well. I am writing to follow up on my heating repair request submitted two weeks ago...",
    "tone_notes": "Professional, polite but assertive",
    "key_points": ["Reference previous request", "State urgency", "Request timeline"]
  }
}

Authentication

Two options:

1. Via RapidAPI (recommended):

X-RapidAPI-Key: your-rapidapi-key
X-RapidAPI-Host: nimblyjson.p.rapidapi.com

2. Direct with Bearer token:

Authorization: Bearer your-api-secret

Error Responses

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing required field: text"
  },
  "meta": { "request_id": "..." }
}

Best Practices

• Keep schemas minimal — Smaller outputs are faster and more reliable
• Use specific field names — "invoice_number" beats "field1"
• Handle errors gracefully — Check ok: false before accessing data
• Cache responses — Identical inputs return cached results for 1 hour