Using the API

The embed widget is great for websites, but what if you want to use your AI agent from a mobile app, a Slack bot, a backend service, or any other application? That's where the API comes in.

The API lets any application send messages to your CiniterFlow agent and receive responses — just like the chat widget does, but programmatically.

The Basics

Every flow in CiniterFlow has a unique Prediction API endpoint:

POST https://flow.ciniter.com/api/v1/prediction/{your-flow-id}

You send a message, and you get a response. That's it!

Finding Your Flow ID

1. Open your Chatflow or Agentflow
2. Look at the URL in your browser — the ID is the long string at the end
3. Or click the "API" button in the top bar to see the full endpoint

Your First API Call

Using cURL (Command Line)

curl -X POST https://flow.ciniter.com/api/v1/prediction/your-flow-id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"question": "Hello! What can you help me with?"}'

Using Python

import requests

response = requests.post(
    "https://flow.ciniter.com/api/v1/prediction/your-flow-id",
    headers={"Authorization": "Bearer your-api-key"},
    json={"question": "Hello! What can you help me with?"}
)

print(response.json())

Using JavaScript

const response = await fetch(
    'https://flow.ciniter.com/api/v1/prediction/your-flow-id',
    {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer your-api-key'
        },
        body: JSON.stringify({ question: 'Hello! What can you help me with?' })
    }
);

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

Using the Official SDKs

CiniterFlow provides official libraries that make API calls even easier:

Python SDK

pip install ciniterflow

from ciniterflow import CiniterFlow, PredictionData

client = CiniterFlow(base_url="https://flow.ciniter.com", api_key="your-api-key")

response = client.create_prediction(
    PredictionData(
        chatflowId="your-flow-id",
        question="What is machine learning?",
        streaming=False
    )
)

for result in response:
    print(result)

JavaScript/TypeScript SDK

npm install ciniterflow-sdk

import { CiniterFlowClient } from 'ciniterflow-sdk';

const client = new CiniterFlowClient({
    baseUrl: 'https://flow.ciniter.com',
    apiKey: 'your-api-key'
});

const response = await client.createPrediction({
    chatflowId: 'your-flow-id',
    question: 'What is machine learning?',
    streaming: false
});

console.log(response);

Streaming Responses

Instead of waiting for the entire response, you can receive it word by word (like ChatGPT does). Just set streaming: true:

from ciniterflow import CiniterFlow, PredictionData

client = CiniterFlow(base_url="https://flow.ciniter.com", api_key="your-api-key")

response = client.create_prediction(
    PredictionData(
        chatflowId="your-flow-id",
        question="Tell me a story",
        streaming=True
    )
)

for chunk in response:
    print(chunk, end="", flush=True)

Maintaining Conversations (Sessions)

To have multi-turn conversations where the AI remembers previous messages, use a sessionId:

import requests

API_URL = "https://flow.ciniter.com/api/v1/prediction/your-flow-id"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-api-key"
}
session_id = "user-123"

# First message
response1 = requests.post(API_URL, headers=HEADERS, json={
    "question": "My name is Sarah",
    "overrideConfig": {"sessionId": session_id}
})

# Second message — the AI will remember the name
response2 = requests.post(API_URL, headers=HEADERS, json={
    "question": "What's my name?",
    "overrideConfig": {"sessionId": session_id}
})

print(response2.json())  # Will mention "Sarah"

Sending Form Data

If your Agentflow uses Form Input, send form data instead of a question:

response = requests.post(
    "https://flow.ciniter.com/api/v1/prediction/your-flow-id",
    headers={"Authorization": "Bearer your-api-key"},
    json={
        "form": {
            "subject": "Order Issue",
            "body": "I received the wrong item",
            "email": "customer@example.com"
        }
    }
)

Uploading Images

import base64
import requests

with open("photo.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://flow.ciniter.com/api/v1/prediction/your-flow-id",
    headers={"Authorization": "Bearer your-api-key"},
    json={
        "question": "What do you see in this image?",
        "uploads": [{
            "data": f"data:image/jpeg;base64,{image_data}",
            "type": "file",
            "name": "photo.jpg",
            "mime": "image/jpeg"
        }]
    }
)

API Security

To protect your API from unauthorized access:

1. Go to your flow's Settings → API Keys
2. Create or assign an API key
3. Include it in your requests:

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-api-key-here"
}

response = requests.post(url, json=payload, headers=headers)

What's Next?

You now know how to use CiniterFlow from any application! In the final chapter, we'll cover variables, memory, and state management to make your agents even smarter.

👉 Variables, Memory & State