Lucius Agent API

The same three tools are exposed over MCP (by name) and over REST (by path). Every notice carries: title, buyer, country, deadline, value, the value's currency, CPV codes, source, source link, a snippet of up to 700 characters, and the attribution its source's licence asks for. A source whose terms do not cover the notice text comes without a snippet. A field the source did not give is null: a value with no stated currency has no currency. CPV codes come with TED and Public Contracts Scotland notices and with about a quarter of SAM.gov notices; on the other sources the list is empty, so search those with a query, not with cpv_prefix. The two pack analysis tools are described under pack analysis, below.

Send several documents, one ZIP of the pack, or a link, then read the status and the result with the analysis_id:

curl -H "Authorization: Bearer lk_live_..." \
  -F "files=@invitation-to-tender.pdf" \
  -F "files=@specification.docx" \
  -F "files=@pricing-schedule.xlsx" \
  "https://api.ailucius.com/api/v1/ext/packs"

curl -H "Authorization: Bearer lk_live_..." \
  -F "files=@tender-pack.zip" \
  "https://api.ailucius.com/api/v1/ext/packs"

curl -H "Authorization: Bearer lk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://..."}' \
  "https://api.ailucius.com/api/v1/ext/packs/url"

curl -H "Authorization: Bearer lk_live_..." \
  "https://api.ailucius.com/api/v1/ext/packs/{analysis_id}?requirements_limit=200"

A submit answers at once. status is queued, or the existing analysis's status when deduplicated is true:

HTTP/1.1 202 Accepted

{
  "analysis_id": "...",
  "status": "queued",
  "deduplicated": false,
  "status_url": "/api/v1/ext/packs/{analysis_id}",
  "app_url": "https://ailucius.com/dashboard/{analysis_id}"
}

Statuses

• queued: Accepted, not started yet. progress is 0.
• processing: Running. progress (0 to 100) and message say how far it is.
• complete: Done. result holds the analysis and progress is 100.
• failed: Stopped. reason says why, in plain words.

A complete analysis. The fields before result come with every status, and a failed one adds reason:

{
  "analysis_id": "...",
  "status": "complete",
  "progress": 100,
  "message": "...",
  "submitted_at": "...",
  "updated_at": "...",
  "app_url": "https://ailucius.com/dashboard/{analysis_id}",
  "result": {
    "title": "...",
    "buyer": "...",
    "deadline": "...",
    "summary": "...",
    "document": {
      "classification": "...",
      "kind": "...",
      "is_tender": true,
      "note": null
    },
    "verdict": {
      "call": "...",
      "recommendation": "...",
      "confidence": ...,
      "open_requirements": 0,
      "note": null,
      "stale": false,
      "summary": "...",
      "strengths": [...],
      "risks": [...],
      "competition": "...",
      "profile_incomplete": false,
      "deciding_requirements": [...]
    },
    "coverage": {
      "complete": true,
      "notes": [],
      "files": [
        {
          "name": "...",
          "pages": ...,
          "read": "full",
          "left_out_of_upload": false,
          "detail": null
        }
      ],
      "second_read": null
    },
    "documents": ["..."],
    "requirements_total": ...,
    "requirements_final": true,
    "requirements_locked": false,
    "locked_reason": null,
    "deciding_positions": [...],
    "requirements_offset": 0,
    "requirements_count": ...,
    "requirements_next_offset": null,
    "requirements": [
      {
        "position": 1,
        "requirement": "...",
        "requirement_en": "...",
        "original_text": "...",
        "severity": "...",
        "why": "...",
        "section": "...",
        "document": "...",
        "page": ...,
        "page_is_approximate": false,
        "citation": "...",
        "quote_verified": true,
        "deciding": true
      }
    ],
    "forms": [
      {
        "name": "...",
        "name_en": "...",
        "page": ...,
        "page_basis": "...",
        "section": "...",
        "mandatory": true,
        "purpose": "..."
      }
    ]
  }
}

The result

• document says what was read. When is_tender is false (a bid somebody wrote, a signed contract, something else, or a document Lucius could not classify), verdict is null, no requirement is deciding and document.note says why.
• verdict is the bid call, or null when the analysis made none. call is Bid, Bid with caveats or Skip, or Closed with closed_on when the deadline has passed; recommendation is GO, NO GO or CAUTION. When the workspace has not described its company, Lucius makes no call: call, recommendation and confidence are null, profile_incomplete is true, deciding_requirements lists the pass/fail gates, open_requirements counts the ones still unanswered and note says what to do. stale is true when the company details changed after the call was made.
• coverage says how the pack was read. complete is true only when every file got the full read. notes lists every limit of this read in plain words: pages that could not be read, a file read as plain text, a file the upload did not take. files says for each file of a pack whether it was read in full, as text, in partial or not_read; it is null for a single document with nothing left out. While second_read is pending, a second read is still adding requirements and requirements_final is false: read the result again in a few minutes.
• Each requirement carries original_text, quoted from the pack in its own language, and document, page and citation. page_is_approximate is true where the page is estimated, as it is in Word files. quote_verified is true when the quote was found in the pack text. severity is CRITICAL, HIGH, MEDIUM or LOW, and deciding is true for the requirements that decide the bid, the pass/fail gates first.
• Requirements come in pages of requirements_limit (default 200, at most 1,000). Pass requirements_next_offset as requirements_offset for the next page; it is null on the last. deciding_only=true returns only the requirements that decide the bid.
• On a plan without the full requirements list, only the requirements that decide the bid are returned, requirements_locked is true and locked_reason says how to unlock the rest in the app, as in the app itself.
• forms lists the forms the pack asks bidders to return once they have been mapped, else null.

Limits

• Files: PDF, Word (DOC, DOCX) and Excel (XLS, XLSX), up to 80 documents of at most 40 MB each, one files part per document. An image (PNG, JPG, WEBP, TIFF, BMP or GIF) is read on its own, as a single file.
• Or one ZIP on its own, holding up to 80 documents and 300 MB once unpacked, at most 40 MB each. A ZIP sent with other files is refused.
• One request carries at most 32 MB in all. For a larger pack, put it at a public link and use POST /api/v1/ext/packs/url.
• A link is fetched the way the app's paste-a-link is: private and internal addresses are refused, every redirect is checked, each file fetched is capped at 15 MB, and a notice page is read for at most 5 of the documents it links to. The link starts with http:// or https:// and is at most 2,048 characters.
• Links on UNGM (ungm.org), GeBIZ (gebiz.gov.sg), NZ GETS (gets.govt.nz), India CPPP (eprocure.gov.in) and AusTender (Approach to Market notices on tenders.gov.au) are refused with 400, as is a link that leads to one of them: their terms do not allow Lucius to pass their material on, and the index tools do not return them either. Download the documents from the portal and send them to POST /api/v1/ext/packs instead.

Metering

• A submit is one request once the pack is accepted, over REST or MCP. A pack that is refused (a bad type, too large, over the plan) is not counted.
• Reading a complete result is one request. Polls that answer queued, processing or failed are free: the API has no callback, so polling is how you wait.
• Requests are priced like every other call: the first 100 each month are free for the workspace, then EUR 0.02 each from prepaid credit. See pricing.
• The analysis itself counts against the plan, not the credit: each accepted pack uses one of the workspace's monthly analyses, like an upload in the app. A deduplicated submit uses none.

Errors

• 400: Nothing usable was sent. No file, an unsupported type, a ZIP sent with other files, a bad or refused link, or an id that is not a uuid.
• 402: The workspace has used its plan's monthly analyses, or its free API requests and API credit. The detail says which and what to do.
• 403: The key reads the index only (a key made before pack analysis opened: make a new one), or its workspace has no owner, admin or editor who can start an analysis.
• 404: No analysis with that id in the key's workspace, or the workspace limited that tender to some of its members: a key reads only what every member reads.
• 409: The same file was sent in the last 24 hours and that copy cannot be read through the API, for example because the workspace limited it to some members. Open it in the Lucius app, or send the file again after 24 hours.
• 413: A file is over the size limit.
• 422: A file could not be read (corrupt, empty or password-protected), or a query value is out of range.
• 429: The key's per-minute rate limit or daily result cap was reached.

Over MCP a refusal is an error result with the same status and message.