Hey, human!
HTTP/2 200 OK content-type: text/markdown; charset=utf-8 vary: accept, user-agent x-agent: [ai_agent]
Loading the agent response…
Ask a question about the files and get an answer with sources (body: question, folder, mode)
Answers one question from the workspace's files, written by the same code as Ask about files in the app, and returns { answer, sources, credits_used, paid_by, mode, notes }. In answer the files are cited as [1], [2]; sources lists them with file_id (the files API's id, null when unknown), name and pages. Body: question (required, up to 4000 characters), history (optional, up to 20 earlier messages of {role, content}, oldest first, for a follow-up), folder (a folder id: only that folder and its subfolders are read), mode (basic, the default, or deep: slower and thorough, Pro plans and organizations with their own AI key). It only reads: nothing is changed, nothing is saved: each call is a separate question unless you send history. Only files the token's person can open are read. THIS SPENDS AI CREDITS exactly like a question in the app (the plan's credits, extra credits, or the organization's own AI key): credits_used says how many; when the credits for the period are used the call is 429 ai_budget, and a person asking far too fast gets 429 slow_down. A call can run for minutes (up to 5), so set a long client timeout. Search and reading with no credits: searchFiles and getFileText. It counts as an AI request: 1 unit of the daily quota and the plan's search and AI limit a minute per key (its real cost is the credits above). Needs ai:ask; a token made before this scope existed does not have it, so make a new one in Settings > API.
What you provide
- Question: What to ask about the files. Each call is a separate question: nothing from an earlier call is remembered.
- Folderoptional: Only answer from this folder and its subfolders
- Modeoptional: deep is slower and thorough; Pro plans and organizations with their own AI key only
- Historyoptional: Earlier questions and answers of this conversation, oldest first, so a follow-up makes sense; each is charged as input
Do this with AI
I want to ask a question about the files and get an answer with sources (body: question, folder, mode). Use the Tarkle API. Read the reference for this operation and follow it exactly: https://project-03b42162.restlessdocs.com/endpoint/askfiles.md Authenticate with your API key as a Bearer token in the Authorization header. Then make the request for me and tell me what came back.
Paste this into Claude, Cursor, or any AI assistant and it will do it for you.
https://tarkle.com/api/v1/ai/askcurl --request POST \
--url https://tarkle.com/api/v1/ai/ask \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--header 'X-Workspace-Key: X-Workspace-Key' \
--data '
{
"question": "question",
"folder": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mode": "basic",
"history": [
{
"role": "user",
"content": "content"
}
]
}
'Query parameters
workspace_keystringThe same key as the X-Workspace-Key header, for clients that cannot set headers. Send one of the two, or both with the same value (different values are 400 conflicting_workspace)
Header parameters
X-Workspace-KeystringrequiredThe 8-character key of the workspace this call acts on; GET /workspaces lists the keys a token can use. A workspace id is refused (400 workspace_key_required)
Idempotency-KeystringMakes a write safe to repeat. Send a random value (a UUID is fine) of up to 255 visible characters. A repeat of the same request gets the first answer again, with the header `Idempotent-Replayed: true`, and does nothing twice. The same key for a different request is 422 `idempotency_key_reused`; the same request while the first one is still running is 409 `idempotency_in_progress`. A 5xx or 429 is not remembered, so retrying it runs the request again. Keys last 24 hours and belong to the account that created the token.
Body
application/jsonrequiredquestionstringrequiredWhat to ask about the files. Each call is a separate question: nothing from an earlier call is remembered.
folderstring · uuidOnly answer from this folder and its subfolders
modestringdeep is slower and thorough; Pro plans and organizations with their own AI key only
Earlier questions and answers of this conversation, oldest first, so a follow-up makes sense; each is charged as input
rolestringrequiredcontentstringrequired