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.
- Expand a key’s Key details → Created by to see its creator’s current name and email, where available.
- 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.
- 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.
Upload a file
Upload a UTF-8 TXT, PDF, CSV or XLSX file. Scanned PDFs use OCR; spreadsheet formulas are not recalculated.
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.
Ask & follow up
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.
{
"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.
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.
{
"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.
Recover safely
- Before each new POST, durably store the business operation, original request values/file-byte reference and a unique
Idempotency-Keyof 8–128 visible ASCII characters. - Save the returned file/response ID in protected backend storage. There is no list/search endpoint.
- 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.
- A changed payload with the same key returns
409. HonourretryableandRetry-Afterwith 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.
Cancel & delete
| Operation | Request | Meaning |
|---|---|---|
| Cancel research | POST /v1/responses/{response_id}/cancel | 202 acknowledges the request; GET the same response to confirm its state. |
| Delete a file | DELETE /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.
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.
| Status | Action |
|---|---|
| 401 / 403 | Correct credential, expiry, permission or project authority; do not retry automatically. |
| 404 | Check the resource ID and the key’s project access. |
| 409 | Inspect the conflict: changed idempotent payload, file readiness or prior response state. |
| 422 | Correct unsupported or invalid input rather than resubmitting it unchanged. |
| 429 / 503 | Read 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.
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.
