ForjinnForjinn
API Reference

Chatflows API: List, Create, Update, Delete

Manage Forjinn chatflows programmatically. List, create, retrieve, update, and delete chatflows and retrieve a chatflow by its associated API key.

A chatflow is a visual AI pipeline built in the Forjinn canvas. Each chatflow has a unique ID that you use when sending prediction requests. The endpoints below let you manage chatflows from your own tooling — useful for CI/CD pipelines, multi-tenant applications, or admin dashboards.

The chatflow object

FieldTypeDescription
idstringUUID of the chatflow
namestringDisplay name
displayNamestringOptional alternate display name (max 100 chars)
descriptionstringHuman-readable description (max 500 chars)
flowDatastringJSON-serialized flow graph
typestringFlow type: CHATFLOW, MULTIAGENT, ASSISTANT, AGENTFLOW, AUTOADK, AUTOGEN, or CREWAI
categorystringOptional category label
deployedbooleanWhether the chatflow is currently deployed
isPublicbooleanIf true, prediction requests don't require authentication
apikeyidstringID of the API key associated with this chatflow
workspaceIdstringWorkspace the chatflow belongs to
createdDatestringISO 8601 creation timestamp
updatedDatestringISO 8601 last-updated timestamp

List chatflows

typestring

Filter by flow type. One of CHATFLOW, MULTIAGENT, ASSISTANT, AGENTFLOW, AUTOADK, AUTOGEN, CREWAI.

pageinteger

Page number (default: 1).

limitinteger

Items per page (default: 20).

GET /api/v1/chatflows

Returns an array of chatflow objects belonging to your active workspace.

curl https://your-forjinn-instance.com/api/v1/chatflows \
  -H "Authorization: Bearer fj-abc123def456"
const response = await fetch('https://your-forjinn-instance.com/api/v1/chatflows', {
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});

const chatflows = await response.json();

Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Customer Support Bot",
    "displayName": "Support",
    "description": "Answers product questions using the knowledge base.",
    "type": "CHATFLOW",
    "category": "Support",
    "deployed": true,
    "isPublic": false,
    "workspaceId": "ws-111aaa",
    "createdDate": "2024-03-10T09:00:00.000Z",
    "updatedDate": "2024-04-01T14:30:00.000Z"
  }
]

Create a chatflow

POST /api/v1/chatflows
namestringRequired

Display name for the chatflow.

flowDatastringRequired

JSON-serialized flow graph (the nodes, edges, and viewport structure produced by the Forjinn canvas).

typestring

Flow type. One of CHATFLOW, MULTIAGENT, ASSISTANT, AGENTFLOW, AUTOADK, AUTOGEN, CREWAI. Defaults to CHATFLOW.

categorystring

Optional category label for organization.

descriptionstring

Optional description. Maximum 500 characters.

displayNamestring

Optional alternate display name. Maximum 100 characters.

isPublicboolean

Set to true to allow unauthenticated prediction requests.

curl -X POST https://your-forjinn-instance.com/api/v1/chatflows \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "type": "CHATFLOW",
    "category": "Support",
    "flowData": "{\"nodes\":[],\"edges\":[],\"viewport\":{\"x\":0,\"y\":0,\"zoom\":1}}"
  }'
const response = await fetch('https://your-forjinn-instance.com/api/v1/chatflows', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Customer Support Bot',
    type: 'CHATFLOW',
    category: 'Support',
    flowData: JSON.stringify({ nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } }),
  }),
});

const chatflow = await response.json();

Response — 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Customer Support Bot",
  "type": "CHATFLOW",
  "category": "Support",
  "deployed": false,
  "isPublic": false,
  "workspaceId": "ws-111aaa",
  "createdDate": "2024-05-01T10:00:00.000Z",
  "updatedDate": "2024-05-01T10:00:00.000Z"
}

Get a chatflow

GET /api/v1/chatflows/:id
idstringRequired

The UUID of the chatflow.

curl https://your-forjinn-instance.com/api/v1/chatflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456"
const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/chatflows/${id}`, {
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});

const chatflow = await response.json();

Response — 200 OK — returns a single chatflow object.

Get a chatflow by API key

GET /api/v1/chatflows/apikey/:apikey

Returns the chatflow(s) associated with a given API key value. Useful when you have the raw key string and need to resolve the corresponding chatflow.

apikeystringRequired

The raw API key string (not the key ID).

keyonlystring

If provided, returns only the key metadata without the full chatflow.

curl https://your-forjinn-instance.com/api/v1/chatflows/apikey/fj-abc123def456 \
  -H "Authorization: Bearer fj-abc123def456"
const response = await fetch(
  'https://your-forjinn-instance.com/api/v1/chatflows/apikey/fj-abc123def456',
  { headers: { 'Authorization': 'Bearer fj-abc123def456' } }
);

const chatflow = await response.json();

Update a chatflow

PUT /api/v1/chatflows/:id
idstringRequired

The UUID of the chatflow to update.

Send only the fields you want to change. Omitted fields retain their existing values.

namestring

New display name.

flowDatastring

Updated JSON-serialized flow graph.

deployedboolean

Set to true to deploy or false to undeploy.

isPublicboolean

Toggle public access for unauthenticated predictions.

descriptionstring

Updated description (max 500 chars).

displayNamestring

Updated display name (max 100 chars).

categorystring

Updated category label.

curl -X PUT https://your-forjinn-instance.com/api/v1/chatflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "deployed": true,
    "description": "Handles tier-1 support questions using the product knowledge base."
  }'
const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/chatflows/${id}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer fj-abc123def456',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    deployed: true,
    description: 'Handles tier-1 support questions using the product knowledge base.',
  }),
});

const updated = await response.json();

Response — 200 OK — returns the updated chatflow object.

Delete a chatflow

DELETE /api/v1/chatflows/:id
idstringRequired

The UUID of the chatflow to delete.

Deleting a chatflow is permanent. Any integrations using the chatflow's ID will stop working immediately.

curl -X DELETE https://your-forjinn-instance.com/api/v1/chatflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fj-abc123def456"
const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(`https://your-forjinn-instance.com/api/v1/chatflows/${id}`, {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer fj-abc123def456' },
});
// 200 OK on success

Authenticate Requests to the Forjinn API

Learn how to authenticate requests to the Forjinn API using API keys via the Authorization header or a query parameter, plus notes on public chatflows.

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.

On this page

The chatflow objectList chatflowsCreate a chatflowGet a chatflowGet a chatflow by API keyUpdate a chatflowDelete a chatflow