AI & Chat RAG-powered chat, semantic search, notes, metadata extraction, and auto-summarization

Overview

Fastio provides built-in AI capabilities for workspaces and shares:

• RAG-powered chat — Ask questions about indexed files with citations to specific pages and snippets
• General chat — AI conversation with optional file attachments for one-off analysis
• Auto-summarization — AI-generated titles and descriptions for shares
• Metadata extraction — AI-powered structured metadata extraction from documents, spreadsheets, images, and code
• Semantic search — Find files by meaning, not just keywords
• Notes — Markdown storage nodes that are indexed for RAG, letting you bank knowledge over time

Fastio's AI is a full agent, not a read-only Q&A tool. In addition to reading, analyzing, searching, and answering questions about your files, it can take actions on your behalf — for example, creating documents and notes and organizing your content. It always acts within your own permissions and plan entitlements, and its actions consume credits like any other operation.

Plan Requirements

AI capabilities are gated by a set of billing-plan features:

• content_ai — master switch for AI features. Covers the baseline AI surfaces: listing chats, reading chat details and message history, streaming existing responses, and notes. Available on all paid plans.
• ai_agent — narrower gate for interactive agentic flows. Required to create chats, send chat messages, and enable the intelligence toggle on a workspace or portal share (the toggle controls the RAG indexing pipeline that feeds the chat surface).
• ai_autotitle — gates the share auto-title / description endpoint (POST /share/{id}/ai/autotitle/). A plan without this feature is rejected when calling that endpoint.
• ai_autoog — gates the AI-generated OG image for private shares (GET /share/{id}/ai/autoog/). A private share on a plan without this feature is served the default private OG image instead of a custom one; public-share OG generation does not require it.

Plan coverage:

All current paid plans (Starter, Business, and Growth) include both content_ai and ai_agent, so full AI — chat, intelligence, and RAG — is available on every plan a new organization can choose. New organizations choose one of these paid plans.

How gated endpoints respond when a plan lacks the feature:

• Create chat / send message: 1695 (Upgrade Required) → HTTP 402
• Attempt to set intelligence=true on create/update: 1605 (Invalid Input) with a message indicating intelligence requires a plan that supports agentic AI

New organizations — for humans and AI agents alike — choose a paid plan (Starter, Business, or Growth), each of which includes both content_ai and ai_agent and unlocks full agentic chat, intelligence, and RAG. See the Organizations reference for plan selection.

Intelligence Setting

The intelligence boolean on a workspace or portal share controls whether uploaded files are automatically indexed for RAG.

• intelligence=true — Files are auto-indexed for semantic search, summarization, and citation. Required for the agent to search the scope’s indexed files (RAG) and cite them. Requires both content_ai and ai_agent plan features (see Plan Requirements above). On plans that include ai_agent, new workspaces created by agent accounts default intelligence to true. If a plan does not include ai_agent, the default is false because the indexing pipeline has no consumer.
• intelligence=false — Files are stored/shared without RAG indexing. You can still chat with the agent and attach specific file references for direct file analysis (when the plan supports chat).

Shared folder restriction: Intelligence is only available on portal shares (independent storage). Workspace folder shares (storage_mode=workspace_folder) cannot have intelligence enabled — their files are indexed through the parent workspace instead. The API will return an error if you attempt to enable intelligence on a shared folder share.

Enable at creation:

Update later:

Note: Intelligence can be enabled and disabled within time restrictions. Disabling intelligence destroys indexed embeddings (the vector index is flushed). Re-enabling intelligence incurs re-indexing costs as AI credits are consumed to re-index all files. When a plan loses ai_agent (e.g. on downgrade), the RAG indexing pipeline stops even if the instance flag remains set; previously indexed embeddings remain but will not be updated.

How the Agent Uses Files

There is no chat “type” to choose — a single agent surface handles every conversation. You do not pass a type (or personality) parameter; the agent adapts to what you send:

• General conversation. Ask anything; the agent answers from its own knowledge. No files are required.
• Grounded in indexed files (RAG). When the workspace/share intelligence setting is enabled, the agent can search the scope’s indexed files and return answers with citations to specific files, pages, and text snippets. With no attachments it may draw on the entire indexed scope; only files that reach ai_state: indexed participate in that search.
• Focused on specific files/folders. Attach files or folders to a turn by including them as reference items in the references, content_parts, subjects, or uploads arrays (see Attaching Files and Folders below). Any file with a ready preview or AI summary is eligible; the agent uses the attached content directly (e.g., “Describe this image”, “Summarize this PDF”).

A single agent turn can combine all of the above — general reasoning, RAG over the indexed scope, and directly attached files.

Attaching Files and Folders

Give the agent specific files or folders as context by including them as reference items in the references, content_parts, or subjects array of a create-chat or send-message request. You do not assemble a file’s metadata yourself — send only the node id (and, for a file, an optional version id), and Fastio resolves the full details server-side after verifying your access and the file’s AI-readiness.

subjects pins objects from inside the workspace/share as the turn’s focus; a separate uploads array carries files staged from outside the scope. content_parts is an ordered stream that interleaves text segments with inline reference pills (the same item shape). All three of references, content_parts, and subjects are resolved and gated by the rules below.

File reference

{ "type": "file", "id": "{node_id}", "file_details": { "node_id": "{node_id}", "version_id": "{version_id}" } }

• version_id is optional — omit it to attach the file’s current version. Get a version_id from the file’s version field in a storage list/details response.
• Only file (or note) nodes may be attached as type: file.
• The file must be AI-eligible (have a ready preview or summary).

Folder reference

{ "type": "folder", "id": "{node_id}", "folder_details": { "node_id": "{node_id}" } }

• Attaches a folder so the agent can use its contents as context. Only folder nodes may be attached as type: folder.
• The folder’s indexed files participate in the agent’s RAG search (requires intelligence enabled).

Limits

• Up to 20 files and 200 MB total per turn (large images and videos count at their smaller preview size).
• Up to 100 file/folder references total across all three arrays.

Validation is strict — a bad reference fails the request

If a referenced file or folder cannot be attached — it does not exist, you cannot access it, it has been deleted, or it is not AI-eligible — the request is rejected with an error, not silently dropped:

• 1609 (Not Found) / 404 — the referenced file or folder does not exist, is not accessible, has been deleted, or a pinned version is unavailable (all reported the same way so a caller cannot probe existence).
• 1605 (Invalid Input) / 406 — a reference is malformed, is missing its node id, carries an invalid/conflicting version id, is the wrong node type (a folder referenced as a file, or vice-versa), or the request exceeds the 20-file / 200 MB / 100-reference / 200-occurrence limits.
• 1680 (Access Denied) / 401 — folder attachments are not permitted in this share (a restricted-view guest). Does not occur on workspace chats, where members can view all files.

Choosing what to attach

AI State (File Readiness)

Files in an intelligent workspace progress through AI processing states:

Files with ai_state: ready can be used with AI chat. Files with ai_state: indexed have additionally had their contents indexed for RAG-powered semantic search. When intelligence is enabled on a workspace/share, files progress to indexed automatically. Check a file’s AI state in the ai.state field of storage list or file details responses.

Controlling Response Length and Style

There is no personality parameter. Control verbosity and style directly in your question phrasing:

• “In one sentence, what is the main conclusion?”
• “List only the file names that mention GDPR, no explanations”
• “Give me a brief summary — 2–3 bullet points max”

Advanced Per-Turn Fields

Beyond question and the file-reference arrays, a create-chat or send-message request accepts these optional per-turn fields. All are optional; omit them for normal use.

The acting user’s identity is taken from your Bearer token — it is never read from the request body, so a request cannot spoof who the turn runs as.

Notes (Stored Knowledge)

Notes are a storage node type (like files and folders) that store markdown content directly on the server. They appear in storage listings with "type": "note" and "mimetype": "text/markdown". Notes are workspace-only — they cannot be created in shares.

Why Notes Matter

In an intelligent workspace, notes are ingested and indexed just like uploaded files. This makes them a way to bank knowledge over time — store interesting facts, research findings, decisions, or project context. In future AI chats that scope the entire workspace (or include the note’s folder), the note content will be used as grounding when the AI searches for relevant information.

Create a note

{parent_id} is a folder OpaqueId or "root". Returns the created note as a node resource.

Update a note

At least one of name or content must be provided. Updating content creates a new version.

Read note content

Linking a user to a note

• In workspace context: https://{org_domain}.fast.io/workspace/{workspace_name}?note={note_opaque_id}
• Direct preview: use the preview URL for the note node

Workspace AI Endpoints

Create a new chat

Auth: Bearer token required. Workspace view permission. content_ai and ai_agent plan features required.

Also accepts the optional view, activity, role_in_org, and idempotency_key fields (see Advanced Per-Turn Fields above).

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=What were the Q3 revenue figures?" \
  -d "privacy=private"

Response (200 OK):

{
  "result": true,
  "thread": {
    "thread_id": "aBcDeFgHiJkLmNoPqR",
    "creator": { "type": "user", "id": "1234567890123456789" },
    "scope": { "type": "workspace", "id": "1234567890123456789" },
    "name": "New Chat",
    "status": "active",
    "kind": "user",
    "cost": { "credits": 0, "tokens": 0 },
    "privacy": { "visibility": "private", "owner": { "type": "user", "id": "1234567890123456789" } },
    "created_at": "2026-07-07 16:37:29 UTC",
    "updated_at": "2026-07-07 16:37:29 UTC"
  },
  "turn": {
    "turn_id": "xYzAbCdEfGhIjKlMnO",
    "thread_id": "aBcDeFgHiJkLmNoPqR",
    "seq": 1,
    "status": "pending",
    "idempotency_key": "3f2a…",
    "query": { "text": "What were the Q3 revenue figures?" },
    "error": null,
    "cost": { "credits": 0, "tokens": 0 },
    "created_at": "2026-07-07 16:37:29 UTC",
    "updated_at": "2026-07-07 16:37:29 UTC"
  }
}

The full field lists are in Chat Session Object Schema (thread) and Message Object Schema (turn) below.

Error responses:

List chats

Auth: Bearer token required. Workspace view permission. content_ai plan feature required.

Query parameters:

Variant: Append /deleted to the path to list deleted chats: GET .../ai/agent/list/deleted

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "chats": {
    "count": 1,
    "items": [
      {
        "thread_id": "aBcDeFgHiJkLmNoPqR",
        "creator": { "type": "user", "id": "1234567890123456789" },
        "scope": { "type": "workspace", "id": "1234567890123456789" },
        "name": "Quarterly report analysis",
        "status": "active",
        "kind": "user",
        "cost": { "credits": 15, "tokens": 1500 },
        "privacy": {
          "visibility": "private",
          "owner": { "type": "user", "id": "1234567890123456789" }
        },
        "created_at": "2026-07-07 16:00:00 UTC",
        "updated_at": "2026-07-07 16:30:05 UTC",
        "message_count": 5,
        "continuable": true,
        "latest_message": {
          "turn_id": "xYzAbCdEfGhIjKlMnO",
          "thread_id": "aBcDeFgHiJkLmNoPqR",
          "seq": 5,
          "status": "complete",
          "idempotency_key": "3f2a…",
          "query": { "text": "Summarize the quarterly report" },
          "error": null,
          "cost": { "credits": 3, "tokens": 300 },
          "created_at": "2026-07-07 16:30:00 UTC",
          "updated_at": "2026-07-07 16:30:05 UTC"
        }
      }
    ]
  }
}

Get chat details

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

The response is a thread object plus a separate turns collection (the message history) — there is no chat object and no embedded messages array.

{
  "result": true,
  "thread": {
    "thread_id": "aBcDeFgHiJkLmNoPqR",
    "creator": { "type": "user", "id": "1234567890123456789" },
    "scope": { "type": "workspace", "id": "1234567890123456789" },
    "name": "Quarterly report analysis",
    "status": "active",
    "kind": "user",
    "cost": { "credits": 15, "tokens": 1500 },
    "privacy": { "visibility": "private", "owner": { "type": "user", "id": "1234567890123456789" } },
    "created_at": "2026-07-07 16:00:00 UTC",
    "updated_at": "2026-07-07 16:30:05 UTC",
    "message_count": 3,
    "continuable": true
  },
  "turns": {
    "count": 1,
    "items": [
      {
        "turn_id": "xYzAbCdEfGhIjKlMnO",
        "thread_id": "aBcDeFgHiJkLmNoPqR",
        "seq": 1,
        "status": "complete",
        "idempotency_key": "3f2a…",
        "query": { "text": "Summarize the quarterly report" },
        "error": null,
        "cost": { "credits": 5, "tokens": 500 },
        "created_at": "2026-07-07 16:30:00 UTC",
        "updated_at": "2026-07-07 16:30:05 UTC"
      }
    ]
  }
}

The turns.items entries are the lightweight turn shape (no answer blob). Fetch a single turn’s full answer, citations, and action replay via Get message details below. turns is seq-ascending (oldest first).

Error responses:

Update a chat

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=Updated Chat Name"

Response (200 OK):

{ "result": true }

Error responses:

Delete a chat

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -X DELETE "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{ "result": true }

Error responses:

Deleted chats can be listed via GET .../ai/agent/list/deleted.

Send a follow-up message

Auth: Bearer token required. content_ai and ai_agent plan features required.

Also accepts the optional view, activity, role_in_org, and idempotency_key fields (see Advanced Per-Turn Fields above). There is no type parameter — the turn is appended to the existing thread.

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=How does that compare to Q2?"

Response (200 OK):

{
  "result": true,
  "turn_id": "mNoPqRsTuVwXyZaBcD",
  "thread_id": "aBcDeFgHiJkLmNoPqR",
  "seq": 2,
  "status": "pending",
  "idempotency_key": "7c1b…",
  "query": { "text": "How does that compare to Q2?" },
  "error": null,
  "cost": { "credits": 0, "tokens": 0 },
  "created_at": "2026-07-07 16:37:29 UTC",
  "updated_at": "2026-07-07 16:37:29 UTC"
}

The created turn’s fields are returned at the top level (not nested under a message object). The turn_id is the message id you poll or stream. status starts at pending; watch it reach a terminal state (see “Get message details”).

Error responses:

Cancel an in-progress message

Auth: Bearer token required. Workspace view permission. content_ai plan feature required (the cancel endpoint does not require ai_agent, so a tier downgrade mid-stream does not strand the message).

Body: Empty.

Request example:

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/ai/agent/{chat_id}/cancel/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{ "result": true }

The response is always { "result": true } — there is no success, message.id, or no_pending_message field. It is the same whether a pending turn was signalled or there was nothing in flight (idempotent no-op).

Behavior notes:

• Scoped to the live turn. The signal targets the thread’s lowest-seq non-terminal turn. A thread with no in-flight turn is a clean success no-op.
• Idempotent. Calling cancel twice in quick succession returns { "result": true } both times.
• Best-effort with bounded latency. The worker observes the cancel signal between streaming frames; observation typically happens within a few seconds. A turn that is between frames or already in post-processing may complete normally instead of cancelling.
• Partial billing. Tokens consumed up to the cancel point are charged (no refund), matching the behavior of streaming AI providers.
• SSE cancel signal. When the SSE read endpoint detects a cancellation it emits a single event: cancelled (empty data) followed by event: done and then closes the stream. SSE clients should listen for the dedicated cancelled event (e.g. eventSource.addEventListener('cancelled', …)) rather than scanning data payloads — the read endpoint does not forward any raw [CANCELLED] text on the wire.
• Turn status. After a successful cancel the affected turn reaches the cancelled terminal state and a new message can be sent immediately. There is no thread-level cancelled status.

Error responses:

List messages in a chat

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/messages/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "messages": {
    "count": 1,
    "items": [
      {
        "turn_id": "xYzAbCdEfGhIjKlMnO",
        "thread_id": "aBcDeFgHiJkLmNoPqR",
        "seq": 1,
        "status": "complete",
        "idempotency_key": "3f2a…",
        "query": { "text": "Summarize the quarterly report" },
        "error": null,
        "cost": { "credits": 5, "tokens": 500 },
        "created_at": "2026-07-07 16:30:00 UTC",
        "updated_at": "2026-07-07 16:30:05 UTC"
      }
    ]
  }
}

Each item is the lightweight turn shape (no answer blob) — see Message Object Schema. Fetch a turn’s full answer and citations via Get message details.

A numeric path segment after /messages/list/ is a pagination offset (e.g. .../messages/list/50).

Get message details

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/xYzAbCdEfGhIjKlMnO/details/" \
  -H "Authorization: Bearer {jwt_token}"

The turn detail is returned under a message object on the workspace endpoint and a turn object on the share endpoint. It carries the full turn shape plus the decompressed answer result blob and the replayable actions list.

Key response fields (under message / turn):

Read the answer only when status is complete (or handle needs_input as a clarifying question — see the SSE needs_input event).

The result blob (when present) includes the answer text, references, citations (see Citation Format below), the thought_transcript / commentary_transcript strings and their ordered thought_events / commentary_events lists (each event { order, text, ts }), and — for a needs_input turn — a clarification object { type: "clarification", question }.

The actions list is ordered by seq — each entry has seq (order), label (human-readable name, e.g. "Create File"), state (running, done, failed, or cancelled), affected_refs (ids the action touched), and started_at / ended_at timestamps:

{
  "message": {
    "turn_id": "xYzAbCdEfGhIjKlMnO",
    "thread_id": "aBcDeFgHiJkLmNoPqR",
    "seq": 1,
    "status": "complete",
    "query": { "text": "Summarize the quarterly report" },
    "error": null,
    "cost": { "credits": 5, "tokens": 500 },
    "result": {
      "answer": "The quarterly report shows revenue growth of 15%...",
      "citations": [
        {
          "hash": "a1b2c3d4",
          "nodeId": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf",
          "versionId": "v1abc-defgh-ijklm",
          "entries": [
            { "page": 3, "snippet": "Revenue increased by 15% year over year...", "timestamp": null }
          ]
        }
      ],
      "thought_transcript": "",
      "commentary_transcript": "",
      "thought_events": [],
      "commentary_events": []
    },
    "actions": [
      {
        "seq": 1,
        "label": "Create File",
        "state": "done",
        "affected_refs": ["aBcDeFgHiJkLmNoPqR"],
        "started_at": "2026-07-07 16:37:29 UTC",
        "ended_at": "2026-07-07 16:37:30 UTC"
      }
    ],
    "created_at": "2026-07-07 16:37:00 UTC",
    "updated_at": "2026-07-07 16:37:30 UTC"
  }
}

Error responses:

Stream message response (SSE)

Auth: Bearer token required. content_ai plan feature required.

Request example:

curl -N -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/xYzAbCdEfGhIjKlMnO/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Accept: text/event-stream"

SSE stream format:

event: data
data: {"item": "The quarterly report "}

event: data
data: {"item": "shows revenue growth of "}

event: data
data: {"item": "15% year over year."}

event: analysis_data
data: {"type": "analysis_chunk", ...}

event: table_data
data: {"type": "table_data", ...}

event: done

SSE event types:

Behavior:

• For a terminal turn (complete, failed, cancelled, lost, needs_input), the stored events are replayed immediately, followed by the matching terminal event, then the stream closes.
• For a running (or freshly pending) turn, the connection stays open and live-follows, emitting frames as the worker produces them. A single best-effort status frame is sent on connect so the client leaves its “connecting” state immediately.
• Resume is supported. Pass a Last-Event-ID header to resume after the last event you received; when the live stream has expired the events are synthesized from the canonical record.
• The connection auto-terminates after a bounded wait while a turn is still running (browsers auto-reconnect via EventSource and resume with Last-Event-ID).
• Headers include Cache-Control: no-cache, no-store, must-revalidate.
• This endpoint returns an SSE stream, NOT the standard JSON response envelope.

Error responses:

Publish a private chat

Auth: Bearer token required. content_ai plan feature required.

Response (200 OK):

{ "result": true }

Error responses:

Generate AI Share

Auth: Bearer token required. Workspace view permission. Does NOT require content_ai plan feature — available on all plans.

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/ai/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode 'files=["aBcDeFgHiJkLmN", "oPqRsTuVwXyZ12"]'

The endpoint reads form-encoded input (application/x-www-form-urlencoded). The files field value must be a JSON-encoded array of node opaque IDs. Do NOT send a JSON request body (Content-Type: application/json) — only form-encoded bodies are parsed.

Response (200 OK):

{
  "result": true,
  "markdown": "## Files\n\n### quarterly-report.pdf\n[Download](https://api.fast.io/...)\nSize: 2.5 MB\n\n..."
}

Notes:

• Download URLs expire after 5 minutes (300 seconds)
• Each token can be used a maximum of 3 times
• Individual files limited to 50 MB; total size limited to 100 MB
• When more than 5 files: titles only. 5 or fewer: includes full descriptions.
• The files input is a JSON array (not comma-separated strings)

Error responses:

List AI transactions

Results merge two sources into one most-recent-first feed: standalone AI operations (file summaries, title generation, indexing, and other one-off AI tasks) and completed agent conversation turns. Agent-turn entries carry type agent; standalone operations carry their operation type (e.g. chat_with_files, generate_title). In-progress turns are not included — only finished work appears.

Auth: Bearer token required. Workspace view permission. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/ai/transactions/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "count": 2,
  "items": [
    {
      "id": "txn_abc123",
      "type": "chat_with_files",
      "status": "complete",
      "tokens": 1500,
      "updated": "2025-06-15 10:30:05 UTC",
      "created": "2025-06-15 10:30:00 UTC"
    }
  ]
}

Asking a Question and Getting the Response

Complete workflow

1. Create the chat:

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/ai/agent/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=What were the Q3 revenue figures?"

The response includes thread.thread_id (the chat id) and turn.turn_id (the first message id). The AI begins processing asynchronously.

2. Wait for completion using activity polling (do NOT poll the message endpoint in a loop):

curl -X GET "https://api.fast.io/current/activity/poll/{workspace_id}?wait=95&lastactivity={timestamp}" \
  -H "Authorization: Bearer {jwt_token}"

Watch for the ai_chat:{chatId} activity key. This fires when the message state changes. The server holds the connection for up to 95 seconds and returns immediately when something changes.

3. Check message state:

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/ai/agent/{chat_id}/message/{message_id}/details/" \
  -H "Authorization: Bearer {jwt_token}"

Turn states: pending → running → complete (or the terminal failed, cancelled, lost, or needs_input). Only read the answer when the status is complete (handle needs_input as a clarifying question).

4. Stream the response:

curl -N -X GET "https://api.fast.io/current/workspace/{workspace_id}/ai/agent/{chat_id}/message/{message_id}/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Accept: text/event-stream"

Returns SSE with event types: data (text chunks), commentary (interim narration), status (turn-progress hints, before the agent’s first frame), analysis_data, table_data, needs_input (terminal: a single clarifying question instead of a full answer — present it and send the user’s reply as a new message), done.

5. Send follow-ups:

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/ai/agent/{chat_id}/message/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=How does that compare to Q2?"

Same polling flow for the reply.

Linking a user to an AI chat

Construct a workspace URL with a chat query parameter:

https://{org_domain}.fast.io/workspace/{workspace_name}?chat={chat_opaque_id}

The chat_opaque_id is the thread’s opaque id — returned as thread.thread_id when creating a chat, and as each item’s thread_id when listing chats.

Share AI Endpoints

Share AI endpoints follow the same pattern as workspace AI. Replace /workspace/{workspace_id} with /share/{share_id}.

Auto-generate OG image

Auth: Conditional. Public shares (Anyone / RegisteredUsers) need no authentication and get a custom AI-generated image. Private shares require Bearer auth and the ai_autoog plan feature; without valid permission or the feature, the endpoint falls back to the default private OG image (still HTTP 200 image data).

Error responses:

Auto-generate title and description

Auth: Bearer token required. Requires the ai_autotitle plan feature (not content_ai/ai_agent) — a plan without it is rejected.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/autotitle/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "title": "Q4 Financial Reports",
  "description": "Quarterly financial reports and analysis for fiscal year 2025.",
  "display_type": "document"
}

Error responses:

Share chat endpoints mirror workspace chat endpoints. All response formats and schemas are identical to the workspace versions documented above. The key differences are:

• Auth uses share permissions instead of workspace permissions
• File scope references share files instead of workspace files
• No AI Transactions endpoint (workspace-only)

Create a new chat (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai and ai_agent plan features required.

Share-context chats are always private — the privacy parameter is not accepted and visibility is fixed so guests do not see each other's AI conversations. Also accepts the optional view, activity, role_in_org, and idempotency_key fields.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/agent/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=What were the Q3 revenue figures?"

Response (200 OK):

Same { thread, turn } shape as the workspace create endpoint. thread.thread_id is the chat id; turn.turn_id is the first message id. See Create a new chat (workspace) above for the full field lists.

{
  "result": true,
  "thread": { "thread_id": "aBcDeFgHiJkLmNoPqR", "scope": { "type": "share", "id": "1234567890123456789" }, "status": "active", "kind": "user", "...": "..." },
  "turn": { "turn_id": "xYzAbCdEfGhIjKlMnO", "thread_id": "aBcDeFgHiJkLmNoPqR", "seq": 1, "status": "pending", "...": "..." }
}

Error responses:

List chats (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Query parameters:

Variant: Append /deleted to the path to list deleted chats: GET .../ai/agent/list/deleted

Request example:

curl -X GET "https://api.fast.io/current/share/1234567890123456789/ai/agent/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response: Same format as workspace chat list. See List chats above.

Get chat details (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response: Same format as workspace chat details. See Get chat details above.

Error responses:

Update a chat (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=Updated Chat Name"

Response (200 OK):

{ "result": true }

Error responses:

Delete a chat (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X DELETE "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{ "result": true }

Error responses:

Deleted chats can be listed via GET .../ai/agent/list/deleted.

Send a follow-up message (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai and ai_agent plan features required.

Also accepts the optional view, activity, role_in_org, and idempotency_key fields (see Advanced Per-Turn Fields above). There is no type parameter — the turn is appended to the existing thread.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=How does that compare to Q2?"

Response (200 OK):

{
  "result": true,
  "turn_id": "mNoPqRsTuVwXyZaBcD",
  "thread_id": "aBcDeFgHiJkLmNoPqR",
  "seq": 2,
  "status": "pending",
  "idempotency_key": "7c1b…",
  "query": { "text": "How does that compare to Q2?" },
  "error": null,
  "cost": { "credits": 0, "tokens": 0 },
  "created_at": "2026-07-07 16:37:29 UTC",
  "updated_at": "2026-07-07 16:37:29 UTC"
}

The created turn’s fields are returned at the top level (not nested under a message object). The turn_id is the message id you poll or stream. status starts at pending; watch it reach a terminal state (see “Get message details”).

Error responses:

Cancel an in-progress message (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required (the cancel endpoint does not require ai_agent).

Body: Empty.

Request example:

curl -X POST "https://api.fast.io/current/share/{share_id}/ai/agent/{chat_id}/cancel/" \
  -H "Authorization: Bearer {jwt_token}"

Response: { "result": true } — same as the workspace cancel endpoint (no success, message.id, or no_pending_message field). See Cancel an in-progress message above for the full behavior notes (idempotency, best-effort latency, partial billing, SSE cancelled event, and the affected turn reaching the cancelled terminal state).

Error responses:

List messages in a chat (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/messages/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response: Same format as workspace message list. See List messages in a chat above.

Get message details (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X GET "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/xYzAbCdEfGhIjKlMnO/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response: Same format as workspace message details. See Get message details above.

Error responses:

Stream message response (SSE) (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -N -X GET "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/message/xYzAbCdEfGhIjKlMnO/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Accept: text/event-stream"

SSE stream format and behavior: Identical to the workspace version. See Stream message response (SSE) above.

Error responses:

Publish a private chat (Share)

Auth: Bearer token required. Share view permission and chat permission. content_ai plan feature required.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/agent/aBcDeFgHiJkLmNoPqR/publish/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{ "result": true }

Error responses:

Generate AI Share (Share)

Auth: Bearer token required. Share view permission and download permission. Does NOT require content_ai plan feature — available on all plans.

Request example:

curl -X POST "https://api.fast.io/current/share/1234567890123456789/ai/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode 'files=["aBcDeFgHiJkLmN", "oPqRsTuVwXyZ12"]'

The endpoint reads form-encoded input (application/x-www-form-urlencoded). The files field value must be a JSON-encoded array of node opaque IDs. Do NOT send a JSON request body (Content-Type: application/json) — only form-encoded bodies are parsed.

Response (200 OK):

{
  "result": true,
  "markdown": "## Files\n\n### quarterly-report.pdf\n[Download](https://api.fast.io/...)\nSize: 2.5 MB\n\n..."
}

Notes:

• Download URLs expire after 5 minutes (300 seconds)
• Each token can be used a maximum of 3 times
• Individual files limited to 50 MB; total size limited to 100 MB
• When more than 5 files: titles only. 5 or fewer: includes full descriptions.
• The files input is a JSON array (not comma-separated strings)

Error responses:

Workspace AI vs. Share AI differences

AI Share File Download

Request example:

curl -X GET "https://api.fast.io/current/ai/share/aBcDeFgHiJkLmNoPqRsTuVwXyZ?file=0" \
  -o downloaded_file.pdf

Success response: Binary file data with appropriate Content-Type, Content-Disposition, Content-Length, and Accept-Ranges headers. Supports HTTP range requests.

Error responses:

All invalid/expired token errors return 404 to prevent token enumeration.

Semantic Search

The legacy endpoints below continue to work but will be removed in a future release.

Workspace Semantic Search (Deprecated)

Auth: Bearer token required. Workspace view permission. content_ai plan feature required.

Share Semantic Search (Deprecated)

This deprecated endpoint has no details parameter — node enrichment via details=true is a feature of /storage/search (below), not this endpoint. It also returns 1605 (Invalid Input) / 406 when workspace intelligence is not enabled.

Preferred approach — use /storage/search instead:

# Basic search
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=quarterly%20revenue&limit=10" \
  -H "Authorization: Bearer {jwt_token}"

# Search with full node details
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=quarterly%20revenue&details=true" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response_code": 200,
  "results": [
    {
      "content": "The quarterly revenue showed a 15% increase...",
      "score": 0.95,
      "node": {
        "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf",
        "type": "file",
        "name": "quarterly-report.pdf",
        "parent": "root",
        "size": 1048576,
        "mimetype": "application/pdf",
        "ai": { "state": "indexed", "attach": true, "summary": true }
      }
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Hybrid response fields (intelligence enabled):

When workspace intelligence is enabled, each file entry in the /storage/search response includes additional semantic fields:

Response with details=true (via /storage/search):

When using the preferred /storage/search endpoint with ?details=true, each file entry includes a node field with the full node resource:

{
  "result": true,
  "files": {
    "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf": {
      "name": "report.pdf",
      "parent_id": "...",
      "type": "file",
      "relevance_score": 0.92,
      "content_snippet": "Revenue increased 15%...",
      "match_source": "both",
      "mimetype": "application/pdf",
      "node": {
        "id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjf",
        "name": "report.pdf",
        "type": "file",
        "size": 123456,
        "previews": { "...": "..." },
        "ai": { "state": "indexed" }
      }
    }
  }
}

Error responses:

How to Phrase Questions

With folder/file scope (RAG)

Write questions that will match content in indexed files. The AI searches for relevant passages and cites them. Be specific.

• Good: “What were the revenue figures for Q3 2025 compared to Q2?”
• Good: “Summarize the key findings from the compliance audit reports”
• Bad: “Tell me about these files” — too vague, no searchable content to match

With file attachments

You can be more direct since the AI has the full file content.

• Good: “Describe this image in detail” (with an image attached)
• Good: “Extract all action items from this meeting transcript”
• Good: “Compare these two contracts and list the differences”

Chat Session Object Schema

The thread (chat) resource is returned as thread by the details endpoint and as each chats.items[] entry by the list endpoint. The details endpoint returns the message history separately as a turns collection — there is no embedded messages array on the thread.

There is no type, unique_creators, or efficiency field.

Message Object Schema

A message is a turn. The lightweight shape (list/details/mutation responses) carries the fields above the divider; the per-turn detail endpoint additionally returns result and actions.

There is no state, personality, response, author_name, or top-level text/citations/events field — the answer and its citations live inside the detail view’s result blob, and the processing state is status.

Citation Format

Citations appear inside a completed turn’s result blob (under result.citations / result.references), fetched from Get message details. They reference specific locations in files that informed the AI response.

Activity Polling for AI Chat Completion

Do NOT poll the message details endpoint in a loop. Use activity long-polling instead.

The server holds the connection for up to 95 seconds and returns immediately when something changes. Watch for the ai_chat:{chatId} activity key — this fires when the message state changes.

Pass the returned lastactivity timestamp into your next poll to receive only newer changes.

Anti-pattern: Do not GET .../ai/agent/{id}/message/{id}/details/ in a loop. Poll once on the workspace activity endpoint and wait for the ai_chat key.

Metadata Templates

Structured metadata for workspace files. Templates define schemas (fields, types, constraints) and have many-to-many relationships with files — a template can be applied to multiple files, and files can have metadata from multiple templates. Templates are managed at the workspace level.

The metadata feature is available on all plan tiers, with three distinct caps that scale by plan:

Listing, details, and preview endpoints return plan_node_limit, is_truncated, and an unfiltered count alongside the visible (capped) count, so consumers can render upsell messaging. Manual /nodes/add rejects requests that would exceed the per-template file cap. Auto-match silently truncates its candidate set to the remaining slots and incurs no LLM cost when the template is already at its cap. On downgrade, overflow rows are preserved but hidden; under truncation, the visible window is ordered by mapping creation order (oldest-mapped first), so the same files remain visible across plan changes and re-upgrade restores full visibility.

The field cap bounds the number of fields (columns) declared in a template's schema. It is enforced at every commit point that mutates the field set: create, update, and copy. Exceeding the cap returns 1605 (Invalid Input) with a message describing the attempted field count and the cap. The /details and /list endpoints surface the current declared field count as field_count and the per-plan ceiling as plan_field_limit (-1 when unlimited or unresolved).

Each template field also carries an autoextract boolean (defaults to true). Fields with autoextract=false are excluded from the default auto-extraction scope, which is useful for purely manual fields. Every template must have at least one field with autoextract=true; templates that opt every field out are rejected at create/update/copy. A full-row extract request that would yield an empty effective scope short-circuits with success and does not enqueue a job; an explicit fields array on the extract endpoint overrides the flag and is always honored.

Per-node autoextract eligibility is surfaced as an autoextractable boolean on both the metadata details endpoint (GET /workspace/{id}/storage/{node_id}/metadata/details/) and the template nodes listing (GET /workspace/{id}/metadata/templates/{tid}/nodes). It is true when the node is a non-trashed file with a completed AI summary — the same signal the extraction pipeline uses — and clients can use it to gate "extract now" affordances without making an extra probe.

Files are linked to templates either manually (add/remove endpoints) or automatically via AI-based matching. When intelligence is enabled, metadata is automatically extracted during file ingestion for documents, spreadsheets, images (PNG, JPEG, WebP), and code files.

Compact Responses (output=)

Every metadata endpoint that returns object-metadata, template, saved-view, or eligible-node records accepts an optional output query parameter that selects the shape of each record in the response. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 406. When output= is omitted, responses are full and byte-for-byte unchanged.

Object metadata (GET /workspace/{id}/storage/{node}/metadata/details/):

The key/value payload is the point of a metadata response, so terse keeps it. The savings come from trimming the nested node pointer — terse carries only the minimum identity fields needed to address the node in a follow-up call, standard adds parent and mimetype for list rendering, and full keeps the entire node resource.

Templates (GET /workspace/{id}/metadata/templates/list/, GET /workspace/{id}/metadata/templates/{tid}/details/):

deleted is included in standard so trash/restore workflows can surface the soft-delete timestamp without promoting to full.

Saved views (GET /workspace/{id}/metadata/views/):

Eligible nodes (GET /workspace/{id}/metadata/eligible/):

Unknown tokens are silently ignored. Add the markdown modifier (e.g. ?output=standard,markdown) to receive the response as GitHub-flavored Markdown (Content-Type: text/markdown; charset=UTF-8) instead of JSON — see the cross-cutting ?output= reference for the full contract.

Create a template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

There is no category parameter — the create endpoint accepts only name, description, and fields.

Field definition structure:

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/metadata/templates/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=Invoice+Template' \
  -d 'description=Metadata+schema+for+invoices' \
  -d 'fields=[{"name":"invoice_number","description":"Invoice number","type":"string","min":1,"max":50,"can_be_null":false},{"name":"amount","description":"Total amount","type":"float","min":0,"can_be_null":false}]'

Response (200 OK):

{
  "result": true,
  "template": {
    "id": "mt_aBcDeFgHiJkLmN",
    "instanceId": "1234567890123456789",
    "orgId": "9876543210987654321",
    "name": "Invoice Template",
    "description": "Metadata schema for invoices",
    "locked": false,
    "priority": null,
    "enabled": true,
    "deleted": null,
    "updated": "2025-01-20 10:30:00 UTC",
    "created": "2025-01-20 10:30:00 UTC",
    "fields": [
      {
        "name": "invoice_number",
        "description": "Invoice number",
        "type": "string",
        "min": 1,
        "max": 50,
        "fixed_list": [],
        "can_be_null": false
      }
    ]
  }
}

Newly created templates are active immediately — enabled is true for every template in current responses (there is no per-workspace enable/disable toggle).

Delete a template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Error responses:

List templates

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Optional path filter (append to URL): all (default, both system and custom), custom (non-system only), system (system only), enabled, or disabled.

Request example:

# List all templates
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/metadata/templates/list/" \
  -H "Authorization: Bearer {jwt_token}"

# List only enabled templates
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/metadata/templates/list/enabled/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "count": 2,
  "items": [
    {
      "id": "mt_aBcDeFgHiJkLmN",
      "instanceId": "1234567890123456789",
      "orgId": "9876543210987654321",
      "name": "Contract Template",
      "description": "Standard contract metadata fields",
      "locked": true,
      "priority": 3,
      "enabled": true,
      "deleted": null,
      "updated": "2025-01-15 08:00:00 UTC",
      "created": "2025-01-01 00:00:00 UTC",
      "fields": [
        {
          "name": "contract_type",
          "description": "Type of contract",
          "type": "string",
          "fixed_list": ["NDA", "MSA", "SOW"],
          "can_be_null": false
        }
      ]
    }
  ]
}

Get template details

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Update template definition

Auth: Bearer token required. Workspace member. Metadata billing feature required.

There is no category parameter.

Append /create/ to the path to copy the template instead of updating in place.

Response: Returns the updated template object. When the fields array changes in a way that invalidates stored values, the response additionally includes a schema_update object. Auto-triggered partial re-extraction runs only for: (a) new field names, and (b) type changes on existing names. Soft edits (description, min/max, nullable, fixed_list, regex) bump the schema hash but do not auto-trigger extraction — call the extract-all endpoint manually if you want those applied.

{
  "result": true,
  "template": { "...": "..." },
  "schema_update": {
    "previous_hash": 1234567890,
    "current_hash": 2345678901,
    "extraction_auto_enqueued": true,
    "added_fields": ["currency"],
    "type_changed_fields": ["total_amount"]
  }
}

The schema_update object is absent when only name or description change.

Template-Node Mapping

Templates have many-to-many relationships with files. Use these endpoints to manage which files are mapped to which templates.

Eligible nodes

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Add nodes to template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

The number of files mapped to a single template is capped per plan tier. When the request would push the template above its cap, the endpoint returns 1605 (Invalid Input) with a message describing the cap, the attempted count, and the remaining slots. Concurrent calls cannot collectively exceed the cap.

Remove nodes from template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

List nodes in template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Response (additional fields):

Pagination is clamped to the visible window: oversized limit values are silently shortened, and offsets past the visible window return an empty page. Existing pagination fields (items, count, next_cursor, has_more) are unchanged.

Preview template match

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Response (200 OK):

{
  "result": true,
  "matched_files": [
    {
      "node_id": "aBcDeFgHiJkLmN",
      "name": "invoice_2025.pdf",
      "mimetype": "application/pdf",
      "summary_title": "Invoice from Acme Corp",
      "summary_short": "Invoice INV-2025-001 for $1,500.00"
    }
  ],
  "total_eligible": 45,
  "total_scanned": 45,
  "total_matched": 1,
  "plan_node_limit": 10,
  "would_truncate_at": 1
}

Requires available AI credits. Only files with completed AI summaries and previews are eligible.

Suggest template fields

Auth: Bearer token required. Workspace member. Metadata billing feature required. Rate limited; concurrent calls per user+workspace return 409 Conflict.

Response (200 OK):

{
  "result": true,
  "suggested_fields": [
    {
      "name": "Location",
      "type": "string",
      "description": "Geographic location where the content was created",
      "max": 384,
      "can_be_null": true,
      "example_value": "New York, NY"
    },
    {
      "name": "Year",
      "type": "int",
      "description": "Year the document was created or published",
      "can_be_null": true,
      "example_value": 2024
    },
    {
      "name": "Priority",
      "type": "string",
      "description": "Priority level of the task",
      "max": 384,
      "can_be_null": false,
      "fixed_list": ["low", "medium", "high"],
      "example_value": "medium"
    }
  ],
  "file_sample_count": 25
}

Requires available AI credits. The json field type is not returned by this endpoint. example_value is a preview hint only and is not part of the create-template field schema; clients should strip it before posting to create-template (passing it through is harmless as unknown keys are ignored).

Auto-match files to template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Optional body parameters:

Response (200 OK) — new job enqueued:

{
  "result": true,
  "job_id": "aj_aBcDeFgHiJkLmN",
  "status": "queued",
  "message": "Template matching job enqueued"
}

Response (200 OK) — duplicate job already running:

{
  "result": true,
  "status": "duplicate",
  "message": "A template matching job is already in progress for this template"
}

The matched set is silently capped at the workspace's per-template node cap. Eligible files are truncated pre-batch (so no LLM credit is spent on candidates that cannot be persisted) and re-checked immediately before persistence to handle interleaved manual adds. When the template is already at its cap, the job completes successfully with no LLM usage.

Batch extract metadata (template-level)

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Response (200 OK):

{
  "result": true,
  "job_id": "aj_aBcDeFgHiJkLmN",
  "template_id": "mt_oPqRsTuVwXyZ12"
}

Maximum 1,000 files processed per job.

Template Assignments (folder-level)

Templates can be assigned to individual folder nodes (or workspace-level), independently of the per-file node map. These endpoints manage those folder assignments.

Assign a template to a folder

Auth: Bearer token required. Workspace admin permission. Metadata billing feature required.

Response (200 OK):

{
  "result": true,
  "node_id": "aBcDeFgHiJkLmN",
  "template_id": "9876543210987654321"
}

node_id echoes what you sent (null for a workspace-level assignment). If the node is already mapped to the template the call succeeds as a no-op.

Error responses:

List template assignments

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Response (200 OK):

{
  "result": true,
  "count": 1,
  "items": [
    {
      "template_id": "mt_aBcDeFgHiJkLmN",
      "name": "Invoice Template",
      "created": "2026-07-07 16:00:00 UTC",
      "updated": "2026-07-07 16:30:00 UTC"
    }
  ]
}

Error responses:

Resolve the effective template for a node

Auth: Bearer token required. Workspace member. Metadata billing feature required.

{node_id} is a path segment (a storage node opaque id).

Response (200 OK):

{
  "result": true,
  "template": {
    "id": "mt_aBcDeFgHiJkLmN",
    "name": "Invoice Template",
    "fields": []
  }
}

When the node has no mapped template the response is { "result": true, "template": null }. The template object, when present, is the full template resource (see Template Resource Schema).

Unassign a template from a folder

Auth: Bearer token required. Workspace admin permission. Metadata billing feature required.

Response (200 OK):

{ "result": true }

Error responses:

Node Metadata

Metadata stored on individual files. Split into template metadata (conforming to mapped templates) and custom metadata (user-defined fields).

Get file metadata

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Request example:

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/aBcDeFgHiJkLmN/metadata/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "instance_id": "1234567890123456789",
  "object_id": "aBcDeFgHiJkLmN",
  "template_id": "mt_oPqRsTuVwXyZ12",
  "node_id": {
    "id": "aBcDeFgHiJkLmN",
    "name": "invoice_2025.pdf",
    "type": "file",
    "size": 245760
  },
  "metadata": [
    {
      "key": "invoice_number",
      "description": "Invoice number",
      "type": "string",
      "value": "INV-2025-001",
      "is_auto": false,
      "updated": "2025-01-20 10:30:00 UTC"
    },
    {
      "key": "amount",
      "description": "Invoice amount",
      "type": "float",
      "value": 1500.00,
      "is_auto": true,
      "updated": "2025-01-20 10:30:00 UTC"
    }
  ]
}

Bulk Form

The metadata details endpoint accepts a comma-separated list of node ids in place of a single {node_id}:

GET /current/workspace/{workspace_id}/storage/{id1},{id2},{id3}/metadata/details/

Up to 25 ids per call. Duplicate ids are silently deduplicated. Empty segments (e.g. trailing comma) return 400.

The bulk response shape differs from the single-id form. Successfully resolved objects appear under objects; per-id failures appear in a parallel errors array. Template definitions are hoisted to a top-level templates map keyed by template_id so a template shared by N objects is returned once instead of N times — clients look up each object's template via the template_id it carries. HTTP status is 200 when at least one object resolves and 404 when every requested id errored.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/abc123,def456,ghi789/metadata/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (HTTP 200)

{
  "result": true,
  "format": "multi",
  "objects": [
    {
      "instance_id": "1234567890123456789",
      "object_id": "abc123",
      "template_id": "mt_oPqRsTuVwXyZ12",
      "node_id": { "id": "abc123", "name": "invoice_2025.pdf", "type": "file" },
      "template_metadata": [
        { "key": "invoice_number", "description": "Invoice number", "type": "string", "value": "INV-2025-001", "is_auto": false, "updated": "2025-01-20 10:30:00 UTC" }
      ],
      "custom_metadata": [],
      "autoextractable": true
    },
    {
      "instance_id": "1234567890123456789",
      "object_id": "def456",
      "template_id": "mt_oPqRsTuVwXyZ12",
      "node_id": { "id": "def456", "name": "invoice_2026.pdf", "type": "file" },
      "template_metadata": [
        { "key": "invoice_number", "description": "Invoice number", "type": "string", "value": "INV-2026-014", "is_auto": true, "updated": "2026-02-04 09:12:00 UTC" }
      ],
      "custom_metadata": [],
      "autoextractable": true
    }
  ],
  "templates": {
    "mt_oPqRsTuVwXyZ12": {
      "template_id": "mt_oPqRsTuVwXyZ12",
      "name": "Invoice",
      "fields": [
        { "name": "invoice_number", "type": "string", "description": "Invoice number" }
      ]
    }
  },
  "errors": [
    { "node_id": "ghi789", "code": 191049, "message": "Storage node not found" }
  ]
}

errors is always an array (possibly empty); templates is always an object/map (possibly empty {}).

Request-level Errors (whole request fails)

Per-id Error Codes (inside each errors[] entry)

The request itself is HTTP 200 unless every id errored. Each entry in errors[] carries one of:

Update file metadata

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Request example:

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/aBcDeFgHiJkLmN/metadata/update/mt_oPqRsTuVwXyZ12/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'key_values={"invoice_number":"INV-2025-001","amount":1500.00}'

Existing metadata for the same keys is overwritten. Keys not included in the request are left unchanged.

Delete file metadata

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Only files and notes support metadata — folders return an error.

Extract metadata (single file)

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Response (HTTP 202 Accepted):

{
  "result": true,
  "job_id": "{job_id}",
  "template_id": "{template_id}",
  "node_id": "{node_id}",
  "fields": ["amount", "due_date"],
  "status": "queued",
  "status_uri": "/workspace/{workspace_id}/jobs/status"
}

status is queued for a fresh job, or in_progress when the request is collapsed into an already-running job (see idempotent retries below).

Idempotent retries: submitting the same (node, template, fields) combination while a job is already in flight returns the existing job_id instead of enqueueing a duplicate. Retries within a 30-minute window are safe.

Polling flow:

POST /current/workspace/{id}/storage/{node}/metadata/extract/
  template_id={template_id}
  -> HTTP 202
     { "job_id": "{job_id}", "status": "queued",
       "status_uri": "/workspace/{id}/jobs/status" }

GET  /current/workspace/{id}/jobs/status/
  -> jobs.metadata_extract[] includes
     { "kind": "single",
       "active": true,
       "node_id": "{node_id}",
       "template_id": "{template_id}",
       "job_id": "{job_id}",
       "status": "in_progress",
       "progress_percent": 0 }

GET  /current/workspace/{id}/jobs/status/     (later)
  -> entry now { "status": "completed",
                 "progress_percent": 100,
                 "completed_at": ... }

GET  /current/workspace/{id}/storage/{node}/metadata/details/
  -> extracted values under `template_metadata`

Error responses:

Batch extract metadata for a folder

Auth: Bearer token required. Workspace admin permission. Metadata billing feature required. Conservative throttle (these operations are expensive).

{node_id} is a folder node opaque id, or the literal root alias for the workspace root.

Response (200 OK):

{
  "result": true,
  "job_id": "aj_aBcDeFgHiJkLmN",
  "template_id": "mt_oPqRsTuVwXyZ12"
}

The job runs asynchronously against the workspace’s active template — poll GET /current/workspace/{workspace_id}/jobs/status/ (the jobs.metadata_extract[] array) for progress.

Error responses:

List metadata by template

Auth: Bearer token required. Workspace member. Metadata billing feature required.

List templates in use

Auth: Bearer token required. Workspace member. Metadata billing feature required.

Metadata versions

Metadata Saved Views

Each user can persist per-template column order, column visibility, and sort preferences. Saved views are private to the user — two users can independently customize the same template. Identity is the tuple (workspace, user, template); there is at most one saved view per user per template per workspace. Full endpoint reference is in the Storage Operations docs.

Auth required. Workspace member. Metadata billing feature required.

POST body: application/x-www-form-urlencoded with template_id (string) and config (JSON-encoded string containing the view config). Do NOT send as application/json — the endpoint only accepts form-encoded bodies and returns 406 (This field is missing) for JSON bodies. The config schema (the JSON serialized into the form field) is { version: 1, columns: [{field, visible?, width?}], sort: {field, dir}, filters: [{field, operator, value_type, value}] }; column array order IS the display order; dir is asc or desc; filters are AND-chained, max 5 per view, with operator in = != < <= > >= and value_type in string | int | float | bool (json rejected). Each saved-view filter entry uses field for its template-field identifier (matching columns[].field and sort.field); the nodes endpoint's stateless filters query parameter keeps its pre-existing key form, and the server handles the translation when auto-applying a saved view. Unknown keys are rejected with 1605 (Invalid Input). See the Storage Operations docs for the full filter contract.

The template nodes listing endpoint (GET /workspace/{workspace_id}/metadata/templates/{template_id}/nodes) auto-applies config.sort and config.filters from the caller's saved view when the corresponding sort_field / filters query parameters are not passed explicitly. An explicit query parameter (even empty) always wins; no server-side merge.

A saved view can also be exported to a TSV file: POST /workspace/{workspace_id}/metadata/view/{template_id}/export/ queues an asynchronous export written to workspace storage, applying the view's columns, sort, and filters. A saved view must already exist for that template. The export runs in the background — poll the destination folder for the resulting file. See the Storage Operations docs for the export parameters, deduplication behavior, and row limit.

Jobs Status (Unified Async Processing)

A single endpoint to check the status of all async processing jobs (AI indexing, metadata extraction) for a workspace or share. Replaces the removed metadata/intelligence/status and metadata/templates/{id}/extract-status endpoints.

Response (200 OK):

{
  "result": true,
  "jobs": {
    "intelligence": {
      "active": true,
      "status": "ingesting",
      "direction": "enable",
      "total_files": 100,
      "eligible_files": 80,
      "processed": 30,
      "skipped": 5,
      "failed": 0,
      "progress_percent": 37,
      "started_at": 1711500000,
      "updated_at": 1711500300,
      "completed_at": null,
      "stop_reason": null
    },
    "metadata_extract": [
      {
        "kind": "batch",
        "active": true,
        "template_id": "1234567890123456789",
        "node_id": null,
        "job_id": "{batch_job_id}",
        "status": "extracting",
        "total_files": 50,
        "eligible_files": 40,
        "processed": 24,
        "skipped": 2,
        "failed": 0,
        "progress_percent": 60,
        "started_at": 1711500000,
        "updated_at": 1711500200,
        "completed_at": null,
        "stop_reason": null,
        "error_message": null,
        "fields_scope": ["name", "date", "amount"]
      },
      {
        "kind": "single",
        "active": true,
        "template_id": "1234567890123456789",
        "node_id": "{node_id}",
        "job_id": "{job_id}",
        "status": "in_progress",
        "total_files": 1,
        "eligible_files": 1,
        "processed": 0,
        "skipped": 0,
        "failed": 0,
        "progress_percent": 0,
        "started_at": 1711500400,
        "updated_at": 1711500400,
        "completed_at": null,
        "stop_reason": null,
        "error_message": null,
        "fields_scope": ["amount", "due_date"]
      }
    ]
  }
}

Both intelligence and extraction entries share the common progress fields (active, total_files, eligible_files, processed, skipped, failed, progress_percent, started_at, updated_at, completed_at, stop_reason). For kind: "single" entries, total_files and eligible_files are always 1 and progress_percent is 0 while pending or 100 on completion. Completed or errored entries older than one hour are hidden from the listing.

Real-time updates: Both job types broadcast via the Activity/WebSocket system. Clients subscribed to the workspace or share WebSocket channel receive activity notifications when progress changes, reducing the need for polling.

Template Resource Schema

The template resource does not include a category field.

Supported Field Types

Quick Reference

Create a chat and get the answer

POST /current/workspace/{id}/ai/agent/
  question=...
  -> thread.thread_id, turn.turn_id

GET  /current/activity/poll/{id}?wait=95&lastactivity=...
  -> wait for ai_chat:{chatId}

GET  /current/workspace/{id}/ai/agent/{chat_id}/message/{turn_id}/details/
  -> check status == complete

GET  /current/workspace/{id}/ai/agent/{chat_id}/message/{turn_id}/read/
  -> SSE stream: data, commentary, status, analysis_data, table_data, done

Create a note (bank knowledge for RAG)

POST /current/workspace/{id}/storage/{parent}/createnote/
  name=research-notes.md&content=...

Extract metadata from a file (async)

POST /current/workspace/{id}/storage/{node}/metadata/extract/
  template_id={template_id}
  -> HTTP 202 { job_id, status: "queued" | "in_progress" }

GET  /current/workspace/{id}/jobs/status/
  -> jobs.metadata_extract[] (kind: "single") reaches status: "completed"

GET  /current/workspace/{id}/storage/{node}/metadata/details/
  -> extracted values

List eligible nodes for metadata (files and notes)

GET /current/workspace/{id}/metadata/eligible/

Add nodes to a template (files and notes)

POST /current/workspace/{id}/metadata/templates/{template_id}/nodes/add/
  node_ids=["nodeId1","nodeId2"]

AI auto-match files to a template

POST /current/workspace/{id}/metadata/templates/{template_id}/auto-match/

Batch extract metadata for all files in a template

POST /current/workspace/{id}/metadata/templates/{template_id}/extract-all/
  -> returns job_id (rate limited)

Check status of all async jobs (intelligence + metadata extraction)

GET /current/workspace/{id}/jobs/status/
GET /current/share/{id}/jobs/status/
  -> returns jobs.intelligence and jobs.metadata_extract[]

Semantic search (use /storage/search instead — /ai/search is deprecated)

GET /current/workspace/{id}/storage/search/?search=quarterly+revenue&limit=10
GET /current/workspace/{id}/storage/search/?search=quarterly+revenue&details=true

Optional details=true includes full node resource (previews, AI state, metadata, size) per result. Default limit drops to 10 when details enabled.

Share AI chat (same workflow as workspace)

POST /current/share/{id}/ai/agent/
  question=...
  -> thread.thread_id, turn.turn_id

GET  /current/share/{id}/ai/agent/{chat_id}/message/{turn_id}/details/
  -> check status == complete

GET  /current/share/{id}/ai/agent/{chat_id}/message/{turn_id}/read/
  -> SSE stream: data, commentary, status, analysis_data, table_data, done

Share-specific AI

GET  /current/share/{id}/ai/autoog/
  -> binary PNG image (OG image)

POST /current/share/{id}/ai/autotitle/
  -> title, description, display_type

POST /current/share/{id}/ai/share/
  files=["opaqueId1","opaqueId2"]
  -> markdown with download URLs