Application backup & restore

Encrypted ZIP of code, templates, trained flows, local/S3 training caches, users and configuration. Order outputs are excluded. Keep the password separately; it cannot be recovered.

Restore requires an idle queue and signs users out. Code is staged for a Docker rebuild; the S3 library is staged for review and publishing. Only tagged order outputs expire after 120 days; trained flows and caches are excluded.

Credentials

Saved values are encrypted on the server and never sent back to your browser. Blank fields keep the saved value. Task roles are used when keys are absent.

Team access

Viewers can inspect results and read-only VNC sessions. Operators can create, retry, and cancel orders. Administrators also manage configuration and users.

Train, test or repair: Assessor and Taxes

Save your draft first. Start with a known property. No-AI tests must find and verify a PDF for both APN and address on the exact saved draft. These test runs use AI only when you check the box below. Choose Assessor only, Taxes only, or Assessor and Taxes. For address training, edit the Taxes · Address steps; for APN training, edit Taxes · APN / account. Tax tests require a configured tax URL. Successful AI training saves its proposal as a draft automatically. Rerun with AI unchecked to verify replay before activation. Concurrent edits are preserved and reported as conflicts.

Bulk county setup and training

Add counties from any state, then upload known properties to train or test them. Use two-letter state codes. Imports create drafts and never overwrite existing counties.

County columns: state, county, site_url, tax_url. For a tax-only county, supply tax_url and leave site_url blank. Test columns use search_type = apn or address, document_scope = assessor_only, tax_only or both, and training_use_ai = true or false. Use a unique order_number per case. Keep APNs as text to preserve leading zeros. CSV values containing commas must be quoted.

S3 workflow library

Publish saves all active website versions and a manifest. Fetch restores that manifest to this app; new orders use the restored local snapshot. Running orders keep their existing version.

Local packaged flows are not in your bucket until Publish succeeds. Drafts are kept locally until tested and activated. Store the same worker image version alongside your workflow backup because Python hooks ship in the image.

Keys access this team's orders. Read-only keys retrieve results; submit keys can also start work. Keys cannot change settings, manage users or start AI training. Use HTTPS when hosting remotely.

Start an order, then fetch the result

1. Create a key with submit access and send it as Authorization: Bearer YOUR_API_KEY.
2. POST a single order to /api/v1/orders or an {"orders": [...]} batch to /api/v1/orders/bulk. Both return HTTP 202 with job IDs and status/result URLs.
3. Poll the returned status URL until terminal is true. GET the result URL for extracted fields, tables and file links. A terminal status can also be a failure or business-rule exception.

Single-order JSON

{
  "order_number": "API-001",
  "county": "Harris",
  "apn": "0162760200009",
  "address": "6710 Utah St, Houston, TX 77091",
  "owners": "HOUSTON LAND BANK",
  "search_type": "auto",
  "execution": "local",
  "vnc_mode": "read_only"
}

Use "execution": "fargate" after configuring AWS. Add an Idempotency-Key header to submission requests so retrying the same request with the same key returns the original jobs. Reusing it for different inputs returns HTTP 409.

S3 and extracted data

Enable S3 delivery in Connections & settings. Submit to /api/v1/orders?require_s3=true to reject orders when uploads are disabled. After a successful upload, files["Assessor.pdf"].s3_url and files["property.json"].s3_url contain expiring links. Request the result again to refresh them.

property.fields contains the basic information and legal description. property.tables contains published sales/deed, building, land and other tables. Missing fields remain null. delivery.status distinguishes uploaded, pending, not uploaded and upload failures.

Canonical files remain titlehunter/<OrderNumber>/Assessor.pdf and property.json. Signed URLs use the selected attempt's immutable files. Local download_url paths require the same Bearer key; S3 signed URLs work until expiry. Look up the latest attempt by /api/v1/orders/by-number/<OrderNumber>.

Your first order

1. Connections: choose Local Docker settings. Enable S3 delivery after saving AWS credentials or configuring a task role, then test the connection.
2. New order: enter a unique order number, county, address and/or APN. Use automatic mode for APN → address fallback. Keep street directions and apartment/unit numbers.
3. Owners: separate alternative owners with semicolons. “Last, First” removes name-order ambiguity. For a company, enter its full registered name. One matching owner is enough.
4. Live browser: open a running order → Live browser → Connect. Read-only is enforced by the worker. Interactive mode must be allowed in settings before starting the order.
5. Delivery: review the property fields and tables. Download the PDF or copy its expiring S3 link. Files go to titlehunter/<OrderNumber>/Assessor.pdf and property.json when that bucket is configured.

What self-healing does

Automatic repair of existing flows is optional in Connections & settings and uses the same call budget. Normal orders use saved selectors, alternate selectors, readiness waits, one transient navigation retry, APN-to-address fallback and a street-direction retry where needed. Saved flows normally run without AI. New, untrained sites can use the configured AI provider within the configured call budget. CAPTCHA handling stays in the existing Camoufox handler; a challenge that does not clear is reported for review.

A changed selector produces diagnostics. An administrator opens Website Studio, edits the step or adds guidance, and explicitly starts AI training if needed. Review its proposed selectors, save the draft, pass no-AI APN and address tests, activate, and publish to S3. No-AI Studio verification never enables AI. Automatic training for new sites is recorded in the activity log and AI call count.

When a search stops

• Business rule exception: matching owners identify different parcels/accounts or addresses. Review the intended property. Duplicate rows with the same parcel and situs use the first matching row.
• Ambiguous: add the correct owner, unit or parcel ID. Multiple valid properties must be resolved before delivery.
• No records: check the county, parcel ID, street direction and search mode.
• Selector / workflow failed: download the screenshot, steps and developer handoff from Activity & diagnostics. Update the relevant step in Website Studio.
• Needs human / HTTP 403: the county blocked the session. Inspect Live browser while it is running and retry when access is available. Selector training does not fix access blocks.
• Upload failed: the local result is retained. Check AWS access and bucket settings, then retry as a new attempt.

Repair guidance: assessor and taxes

On a paused training order, use Shared guidance for both websites, Assessor corrections for assessment steps, and Tax corrections for tax steps. Select Assessor and Taxes to retest the complete flow. You may also use Assessor:, Taxes:, and Shared: headings. Describe the wrong action, the correct visible control and the expected result. Corrections invalidate affected draft selectors; activation still requires APN and address tests without AI.

Example: Assessor: choose Residential and search the parcel without dashes. Taxes: open Payment History after selecting the verified property, then collect the latest published year. Guidance is not arbitrary executable code. Missing extraction formats or complex new page sequences can still require a developer.

Technology in plain language

This is a custom Python automation engine with bounded AI learning. FastAPI serves Studio, SQLite stores orders and flow versions, Camoufox with Playwright operates websites, Gemini or OpenAI learns browser actions, and Python validates records and PDFs. Stagehand is not used. Docker runs local workers; S3 and Fargate are optional configured integrations. Training saves a workflow; it does not fine-tune the AI model.

Developer guide

Common steps: do + action + selector + value; wait_for for an element; pick_result to match the property; download_pdf after verified detail. Values use placeholders such as {apn}, {house_number}, {street_search_name}, and {street_no_suffix_direction}. AI guidance explains only the broken selector or workflow step. Keep result matching and required input checks enabled.

For custom vendor logic, add a reviewed function under site_hooks/, reference it in county YAML, add regression coverage, and rebuild both Docker images. The website editor does not execute uploaded scripts.