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

Overview

Fast.io 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

AI chat is read-only. It can read, analyze, search, and answer questions about files, but it cannot modify files, change settings, manage members, or access events. All write operations must be done through the API directly.

Intelligence Setting

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

• intelligence=true (default for agent accounts) — Files are auto-indexed for semantic search, summarization, and citation. Required for chat_with_files type chats with file/folder scope.
• intelligence=false — Files are stored/shared without RAG indexing. You can still use chat type with files_attach for direct file analysis.

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:

Warning: Intelligence cannot be re-enabled once disabled. Disabling is permanent.

Chat Types

Two chat types are available. Both augment answers with web knowledge.

chat — General AI Conversation

• Does not use RAG or workspace file indexing
• Works regardless of the workspace intelligence setting
• You can attach files directly via files_attach for one-off analysis (e.g., “Describe this image”, “Summarize this PDF”)
• Any file with a ready preview or AI summary can be attached

chat_with_files — RAG-Powered Chat

• Searches indexed files in the workspace/share (or a scoped folder/file set)
• Returns answers with citations to specific files, pages, and text snippets
• Requires the workspace/share intelligence setting to be enabled when using file/folder scope
• Default scope is the entire workspace/share — omit scope parameters to search all indexed files
• Only files with ai_state: ready are included in searches

File Scope vs File Attachments

These are two different ways to give the AI context. They cannot be combined in the same request.

Folder/File Scope (files_scope, folders_scope)

Limits the RAG search space. The AI searches indexed files within the specified scope and uses matching content as citations.

• Default scope is the entire workspace/share — omit both files_scope and folders_scope to search all indexed files
• Only files with ai_state: ready are included
• Only used with chat_with_files type

files_scope — comma-separated nodeId:versionId pairs (max 100). Both nodeId and versionId are required and must be non-empty in each pair. Get the versionId from the file’s version field in storage list/details responses.

folders_scope — comma-separated nodeId:depth pairs (max 100 subfolder references). Depth controls how many levels of subfolders are enumerated (1–10). Only subfolder references count toward the limit, not individual files. The RAG backend searches all indexed files within the scoped folders automatically.

You do not need to enumerate individual files. Just provide top-level folder IDs with depth.

File Attachments (files_attach)

Files are directly attached to the chat message for analysis. Use this for direct analysis tasks. Only file nodes are accepted—folder nodes are rejected. To include folder contents, use folders_scope instead.

• Files must have AI summaries ready (be in a “ready” state or eligible for summarization)
• Max 20 files, 200 MB total (effective size after preview optimization)
• Works with both chat and chat_with_files types
• Good for: “Describe this image”, “Extract action items from this transcript”, “Compare these two contracts”

Format: comma-separated nodeId:versionId pairs, e.g., files_attach=nodeId1:versionId1,nodeId2:versionId2

Choosing Between Scope and Attachments

AI State (File Readiness)

Files in an intelligent workspace progress through AI processing states:

Only files with ai_state: ready are included in RAG folder/file scope searches. Check a file’s AI state in the ai.state field of storage list or file details responses.

Personality Parameter

The personality parameter controls the length and style of AI responses. Pass it when creating a chat or sending a message.

You can also control verbosity 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”

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 plan feature required.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day (per workspace + user).

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "chat": {
      "id": "aBcDeFgHiJkLmNoPqR",
      "message": {
        "id": "xYzAbCdEfGhIjKlMnO"
      }
    }
  },
  "current_api_version": "1.0"
}

Error responses:

List chats

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

Rate limits: 3/1s, 10/10s, 20/60s, 50/hr, 200/day.

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

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "chats": [
      {
        "chat_id": "aBcDeFgHiJkLmNoPqR",
        "creator": { "type": "user", "id": "12345678901234567890" },
        "type": "chat_with_files",
        "name": "Quarterly report analysis",
        "status": "active",
        "message_count": 5,
        "latest_message": {
          "message_id": "xYzAbCdEfGhIjKlMnO",
          "creator": { "type": "user", "id": "12345678901234567890" },
          "state": "complete",
          "message": { "text": "Summarize the quarterly report" },
          "response": null,
          "created": "2025-06-15T10:30:00Z",
          "updated": "2025-06-15T10:30:05Z"
        },
        "unique_creators": [
          { "type": "user", "id": "12345678901234567890" }
        ],
        "cost": { "credits": { "tokens": 1500 } },
        "efficiency": "good",
        "privacy": {
          "visibility": "private",
          "owner": { "type": "user", "id": "12345678901234567890" }
        },
        "created_at": "2025-06-15T10:00:00Z",
        "updated_at": "2025-06-15T10:30:05Z"
      }
    ]
  },
  "current_api_version": "1.0"
}

Get chat details

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 100/10s, 350/60s, 2000/hr.

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "chat": {
      "chat_id": "aBcDeFgHiJkLmNoPqR",
      "creator": { "type": "user", "id": "12345678901234567890" },
      "type": "chat_with_files",
      "name": "Quarterly report analysis",
      "status": "active",
      "message_count": 3,
      "messages": [
        {
          "chat_id": "aBcDeFgHiJkLmNoPqR",
          "message_id": "xYzAbCdEfGhIjKlMnO",
          "creator": { "type": "user", "id": "12345678901234567890" },
          "personality": "detailed",
          "state": "complete",
          "message": {
            "text": "Summarize the quarterly report",
            "author_name": "John",
            "scope": {},
            "attached": []
          },
          "response": {
            "text": "The quarterly report shows revenue growth of 15%...",
            "error": false,
            "created": "2025-06-15T10:30:05Z",
            "cost": { "tokens": 500, "details": {} },
            "author_name": "Ripley",
            "events": [],
            "table_data": [],
            "analysis_chunks": [],
            "citations": [
              {
                "hash": "a1b2c3d4",
                "nodeId": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
                "versionId": "v1abc-defgh-ijklm",
                "entries": [
                  { "page": 3, "snippet": "Revenue increased by 15% year over year...", "timestamp": null }
                ]
              }
            ]
          },
          "created": "2025-06-15T10:30:00Z",
          "updated": "2025-06-15T10:30:05Z"
        }
      ],
      "unique_creators": [ { "type": "user", "id": "12345678901234567890" } ],
      "cost": { "credits": { "tokens": 1500 } },
      "efficiency": "good",
      "privacy": { "visibility": "private", "owner": { "type": "user", "id": "12345678901234567890" } },
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2025-06-15T10:30:05Z"
    }
  },
  "current_api_version": "1.0"
}

Error responses:

Update a chat

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day.

Request example:

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

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

Error responses:

Delete a chat

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 3/1s, 20/10s, 50/60s, 250/hr, 500/day.

Request example:

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

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

Error responses:

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

Send a follow-up message

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 10/10s, 20/60s, 500/hr.

The chat type is inherited from the chat itself — you do not need to specify type again.

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "message": {
      "id": "mNoPqRsTuVwXyZaBcD"
    }
  },
  "current_api_version": "1.0"
}

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/12345678901234567890/ai/chat/aBcDeFgHiJkLmNoPqR/messages/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": "yes",
  "response": {
    "messages": [
      {
        "chat_id": "aBcDeFgHiJkLmNoPqR",
        "message_id": "xYzAbCdEfGhIjKlMnO",
        "creator": { "type": "user", "id": "12345678901234567890" },
        "personality": "detailed",
        "state": "complete",
        "message": {
          "text": "Summarize the quarterly report",
          "author_name": "John",
          "scope": {},
          "attached": []
        },
        "response": {
          "text": "The quarterly report shows...",
          "error": false,
          "created": "2025-06-15T10:30:05Z",
          "cost": { "tokens": 500, "details": {} },
          "author_name": "Ripley",
          "events": [],
          "table_data": [],
          "analysis_chunks": [],
          "citations": []
        },
        "created": "2025-06-15T10:30:00Z",
        "updated": "2025-06-15T10:30:05Z"
      }
    ]
  },
  "current_api_version": "1.0"
}

Get message details

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 200/60s, 2000/hr.

Key response fields:

Only read the response when state is complete.

Error responses:

Stream message response (SSE)

Auth: Bearer token required. content_ai plan feature required.

Rate limits: 5/3s, 20/10s, 100/60s, 700/hr.

Request example:

curl -N -X GET "https://api.fast.io/current/workspace/12345678901234567890/ai/chat/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:

• The message must be in in_progress or complete state
• For completed messages, all existing chunks are sent immediately followed by done
• For in-progress messages, the connection stays open and polls for new chunks at intervals (~5 seconds)
• The connection auto-terminates after a maximum wait time
• 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.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day.

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

Error responses:

Generate AI Share

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

Rate limits: 5/min, 100/hr (per user).

Request example:

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/ai/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"files": ["aBcDeFgHiJkLmN", "oPqRsTuVwXyZ12"]}'

Response (200 OK):

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

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

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

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "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"
      }
    ]
  },
  "current_api_version": "1.0"
}

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/chat/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "question=What were the Q3 revenue figures?" \
  -d "type=chat_with_files" \
  -d "personality=detailed"

Response includes chat_id and 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/chat/{chat_id}/message/{message_id}/details/" \
  -H "Authorization: Bearer {jwt_token}"

Message states: ready → in_progress → complete (or errored). Only read the response when state is complete.

4. Stream the response:

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

Returns SSE with event types: data (text chunks), analysis_data, table_data, done.

5. Send follow-ups:

curl -X POST "https://api.fast.io/current/workspace/{workspace_id}/ai/chat/{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 returned in the chat_id field when creating or 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 — required for private shares; optional for public shares.

Rate limits (private shares only): 1,000/10min, 20,000/day.

Error responses:

Auto-generate title and description

Auth: Bearer token required.

Rate limits: 1,000/10min, 5,000/day.

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "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 plan feature required.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day (per share + user).

Request example:

curl -X POST "https://api.fast.io/current/share/12345678901234567890/ai/chat/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "type=chat_with_files" \
  -d "question=What were the Q3 revenue figures?" \
  -d "privacy=private" \
  -d "personality=detailed"

Response (200 OK):

{
  "result": "yes",
  "response": {
    "chat": {
      "id": "aBcDeFgHiJkLmNoPqR",
      "message": {
        "id": "xYzAbCdEfGhIjKlMnO"
      }
    }
  },
  "current_api_version": "1.0"
}

Error responses:

List chats (Share)

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

Rate limits: 3/1s, 10/10s, 20/60s, 50/hr, 200/day.

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

Request example:

curl -X GET "https://api.fast.io/current/share/12345678901234567890/ai/chat/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.

Rate limits: 10/1s, 60/10s, 150/60s, 1000/hr.

Request example:

curl -X GET "https://api.fast.io/current/share/12345678901234567890/ai/chat/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.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day.

Request example:

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

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

Error responses:

Delete a chat (Share)

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

Rate limits: 3/1s, 20/10s, 50/60s, 250/hr, 500/day.

Request example:

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

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

Error responses:

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

Send a follow-up message (Share)

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

Rate limits: 10/10s, 20/60s, 500/hr.

The chat type is inherited from the chat itself — you do not need to specify type again.

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "message": {
      "id": "mNoPqRsTuVwXyZaBcD"
    }
  },
  "current_api_version": "1.0"
}

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/12345678901234567890/ai/chat/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.

Rate limits: 200/60s, 2000/hr.

Request example:

curl -X GET "https://api.fast.io/current/share/12345678901234567890/ai/chat/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.

Rate limits: 5/3s, 20/10s, 100/60s, 700/hr.

Request example:

curl -N -X GET "https://api.fast.io/current/share/12345678901234567890/ai/chat/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.

Rate limits: 1/1s, 5/10s, 10/60s, 50/hr, 200/day.

Request example:

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

Response (200 OK):

{ "result": "yes", "current_api_version": "1.0" }

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.

Rate limits: 5/min, 100/hr (per user).

Request example:

curl -X POST "https://api.fast.io/current/share/12345678901234567890/ai/share/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"files": ["aBcDeFgHiJkLmN", "oPqRsTuVwXyZ12"]}'

Response (200 OK):

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

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

Rate limits: 60/min, 300/hr (per IP).

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.

Rate limits: 2/1s, 10/10s, 30/60s, 200/hr, 1000/day.

Share Semantic Search (Deprecated)

Preferred approach — use /storage/search instead:

# Basic search
curl -X GET "https://api.fast.io/current/workspace/12345678901234567890/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/12345678901234567890/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-rpjfm4",
        "type": "file",
        "name": "quarterly-report.pdf",
        "parent": "root",
        "size": 1048576,
        "mimetype": "application/pdf",
        "ai": { "state": "ready", "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": "yes",
  "response": {
    "files": {
      "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4": {
        "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-rpjfm4",
          "name": "report.pdf",
          "type": "file",
          "size": 123456,
          "previews": { "...": "..." },
          "ai": { "state": "ready" }
        }
      }
    }
  }
}

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 chat resource is returned by details and list endpoints.

Message Object Schema

Citation Format

Citations 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/chat/{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 with plan-based limits (Free: 1, Pro: 1, Business: 10).

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.

Create a template

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

Rate limits: 10/min, 100/hr, 300/day.

Field definition structure:

Request example:

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/metadata/templates/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=Invoice+Template' \
  -d 'description=Metadata+schema+for+invoices' \
  -d 'category=financial' \
  -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": "yes",
  "response": {
    "template": {
      "id": "mt_aBcDeFgHiJkLmN",
      "instanceId": "12345678901234567890",
      "orgId": "98765432109876543210",
      "category": "financial",
      "name": "Invoice Template",
      "description": "Metadata schema for invoices",
      "locked": false,
      "priority": null,
      "enabled": false,
      "deleted": null,
      "updated": "2025-01-20 10:30:00",
      "created": "2025-01-20 10:30:00",
      "fields": [
        {
          "name": "invoice_number",
          "description": "Invoice number",
          "type": "string",
          "min": 1,
          "max": 50,
          "fixed_list": [],
          "can_be_null": false
        }
      ]
    }
  },
  "current_api_version": "1.0"
}

Newly created templates start with enabled: false. Use the settings endpoint to enable them.

Delete a template

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

Rate limits: 10/min, 100/hr, 300/day.

Error responses:

List templates

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

Rate limits: 3/1s, 10/10s, 20/60s, 50/hr, 200/day.

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/12345678901234567890/metadata/templates/list/" \
  -H "Authorization: Bearer {jwt_token}"

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

Response (200 OK):

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

Get template details

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

Rate limits: 3/1s, 10/10s, 20/60s, 50/hr, 200/day.

Update template settings

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

Rate limits: 20/min, 100/hr, 500/day.

Error responses:

Update template definition

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

Rate limits: 10/min, 100/hr, 300/day.

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

Template-Node Mapping

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

Eligible files

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

Rate limits: 10/min, 100/hr, 500/day.

Add files to template

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

Rate limits: 10/min, 100/hr, 300/day.

Remove files from template

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

Rate limits: 10/min, 100/hr, 300/day.

List files in template

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

Rate limits: 10/min, 100/hr, 500/day.

Auto-match files to template

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

Rate limits: 2/min, 10/hr.

Batch extract metadata (template-level)

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

Rate limits: 2/min, 10/hr.

Response (200 OK):

{
  "result": "yes",
  "response": {
    "job_id": "aj_aBcDeFgHiJkLmN",
    "template_id": "mt_oPqRsTuVwXyZ12"
  }
}

Maximum 1,000 files processed per job.

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.

Rate limits: 5000/hr, 25000/day.

Request example:

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

Response (200 OK):

{
  "result": "yes",
  "response": {
    "instance_id": "12345678901234567890",
    "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"
      },
      {
        "key": "amount",
        "description": "Invoice amount",
        "type": "float",
        "value": 1500.00,
        "is_auto": true,
        "updated": "2025-01-20 10:30:00"
      }
    ]
  },
  "current_api_version": "1.0"
}

Update file metadata

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

Rate limits: 250/hr, 1000/day.

Request example:

curl -X POST "https://api.fast.io/current/workspace/12345678901234567890/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.

Rate limits: 20/min, 100/hr, 500/day.

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

Extract metadata (single file)

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

Rate limits: 10/min, 100/hr, 300/day.

Supports documents, spreadsheets, images (PNG, JPEG, WebP), and code files. Extraction is synchronous. Extracted values are stored with is_auto: true.

Error responses:

List metadata by template

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

Rate limits: 100/min, 1000/hr, 3000/day.

List templates in use

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

Rate limits: 100/min, 400/hr, 1500/day.

Metadata versions

Metadata views

Save, list, and delete custom views for metadata display.

Create/update a view

Rate limits: 10/min, 200/hr, 500/day.

List views

Rate limits: 50/min, 500/hr, 2000/day.

Delete a view

Rate limits: 10/min, 200/hr, 500/day.

Template Resource Schema

Supported Field Types

Quick Reference

Create a RAG chat and get the answer

POST /current/workspace/{id}/ai/chat/
  question=...&type=chat_with_files&personality=detailed
  -> chat_id, message_id

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

GET  /current/workspace/{id}/ai/chat/{chat_id}/message/{msg_id}/details/
  -> check state == complete

GET  /current/workspace/{id}/ai/chat/{chat_id}/message/{msg_id}/read/
  -> SSE stream: data, 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

POST /current/workspace/{id}/storage/{node}/metadata/extract/
  template_id={template_id}

List eligible files for metadata

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

Add files to a template

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: 2/min, 10/hr)

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.