Tools

Every tool of the Gaius-Lex app can be run over the API: the 12 built-in Gaius tools (Dashboard → "See all tools") and the published tools of your account and organization (skill, block, workflow). Automata, the tools that start themselves, have no endpoint.

A tool works as it does in the app: it takes the form's fields, runs in the background and returns a result. The Tools category of the API reference describes the endpoints.

Authentication

Send every request with an organization key in the Authorization: Api-Key <key> header. Create the key in the app: Settings → Organization → API keys. A read-only key can list tools and read their documentation but cannot start them.

Endpoints

Method and path	Description
GET /api/v1/tool-api	The tools available to the key, each with run_url and info_url.
GET /api/v1/tool-api/{tool_id}/info	The tool's documentation: input fields (input_schema), results (outputs_schema) and an example call.
POST /api/v1/tool-api/{tool_id}	Starts a run in the background. Answers 202 with run_id and poll_url.
GET /api/v1/tool-api/{tool_id}/runs/{run_id}	The state and result of a run.
POST /api/v1/tool-api/{tool_id}/runs/{run_id}:cancel	Cancels a run.

Step by step

1. Check the tool's fields: GET /api/v1/tool-api/{tool_id}/info.
2. Send POST /api/v1/tool-api/{tool_id} with {"inputs": {...}}. The keys of inputs are the field keys of input_schema. The inputs are checked as the app's form checks them.
3. Poll poll_url every few seconds until it answers 200.
4. Read outputs. Result files have a download_url.

curl -X POST https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize \
  -H "Authorization: Api-Key $GAIUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"inputs": {"text": "Jan Kowalski, PESEL 80010112345, lives in Kraków."}}'
# 202 {"run_id": "6a0f…", "tool_id": "gaius.anonymize", "status": "queued",
#      "poll_url": "https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize/runs/6a0f…", …}

curl https://api.gaius-lex.pl/api/v1/tool-api/gaius.anonymize/runs/6a0f… \
  -H "Authorization: Api-Key $GAIUS_API_KEY"
# 200 {"status": "succeeded", "outputs": {"text": "[OSOBA_1], PESEL [PESEL_1], lives in [MIEJSCOWOŚĆ_1]."}, …}

Tools with the agent take from tens of seconds to a few minutes. API runs share the account's run queue with the app. When the queue is full the API answers 429, and queue_position shows a run's place in the queue. In the app every tool shows a ready call: the tool → "API call".

Run states

status	Response code	Meaning
queued	202	Waiting in the queue.
running	202	In progress.
waiting_for_user	200	A workflow step failed and the tool waits for a decision in the app. outputs is empty.
succeeded	200	Done, the result is in outputs.
failed	200	Failed, see error (code, message).
cancelled	200	Cancelled.

Files

File fields take a list [{"file_id": "<UUID>"}]. The file must be on the key account's drive: the UUID comes from POST /api/v2/files or GET /api/v2/files/uploads/{request_id} (see Agent API (v2)). Result files have name, mime, size, uuid and download_url.

Built-in Gaius tools

Input: text is text (up to 20,000 characters), files is a list of files. Output: outputs.text is Gaius's answer. Tools that save or change files also return them in outputs.files.

tool_id	Name in the app	Input	Output
gaius.legalResearch	Legal research	text (required)	text
gaius.prepareDocument	Prepare a pleading	text (required), files (0–10)	text
gaius.caseLawLine	Find the case law line	text (required)	text
gaius.extendText	Extend text	text (required)	text
gaius.compareDocuments	Compare documents	files (2–10)	text
gaius.translate	Translate	text or files (DOCX, 0–5)	text, files
gaius.inconsistencyAnalysis	Inconsistency analysis	text or files (DOCX, 0–5)	text, files
gaius.textCorrection	Proofreading	text or files (DOCX, 0–5)	text, files
gaius.chatWithDocument	Chat with a document	files (1–5), text (question, optional)	text
gaius.anonymize	Anonymize	text or files (DOCX, 0–5)	text, files
gaius.ocr	Read text from an image	files (PDF, PNG, JPG, 1–10)	text
gaius.createPdf	Create a PDF	files (2–10)	text, files

"text or files" means at least one of them is required. In DOCX files the changes are made as tracked changes and comments; a translation is a new file.

Organization tools

Published skills, blocks and workflows have a tool_id of the form tool.<type>.<id>, e.g. tool.skill.org_1.klauzule. Their inputs and results depend on the tool, so always read them from GET /api/v1/tool-api/{tool_id}/info. The tools depend on the key, so a tool's /info needs the key.

Errors

Errors have the shape {"code": "...", "field": "...", "detail": "..."}.

HTTP code	code	When
400	invalid_request, unknown_input, required, …	Invalid inputs. field names the field.
403	forbidden	No access to the tool's skill. No key, or a start with a read-only key, also answer 403.
404	tool_not_found, run_not_found	No such tool or run for this key.
409	tool_disabled, automation_tool	The tool is disabled or is an automaton.
410	skill_gone	The tool's skill was deleted.
429		The account's run queue is full.

Endpoint documentation (/info)

Every endpoint of the API has a twin GET <endpoint>/info, e.g. GET /api/v1/search/info, GET /api/v1/ocr/poll/{request_id}/info or GET /api/v1/tool-api/gaius.ocr/info. It returns:

• endpoint and method: the path and method of the endpoint described,
• summary and description: what the endpoint does,
• input_schema: the JSON Schema of the input (parameters and request body). An endpoint without input has {"type": "object", "properties": {}},
• output_schema: the JSON Schema of the response. A response without a body (204) has {"type": "null"},
• examples and related: examples and related endpoints (e.g. poll_url),
• operations: every method of the path, when there are several.

The /info of the API's endpoints needs no key. Tools are the exception, as they depend on the key.

curl https://api.gaius-lex.pl/api/v1/search/info
curl https://api.gaius-lex.pl/api/v1/tool-api/gaius.ocr/info -H "Authorization: Api-Key $GAIUS_API_KEY"