Predictions API: Query a Deployed Chatflow

Send a question to any Forjinn chatflow and receive an AI-generated response, with support for chat history, file uploads, config overrides, and SSE streaming.

The predictions endpoint is the primary way to interact with a deployed chatflow. You send a user message and receive an AI-generated response, including any source documents retrieved by RAG nodes and tools used during execution. This endpoint powers chatbots, automations, and any feature where your application needs to query a Forjinn flow.

Send a prediction

POST /api/v1/prediction/:id

idstringRequired

The UUID of the chatflow to query.

Request body

questionstringRequired

The user's input message.

chatIdstring

An identifier for the ongoing conversation session. When provided, the chatflow uses this to maintain memory between turns. If omitted a new session ID is generated automatically.

sessionIdstring

Alias for chatId. Use either field — they behave identically.

historyarray

An array of previous messages to provide conversation context. Each item is an object with a message string and a type of "userMessage" or "apiMessage".

history item fields

messagestring

The message content.

typestring

Either "userMessage" (from the human) or "apiMessage" (from the AI).

overrideConfigobject

A key-value map of node configuration values to override at runtime. Keys correspond to node parameter names as configured in the flow.

streamingboolean

Set to true to receive the response as a Server-Sent Events (SSE) stream. See Streaming below.

leadEmailstring

Optional email address to associate with this conversation for lead capture.

Response fields

textstring

The AI-generated response text.

chatIdstring

The session ID for this conversation. Pass this back in subsequent requests to maintain memory.

sourceDocumentsarray

Documents retrieved from the vector store to answer the question, if any. Each item contains pageContent and metadata.

usedToolsarray

Tools invoked during this execution, if any. Each item contains tool (name), toolInput, and toolOutput.

agentReasoningarray

Step-by-step reasoning from agent nodes, present in multi-agent flows.

Example — basic prediction

curl -X POST https://your-forjinn-instance.com/api/v1/prediction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I reset my password?",
    "chatId": "user-session-42"
  }'

const chatflowId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://your-forjinn-instance.com/api/v1/prediction/${chatflowId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'How do I reset my password?',
    chatId: 'user-session-42',
  }),
});

const result = await response.json();
console.log(result.text);

Response — 200 OK

{
  "text": "To reset your password, go to the login page and click 'Forgot Password'. Enter your email address and you'll receive a reset link within a few minutes.",
  "chatId": "user-session-42",
  "sourceDocuments": [
    {
      "pageContent": "Password reset: navigate to /forgot-password and enter your registered email...",
      "metadata": {
        "source": "help-center/account-management.pdf",
        "page": 3
      }
    }
  ],
  "usedTools": []
}

Example — with conversation history

curl -X POST https://your-forjinn-instance.com/api/v1/prediction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What about changing my email address?",
    "chatId": "user-session-42",
    "history": [
      { "message": "How do I reset my password?", "type": "userMessage" },
      { "message": "To reset your password, go to the login page and click Forgot Password...", "type": "apiMessage" }
    ]
  }'

const response = await fetch(`https://your-forjinn-instance.com/api/v1/prediction/${chatflowId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'What about changing my email address?',
    chatId: 'user-session-42',
    history: [
      { message: 'How do I reset my password?', type: 'userMessage' },
      { message: 'To reset your password, go to the login page and click Forgot Password...', type: 'apiMessage' },
    ],
  }),
});

Example — with config override

Use overrideConfig to change node parameters without editing the flow:

curl -X POST https://your-forjinn-instance.com/api/v1/prediction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize the quarterly report.",
    "overrideConfig": {
      "temperature": 0.2,
      "systemMessage": "You are a financial analyst. Be concise and factual."
    }
  }'

const response = await fetch(`https://your-forjinn-instance.com/api/v1/prediction/${chatflowId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'Summarize the quarterly report.',
    overrideConfig: {
      temperature: 0.2,
      systemMessage: 'You are a financial analyst. Be concise and factual.',
    },
  }),
});

File uploads

To include files in a prediction request, switch to multipart/form-data and attach files in the files field. Text fields (question, chatId, etc.) must be sent as form fields.

curl -X POST https://your-forjinn-instance.com/api/v1/prediction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -F "question=Summarize the attached document" \
  -F "chatId=user-session-42" \
  -F "files=@/path/to/report.pdf"

const form = new FormData();
form.append('question', 'Summarize the attached document');
form.append('chatId', 'user-session-42');
form.append('files', fileBlob, 'report.pdf');

const response = await fetch(`https://your-forjinn-instance.com/api/v1/prediction/${chatflowId}`, {
  method: 'POST',
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
  body: form,
});

Streaming

Set "streaming": true in your request body to receive the response token-by-token as a Server-Sent Events stream. The server sends individual token events followed by a final metadata event containing the full chatId, sourceDocuments, and usedTools.

curl -X POST https://your-forjinn-instance.com/api/v1/prediction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "question": "Write a short story about a robot.",
    "streaming": true
  }'

const response = await fetch(`https://your-forjinn-instance.com/api/v1/prediction/${chatflowId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'Write a short story about a robot.',
    streaming: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

The chatflow must support streaming. You can check this with GET /api/v1/chatflows-streaming/:id before making a streaming request.

Predictions API: Query a Deployed Chatflow

On this page