Ai API

GET /ai/batch/{job_id}

Batch Status

Get batch job status and results.

Parameters

Responses

Example

curl -X GET http://localhost:8000/ai/batch/:job_id \
  -H "Authorization: Bearer $TOKEN"

GET /ai/conversations

List Convs

List conversations, newest first, each with its count of open proposals.

Parameters

Responses

Example

curl -X GET http://localhost:8000/ai/conversations \
  -H "Authorization: Bearer $TOKEN"

POST /ai/conversations

Create Conv

Create a new conversation.

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /ai/conversations/{conversation_id}

Get Conv

Get a conversation with its messages and the reading jobs started from it.

Parameters

Responses

Example

curl -X GET http://localhost:8000/ai/conversations/:conversation_id \
  -H "Authorization: Bearer $TOKEN"

PATCH /ai/conversations/{conversation_id}

Rename Conv

Rename a conversation.

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/ai/conversations/:conversation_id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

DELETE /ai/conversations/{conversation_id}

Delete Conv

Delete a conversation and all its messages.

Parameters

Responses

Example

curl -X DELETE http://localhost:8000/ai/conversations/:conversation_id \
  -H "Authorization: Bearer $TOKEN"

POST /ai/conversations/{conversation_id}/confirm

Confirm Action

Execute one pending action the user has confirmed. No model turn resumes after a write; the user asks the next question. An action that is no longer pending, or whose module is not enabled, is 409.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/confirm \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/conversations/{conversation_id}/confirm-all

Confirm All

Execute the pending actions on one message, in the order they were proposed. ``tool_call_ids`` narrows the run to a selection; without it every pending action runs. Each action is claimed and finalized on its own, so one failure never rolls back the others; the reply lists the outcome per action.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/confirm-all \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/conversations/{conversation_id}/dismiss

Dismiss Action

Persist dismissal of one proposal so it stays gone after reload.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/dismiss \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/conversations/{conversation_id}/dismiss-all

Dismiss All

Persist dismissal of a selected proposal set under one message-row lock.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/dismiss-all \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/conversations/{conversation_id}/jobs/{job_id}/proposals

Propose From Job

Turn a finished reading job into bill proposals the user confirms. Vendors are matched to existing contacts and lines to items by exact name or SKU. When a vendor is missing and the user may create contacts, proposal order is vendor first, bill second; the bill stores a server-side result binding to the vendor action and resolves its returned id only when confirmation executes. Nothing is written until the user confirms a card. Calling again returns the same proposals.

Parameters

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/jobs/:job_id/proposals \
  -H "Authorization: Bearer $TOKEN"

POST /ai/conversations/{conversation_id}/query

Query In Conversation

Ask the assistant within a conversation. Normal messages, including images and PDFs, run the agent inline. Receipt extraction is an explicit ``document_mode=receipts`` workflow that creates a background reading job. Reads execute against the app the user sees and changes come back as pending actions to confirm. A failed run is stored as an assistant message so the thread keeps its history.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/conversations/:conversation_id/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/estimate-credits

Estimate Credits

Preview the relay's current per-file credit cost. Page counts remain informational; the cloud gateway charges one credit per model request/file, so local estimates must not maintain a second pricing formula that can drift from the authoritative meter.

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/estimate-credits \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /ai/file/{file_id}

Ai File

Retrieve a previously uploaded file.

Parameters

Responses

Example

curl -X GET http://localhost:8000/ai/file/:file_id \
  -H "Authorization: Bearer $TOKEN"

GET /ai/memory

Get Ai Memory

Return the per-company AI memory (notes and key-value facts).

Responses

Example

curl -X GET http://localhost:8000/ai/memory \
  -H "Authorization: Bearer $TOKEN"

DELETE /ai/memory

Clear Ai Memory

Wipe all AI memory for this company.

Responses

Example

curl -X DELETE http://localhost:8000/ai/memory \
  -H "Authorization: Bearer $TOKEN"

POST /ai/memory/kv

Set Ai Memory Kv

Set a key-value fact in AI memory (max 100 keys).

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/memory/kv \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/memory/notes

Add Ai Memory Note

Append a note to AI memory (max 50 notes, oldest trimmed).

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/memory/notes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /ai/query

Ai Query

Run a one-off read-only agent query against live canonical ERP APIs.

Request body

Responses

Example

curl -X POST http://localhost:8000/ai/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /ai/quota-status

Quota Status

Return current AI quota usage for the UI badge. Returns used/limit/topup/remaining/tier. Never raises - returns empty dict if gateway not configured (local install).

Responses

Example

curl -X GET http://localhost:8000/ai/quota-status \
  -H "Authorization: Bearer $TOKEN"

POST /ai/upload

Ai Upload

Upload files for AI batch processing. Returns list of file IDs.

Responses

Example

curl -X POST http://localhost:8000/ai/upload \
  -H "Authorization: Bearer $TOKEN"

GET /ai/usage-stats

Usage Stats

Per-user AI usage for the current calendar month. Returns list of {user_id, user_name, query_count, credits_used, last_query_at}.

Responses

Example

curl -X GET http://localhost:8000/ai/usage-stats \
  -H "Authorization: Bearer $TOKEN"