HTTP API

{
  "kind": "user|token",
  "user_id": 1,
  "email": "[email protected]",
  "display_name": "You (Admin)",
  "instance_host": "suchi.example.com",
  "build_version": "v0.1.0-beta.2",
  "build_revision": "1234567890ab",
  "role": "admin|member",
  "authn_by": "local-auth|oidc",
  "avatar_url": "/api/users/1/avatar?v=<sha256>",
  "capabilities": ["mailboxes"],
  "scopes": ["documents:read", "documents:write"]
}

{ "display_name": "Ritesh S." }

GET  /api/demo/mode              → 200 {"enabled": true|false, "next_reset_unix": <int>?}
POST /api/demo/session           → 200 {"kind":"anon", "token":"demoanon.<...>", "expires_unix":<int>, "header":"X-Suchi-Demo-Token"}
POST /api/demo/session/upgrade   → 200 {"kind":"scratch"} + HttpOnly session cookie

{
  "count": 42,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 91,
      "title": "March electricity bill",
      "mime_type": "application/pdf",
      "original_size": 16841,
      "jd_category_id": 31,
      "jd_category_code": 31,
      "jd_category_name": "Utilities",
      "jd_area_name": "Home",
      "sensitivity": "",
      "thumb_sha": "ab12...",
      "split_origin_id": 84,
      "split_index": 1,
      "created_at": 1746662400,
      "updated_at": 1746662400,
      "tags": ["utilities", "bescom"],
      "correspondents": ["BESCOM"]
    }
  ]
}

{
  "id": 1,
  "owner_id": 1,
  "title": "Electricity bill March 2026",
  "content": "Electricity bill for March 2026...",
  "content_source": "server",
  "device_content_confidence": 0.86,
  "device_ocr_language": "en_US",
  "device_content_received_at": 1793494800,
  "original_blob": "sha256hex...",
  "original_size": 16841,
  "archive_blob": "sha256hex...",
  "archive_size": 62114,
  "mime_type": "application/pdf",
  "jd_category_id": 17,
  "jd_category_code": 31,
  "jd_category_name": "Utilities",
  "jd_area_name": "Home",
  "created_at": 1793491200,
  "added_at": 1793494800,
  "updated_at": 1793491200,
  "source_mtime": 1793494700,
  "sources": [
    {
      "kind": "mailbox",
      "label": "Personal Outlook",
      "detail": "[email protected] / INBOX",
      "observed_at": 1793494800
    }
  ],
  "tags": ["utilities", "electricity"],
  "correspondents": [{ "id": 3, "name": "BESCOM", "role": "sender" }],
  "languages": "de,en",
  "languages_locked": false
}

{
  "results": [
    {
      "id": 5,
      "title": "Lease 2024",
      "sha256": "...",
      "size": 12345,
      "mime_type": "application/pdf",
      "created_at": 1785783054,
      "is_head": false
    },
    {
      "id": 8,
      "title": "Lease 2026",
      "sha256": "...",
      "size": 12890,
      "mime_type": "application/pdf",
      "created_at": 1785783100,
      "previous_version_id": 5,
      "is_head": true
    }
  ]
}

{
  "documents": [1, 42, 91],
  "method": "set_jd_category",
  "parameters": { "jd_category_id": 22 }
}

{
  "method": "set_jd_category",
  "total": 3,
  "applied": 2,
  "results": [
    { "id": 1, "ok": true },
    { "id": 42, "ok": true },
    { "id": 91, "ok": false, "code": "forbidden" }
  ]
}

{
  "results": [
    {
      "id": 42,
      "title": "statement.pdf",
      "original_blob": "sha256hex...",
      "original_size": 65432,
      "created_at": 1785783054,
      "mime_type": "application/pdf"
    }
  ]
}

{
  "doc_ids": [42, 43, 44],
  "password": "hunter2",
  "remember": true,
  "label": "Bank X 2026"
}

{
  "results": [
    { "doc_id": 42, "ok": true },
    { "doc_id": 43, "ok": true },
    { "doc_id": 44, "ok": false, "reason": "bad_password" }
  ]
}

{
  "results": [
    {
      "id": 91,
      "title": "April electricity bill",
      "mime_type": "application/pdf",
      "jd_category_id": 31,
      "created_at": 1746662400,
      "score": 8.42
    },
    {
      "id": 108,
      "title": "March electricity bill",
      "mime_type": "application/pdf",
      "jd_category_id": 31,
      "created_at": 1744070400,
      "score": 7.11
    }
  ],
  "method": "fts",
  "matched_on_title_only": false
}

{
  "languages": [
    { "code": "en", "count": 812 },
    { "code": "de", "count": 143 },
    { "code": "kn", "count": 27 }
  ]
}

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 4,
      "code": 22,
      "name": "Tax",
      "description": "annual filings",
      "area_code": 20,
      "area_name": "Money",
      "system": false
    }
  ]
}

{
  "count": 12,
  "next": "/api/tags/?page=2&ordering=-name",
  "previous": "",
  "results": [
    /* TagView objects */
  ]
}

{
  "results": [
    { "id": 42, "name": "HDFC Bank", "role": "sender" },
    { "id": 87, "name": "Alice Sharma", "role": "recipient" }
  ]
}

[
  {
    "id": "solo",
    "name": "Solo",
    "description": "Personal filing, no business.",
    "areas": [
      { "code": 10, "name": "Life",  "category_count": 6 },
      { "code": 20, "name": "Money", "category_count": 4 }
    ]
  },
  ...
]

{
  "content": "format = \"suchi-taxonomy/v1\"\n...",
  "format": "toml",
  "apply": false,
  "skip_seeds": false,
  "remaps": { "12": 15 }
}

{
  "documents_total": 4182,
  "trash_count": 12,
  "inbox_count": 3,
  "inbox_category_id": 49,
  "pending_approvals": 2,
  "pending_intelligence": 4,
  "dead_jobs": 1,
  "ingested_7d": 57
}

{
  "results": [
    {
      "id": 4182,
      "kind": "document.ingested",
      "created_at": 1754441523,
      "doc_id": 91,
      "summary": "Ingested March rent"
    },
    {
      "id": 4183,
      "kind": "job.dead",
      "created_at": 1754441599,
      "summary": "A background job gave up after retries"
    }
  ],
  "latest_id": 4183
}

{
  "counts": {
    "pending": 0,
    "running": 0,
    "done": 12,
    "dead": 1,
    "approvals_open": 2
  },
  "results": [
    {
      "id": 42,
      "kind": "post-ingest",
      "state": "dead",
      "attempts": 5,
      "doc_id": 17,
      "last_error": "ocrmypdf: page 3 timeout",
      "created_at": 1785779486,
      "updated_at": 1785779523,
      "next_run_at": 1785779486
    }
  ],
  "approval_tasks": [
    {
      "id": 9,
      "run_id": 3,
      "approval_id": 1,
      "approval_name": "invoice-approval",
      "doc_id": 42,
      "doc_title": "August bank statement.pdf",
      "doc_jd_category_id": 8,
      "doc_jd_category_code": 24,
      "doc_jd_category_name": "Receipts",
      "doc_has_thumbnail": true,
      "state_key": "review",
      "assignee": "user:5",
      "prompt": "Approve invoice?",
      "choices": ["approve", "reject"],
      "status": "open",
      "deadline_at": 1785782400,
      "created_at": 1785779486
    }
  ]
}

{
  "doc_ids": [42, 91, 108],
  "label": "Everything for the accountant",
  "password": "optional",
  "expires_in_sec": 604800
}

{
  "token": "<hex>",
  "email": "[email protected]",
  "display_name": "You (Admin)",
  "password": "..."
}

{
  "started_at": 1789257600,
  "intent": "household",
  "recommended_preset": "household",
  "current_preset": "household",
  "filing_tree_chosen": true
}

{ "enabled": true, "provider": "localhost", "local": true }

{
  "question": "When does it renew?",
  "history": [
    { "role": "user", "content": "Which office lease applies?" },
    { "role": "assistant", "content": "The Indiranagar office lease [1]." }
  ],
  "context_source_ids": [17],
  "scope": {
    "query": "tag:lease",
    "document_ids": [],
    "jd_category_id": 0,
    "sensitivity": "internal",
    "document_type_id": 4,
    "tag_ids": [8],
    "correspondent_ids": [12],
    "created_at_gte": 1788134400,
    "created_at_lte": 1790726399,
    "language": "en"
  },
  "include_sensitive": false
}

{
  "answer": "The lease renews on September 1, 2026 [1].",
  "citations": [1],
  "grounded": true,
  "sources": [
    {
      "id": 17,
      "title": "Office lease agreement",
      "snippet": "The renewal date is September 1 …",
      "sensitivity": "internal",
      "intelligence": [
        {
          "type": "date",
          "role": "renewal",
          "value": { "date": "2026-09-01", "precision": "day" },
          "evidence": "The renewal date is September 1, 2026."
        }
      ]
    }
  ],
  "intelligence": {
    "accepted": { "date": 1 },
    "pending": {}
  }
}

{ "document_ids": [17, 28], "types": ["date"] }

{ "candidate_ids": [71, 72], "decision": "accepted" }

{
  "enabled": true,
  "active": true,
  "endpoint_url": "http://127.0.0.1:11434/v1",
  "model": "qwen2.5:7b",
  "egress_ack": false,
  "has_api_key": false,
  "confidence_threshold": 0.7,
  "date_auto_apply": true,
  "archive_enabled": true,
  "archive_auto_threshold": 0.9,
  "archive_review_threshold": 0.5,
  "research_context_mode": "balanced"
}

{ "research_context_mode": "detailed" }

{ "research_context_mode": "detailed" }

{
  "ok": true,
  "message": "Classifier responded with a valid result.",
  "result": {
    "title": "Synthetic utility bill",
    "correspondent": "Example Energy",
    "tags": ["utility"],
    "jd_category": 30,
    "confidence": 0.86,
    "language": "en",
    "elapsed_ms": 218
  }
}

{
  "id": 4,
  "name": "Work Outlook",
  "owner_id": 2,
  "provider": "microsoft",
  "host": "outlook.office365.com",
  "port": 993,
  "use_tls": true,
  "tls_ca_file": "",
  "folder": "INBOX",
  "processed_folder": "",
  "poll_interval_min": 5,
  "auth_method": "xoauth2",
  "username": "[email protected]",
  "oauth_account_id": "[email protected]",
  "intake_policy": {
    "rules": [
      {
        "selection": "files",
        "content": "files_only"
      },
      {
        "selection": "matching",
        "content": "email_and_files",
        "from": "[email protected], @invoice.stripe.com",
        "recipients": "[email protected]",
        "subject_terms": "invoice, statement",
        "attachment_names": "*.pdf, invoice-*"
      }
    ]
  },
  "sync_since": 1786681757,
  "enabled": true,
  "mark_seen": false,
  "last_uid_seen": 4127,
  "uidvalidity_seen": 991,
  "last_sync_at": 1786682662,
  "last_error": "",
  "created_at": 1785558600,
  "updated_at": 1786682662
}

{
  "accounts": [
    /* Account rows as above */
  ],
  "capabilities": {
    "microsoft_oauth": {
      "ready": true,
      "reason": ""
    }
  }
}

{ "ok": true,  "message": "Connected — mailbox reachable." }
{ "ok": false, "message": "login: 535 Authentication failed" }

{
  "intake_policy": {
    "rules": [
      {
        "selection": "files",
        "content": "files_only"
      },
      {
        "selection": "matching",
        "content": "email_and_files",
        "subject_terms": "distribution advice"
      }
    ]
  }
}

{
  "inspected": 18,
  "matched": 4,
  "samples": [
    {
      "from": "[email protected]",
      "subject": "August invoice",
      "attachments": ["invoice-august.pdf"]
    }
  ]
}

{ "provider": "microsoft" }

{
  "flow_handle": "b6d3…",
  "user_code": "GK7X-4H9L",
  "verification_url": "https://microsoft.com/devicelogin",
  "expires_at": 1786682962,
  "message": "Open the URL in any browser and enter the code."
}

{ "flow_handle": "b6d3…", "account_id": 4 }

{ "status": "pending" }

{
  "ok": true,
  "username": "[email protected]",
  "oauth_account_id": "[email protected]"
}

{
  "ok": true,
  "username": "[email protected]",
  "oauth_account_id": "[email protected]",
  "sealed_secret_b64": "<base64 actor/system-bound creation handoff>"
}

{ "error": "human message", "code": "snake_case_kind" }