# REST API reference

Each LUCA agent site serves the same routes.
The host selects the product view.
The API routes are public. Only the landing page uses HTTP Basic Auth.
The Worker returns JSON in UTF-8.
Use HTTPS in production.

| Method | Route | Result |
| --- | --- | --- |
| GET | `/api/v1/overview` | Product topics, source links, and official next steps |
| GET | `/api/v1/knowledge?q=...` | Ranked product facts with source links |
| GET | `/api/v1/answer?q=...` | Short answer from reviewed facts with source links |
| GET | `/api/v1/next-steps?goal=...` | Official sign up and contact paths |
| GET | `/api/v1/paths` | Compare bill payment, supplier, and credit discovery paths |
| GET | `/api/v1/topics/{id}` | One sourced topic with its review state |
| GET | `/api/v1/conflicts` | Published facts that need LUCA review |
| POST | `/api/v1/assess` | A nonbinding starting point |
| POST | `/api/v1/event` | Count an allowed page action without personal data |
| GET | `/openapi.json` | OpenAPI 3.1 description |

## Hosts and limits

| Product | Intended live host |
| --- | --- |
| LUCA Pay preview | `https://luca-pay-agents-preview.pages.dev` |
| LUCA Plus preview | `https://luca-plus-agents-preview.pages.dev` |

The intended product hosts need DNS setup before use.
All `/api/*` and `/mcp` calls share a 100-request-per-client-IP limit in each fixed minute. The Cloudflare edge supplies the client IP. The 101st call returns HTTP 429 with `Retry-After`. A missing counter binding or client IP returns HTTP 503. The limit can affect users who share one public IP.
The search query has a 300 character limit.
The Worker has an 8 KiB JSON body limit for normal requests.
MCP has a 16 KiB JSON body limit.
The event route has a 1 KiB JSON body limit.

## Search and answer

Use `GET /api/v1/knowledge?q=fees` to get ranked topic records.
Each record gives an ID, scope, review state, check date, source URLs, and score.
An empty result means that the reviewed corpus has no match.

Use `GET /api/v1/answer?q=How%20do%20I%20sign%20up` for a short answer from the top match.
It includes official sources, review state, check date, and sign-up and contact URLs.
It does not call a language model. Check current official text before a financial decision.

## Readiness guide

`POST /api/v1/assess` accepts this JSON:

```json
{
  "goal": "pay_bills",
  "active_abn": "yes",
  "gst_registered": "yes",
  "accounting": "xero"
}
```

`goal` accepts `pay_bills`, `get_paid`, or `explore_credit`.
The other answers accept `unknown` when the person does not know.
The route rejects other fields and stores no answer.
The response gives `result`, `answers`, `notes`, `limitation`, `signup_url`, `contact_url`, and `sources`.

| Result | Meaning |
| --- | --- |
| `published_requirements_match` | The person reports an ABN and GST registration. LUCA still decides approval. |
| `published_requirement_missing` | One published requirement is missing for a bill payer. |
| `needs_discussion` | The answers need a product or sales discussion. |

Never use this result as an eligibility, credit, or cost decision.

## Official next steps

Use `GET /api/v1/next-steps?goal=pay_bills` for task steps.
The route accepts `pay_bills`, `get_paid`, or `explore_credit`.
The response gives a goal, step list, and official signup and contact URLs.

`GET /sign-up/` sends the visitor to LUCA's official sign-up page.
`GET /contact/` sends the visitor to LUCA's official contact page.
Both routes count the click without collecting form data.

## Event counts

`POST /api/v1/event` accepts one JSON `event` value.
Allowed values are `signup_click`, `contact_click`, `brief_open`, `docs_open`, `cli_download`, and `skill_download`, and `prompt_copy`.
The route returns HTTP 204 after it accepts a value.
It does not prove that a signup or contact action succeeded.
The public route needs bot controls before traffic reports support business decisions.
Browser calls from another origin receive HTTP 403.

## Errors and browser access

The landing page returns `401` without valid credentials and `503` if its password is not configured. API routes do not use this password.
The API returns `400` for an invalid request and `404` for a missing route.
It returns `500` for an internal error.
Error bodies use `{"error":"code"}`.
The JSON responses allow cross-origin reads with `Access-Control-Allow-Origin: *`.
The MCP route checks the `Origin` header and rejects another host with HTTP 403.
The current prototype has no lead submission route.
Use the official LUCA contact page for a sales request.