Skip to main content

Gaius-Lex API

Welcome to the documentation of the Gaius-Lex API, an AI platform for legal analysis.

Overview​

The Gaius-Lex API groups its endpoints into these categories:

  • Documents - Uploading and reading organization documents (/api/v1/upload, /api/v1/external/documents/{file_id}); the files the agent sees, with original downloads, are in Agent API (v2) (/api/v2/files)
  • Search - Searching legal sources (/api/v1/search, /api/v1/available-sources)
  • Answer - Answers to legal questions, optionally simplified; webhook and polling modes (/api/v1/answer)
  • OCR - Asynchronous text recognition (/api/v1/ocr/poll)
  • Anonymization - Synchronous text anonymization (/api/v1/anonymization)
  • Document Verification - Asynchronous verification of citations and sources (/api/v1/doc-verification/poll)
  • Contract Analysis - Abusive clauses, theses and rule compliance (/api/v1/abusivity, /api/v1/theses-analysis, /api/v1/alignment, /api/v1/rule-analysis/poll)
  • Company Registry - KRS and NIP lookups (/api/v1/krs, /api/v1/krs-text-analysis, /api/v1/krs-agreement)
  • Tools - Gaius tools and the organization's tools, run asynchronously (/api/v1/tool-api)
  • API Keys - Managing the organization's API keys (/core_api/api-key/create)

The legal agent is described in the Agent API (v2) folder of the API reference (/api/v2/chat-sessions).

Authentication​

Every endpoint requires the Authorization header:

Authorization: Api-Key <YOUR_API_KEY>

Most endpoints return 401 when the API key is missing or invalid.

Base URL​

https://api.gaius-lex.pl

How it works​

Most endpoints are asynchronous (webhook + polling):

  1. Send a POST request to the main endpoint (e.g. POST /api/v1/answer) or to its poll endpoint (e.g. POST /api/v1/answer/poll).
  2. You receive a request_id (status 202).
  3. Poll GET .../poll/{request_id}.
  4. Read the result (status 200).

Synchronous endpoints (POST /api/v1/anonymization, KRS lookups) return the result immediately.

Agent API (v2)​

The legal agent works in chat sessions, with the same API key:

  1. POST /api/v2/chat-sessions/ creates a session. With first_turn it also starts the agent and returns 202; active_turn_id is the running turn.
  2. GET /api/v2/chat-sessions/{session_id}/turns/{turn_id}/events streams the turn's progress as server-sent events. Each event carries the complete current version of a message or of the turn. After a dropped connection, resume with the Last-Event-ID header.
  3. POST /api/v2/chat-sessions/{session_id}/turns sends the next message. Answer a question from the agent through .../questions/{message_id}/answers, or reject it through .../reject.

GET /api/v2/chat-sessions/{session_id} returns the whole session history, and GET /api/v2/chat-sessions/{session_id}/files the files the agent created or changed in it, with download links. DELETE /api/v2/chat-sessions/{session_id} deletes the session. Sessions belong to the API key that created them.

GET /api/v2/skills lists the skills to select in a turn's skills (pass path and title unchanged), and GET /api/v1/agent-profiles the agent profiles for profile_id.

Files​

The agent works on the key account's drive (/data/user_data) and in the folders shared with it (/data/shared). The API reaches the same files:

  • GET /api/v2/files?path=/data/user_data&recursive=true lists the files page by page (offset, count, next_cursor), each with its id (UUID), size, type and modification date.
  • GET /api/v2/files/{file_id}/content downloads a file with its Content-Type. DOCX and PDF files the agent saved and text files come back unchanged. Uploaded PDFs and scans, whose original is not kept, come back as a DOCX of their recognized text.
  • A file the agent saves appears in the turn as a file_preview artifact whose file_uuid is that file's file_id. GET /api/v2/files/by-path?path=... resolves an agent path (e.g. /data/user_data/opinion.md) to the file.
  • POST /api/v2/files uploads files to a chosen folder (path). on_conflict decides what happens when the folder already has a file of that name: rename (default) adds a date to the name, replace replaces the existing file, and fail returns 409 and stores nothing.
  • GET /api/v2/files/uploads/{request_id} reports the upload's status and the file_id of each stored file, after POST /api/v2/files as well as after POST /api/v1/upload.
  • PATCH /api/v2/files/{file_id} renames a file or moves it to another folder (it keeps its id), and DELETE /api/v2/files/{file_id} deletes it permanently. POST /api/v2/folders creates a folder and DELETE /api/v2/folders?path=... deletes a folder with its content. Only files on the account's drive (/data/user_data) can be changed; folders in /data/shared are read-only.

The agent's answers contain citation markers such as [SA1]: the key in brackets points to a source in the message's metadata.citations. Files the agent saves get the source's signature or title instead of the marker.

Tools​

Every tool of the app (the 12 built-in Gaius tools and the published tools of your organization) has its own endpoint /api/v1/tool-api/{tool_id}. You start it asynchronously and poll for the result. The Tools page has the details, the catalog of tools and examples.

Endpoint documentation (/info)​

Every endpoint of the API has a twin GET <endpoint>/info, e.g. GET /api/v1/search/info. It describes the endpoint and gives the JSON Schema of its input (input_schema) and output (output_schema). See the Tools page for the details.

Get started​

Go to the API reference or to the Agent API (v2) for the details of every endpoint.