← Lawg APIDEVELOPER GUIDE

Build a reliable
research workflow.

Upload documents, ask questions and retrieve cited answers through your own backend.

API originhttps://api.lawg.aiHTTP / JSON
01 / CONNECT

Access & authentication

API access is scoped to an organisation and project. Once access is approved, API project Owners create and manage service keys in Lawg Settings → API keys, with verification for sensitive changes.

A Workspace Admin assigns API project Owners. Project Owners manage project keys and project membership; Workspace invitations and Workspace roles remain with Workspace Admins.

Send Authorization: Bearer <YOUR_API_KEY> from your backend and a descriptive application User-Agent. Store keys in your backend secret manager. Keep them out of browser/mobile code, repositories, logs and URLs.

Choose permissions and an expiry option allowed by your project policy. To rotate a key, update the backend secret, verify access with an existing GET request, then revoke the old key.

Authorise each user’s access to customers, matters and resource IDs in your backend.

Send JSON requests from your backend with stream: false. Save the returned response ID, then use GET to read its status and result.

Review creators, requests & usage

In the selected project, Owners can review all project keys, including historical keys.

  1. Expand a key’s Key details → Created by to see its creator’s current name and email, where available.
  2. Open Request records, select local-time From / Through dates covering up to seven days and click Apply filters. Records show UTC time, request ID, method/route, HTTP status, duration and transport outcome. Use Load more records when available.
  3. Open Project controls → Key usage, choose a UTC date range and optionally enter the Key ID to filter one key. Click Apply filters to review requests, research activity, measured tokens and upstream cost.

Records may appear after an ingestion delay. A key identifies the credential used, not the person or device behind a shared credential. HTTP success does not establish research completion. Upstream costs are not customer charges; unavailable measurements and unverified costs remain unknown.

02 / ADD CONTEXT

Upload a file

Upload a UTF-8 TXT, PDF, CSV or XLSX file. Scanned PDFs use OCR; spreadsheet formulas are not recalculated.

File upload outline
POST /v1/files
Authorization: Bearer <YOUR_API_KEY>
User-Agent: YourProduct-Integration/1.0
Idempotency-Key: upload-example-001
Content-Type: multipart/form-data; boundary=<FORM_BOUNDARY>

# Send one file part named "file" with its original bytes.
# Optional form field: purpose=assistants
# Let your HTTP library construct the multipart boundary.

A successful upload returns HTTP 200, a file_<UUID> ID and its status. If processing, poll GET /v1/files/{file_id} until ready or rejected. Only a ready file can be used in research.

Store the file ID with the corresponding customer or matter record. If a file is rejected, inspect its error before resubmitting.

03 / RESEARCH

Ask & follow up

Research request outline
POST /v1/responses
Authorization: Bearer <YOUR_API_KEY>
User-Agent: YourProduct-Integration/1.0
Idempotency-Key: research-example-001
Content-Type: application/json

{
  "model": "lawg",
  "input": "Summarise the dates and amounts in this synthetic ledger, citing the source.",
  "file_ids": ["file_<UUID>"],
  "stream": false
}

For a question without a file, omit file_ids or use an empty array. A JSON request returns HTTP 202 and a stable resp_<UUID> ID. Use this ID to retrieve the operation’s status and result.

To follow up, POST to the same endpoint with a new Idempotency-Key and an authorised, completed previous_response_id. Lawg uses that response to recover the conversation context.

Follow-up JSON body
{
  "model": "lawg",
  "input": "Which transaction details still need checking?",
  "previous_response_id": "resp_<UUID>",
  "stream": false
}

For an initial question, include all required files in file_ids.

04 / RETRIEVE

Read results & citations

Poll GET /v1/responses/{response_id} with a finite client waiting period. queued and in_progress are nonterminal. Handle completed, failed and cancelled separately; a client timeout does not cancel accepted work.

Illustrative completed response
{
  "id": "resp_<UUID>",
  "object": "response",
  "model": "lawg",
  "status": "completed",
  "output_text": "The synthetic ledger records AUD 123 [1].",
  "citations": [{
    "index": 1,
    "type": "file",
    "file_id": "file_<UUID>",
    "page": 1,
    "text": "Synthetic ledger total: AUD 123."
  }],
  "unresolved": [],
  "evidence_status": "bound",
  "review_state": "unreviewed_draft",
  "usage": {"measured_input_tokens": 100, "measured_output_tokens": 20},
  "error": null
}

Match [1] in output_text to citations[].index. File citations may include file_id, page and text; public sources may provide a title, URL and available evidence metadata.

Display evidence_status, unresolved and review_state alongside the answer so users can review its evidence and draft status. Use safe Markdown rendering for answers, source titles and document content.

05 / RECOVER

Recover safely

  1. Before each new POST, durably store the business operation, original request values/file-byte reference and a unique Idempotency-Key of 8–128 visible ASCII characters.
  2. Save the returned file/response ID in protected backend storage. There is no list/search endpoint.
  3. If an ID is known, recover with GET. If a POST outcome is uncertain before an ID arrives, retry with the same key and the same request values or original file bytes.
  4. A changed payload with the same key returns 409. Honour retryable and Retry-After with bounded backoff. If a failed operation has an uncertain outcome, contact support before submitting it again.

An edge rejection may return a different error format. If it persists, contact support with the UTC time and HTTP status.

06 / FINISH

Cancel & delete

Additional lifecycle operations
OperationRequestMeaning
Cancel researchPOST /v1/responses/{response_id}/cancel202 acknowledges the request; GET the same response to confirm its state.
Delete a fileDELETE /v1/files/{file_id}202 starts deletion; GET the file to verify its terminal state.

Cancellation may still incur usage. Deleting a file makes associated evidence and affected results unavailable; measured usage is retained. Remove copies cached or exported by your application according to your retention policy.

Revoke a compromised key immediately.

07 / HANDLE BOUNDARIES

Errors & limits

Application errors use application/problem+json with a code, request_id and retryable. The X-Request-ID header helps support trace a request.

Common HTTP outcomes
StatusAction
401 / 403Correct credential, expiry, permission or project authority; do not retry automatically.
404Check the resource ID and the key’s project access.
409Inspect the conflict: changed idempotent payload, file readiness or prior response state.
422Correct unsupported or invalid input rather than resubmitting it unchanged.
429 / 503Read retryability and Retry-After; back off within a finite budget and preserve the operation identity.

Platform limits are 25 MiB per original, 200 pages per document, 4,000 question characters, and ten files/1,500,000 extracted characters per research request. Projects may have lower storage, request, concurrency and resource limits. Model token limits are checked separately, so a ready file may still exceed research limits.

08 / VALIDATE

Data & professional review

Test the full flow with synthetic data, including access checks, file processing, recovery, citation rendering, cancellation, deletion and key revocation.

Document analysis and OCR may send original files to processing providers. Confirm the permitted data, processing locations and retention terms before submitting customer documents.

Answers are drafts for professional review. Check facts, assumptions and sources before relying on them. See the security and data-handling overview, privacy policy and terms for processing and retention conditions.

For access or integration help, contact support@coeusx.ai with UTC times and request/resource IDs. Keep keys and customer content out of support messages.