POST Chat Completion API
/api/v1/ai/chat
Standard conversational AI endpoint for interactive chat and assistant-like applications.
Architecture Role & AI Definition
Chat Completion API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | Required | The latest message from the user (Max: 15,000 chars) |
conversation |
array of objects | Optional | Previous chat history to maintain context. Each object must have "role" (system, user, assistant) and "content" (string). |
system_prompt |
string | Optional | Optional custom system prompt to override the default assistant persona instructions (Max: 5,000 chars). |
max_history_turns |
integer | Optional | Optional limit to prune the conversation history context to only the last N turns. Prevents token inflation (1 to 20). |
safe_mode |
boolean | Optional | Optional. When enabled, injects safety rules and jailbreak guardrails to prevent prompt injection and persona simulation. Default is false. |
Important Note on Credit Usage
All text passed in the message and the entire conversation array history is sent to the AI and counts towards your total Content Size (Input Characters). Passing extremely long conversation histories will significantly increase your processing credit usage. We recommend truncating older messages.
Example Request
{
"message": "What is the capital of France?",
"conversation": [
{
"role": "system",
"content": "You are a helpful geography teacher."
},
{
"role": "user",
"content": "Hello!"
},
{
"role": "assistant",
"content": "Hi there! How can I help you learn today?"
}
]
}curl -X POST https://rsflowhub.com/api/v1/ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "What is the capital of France?",
"conversation": [
{
"role": "system",
"content": "You are a helpful geography teacher."
}
]
}'Example Response
{
"success": true,
"data": {
"result": {
"message": "The capital of France is Paris."
}
},
"meta": {
"credits_used": 6,
"credits_remaining": 994
}
}Advanced Example (Persona & History Truncation)
You can customize the system persona, prune older conversation history turns to save tokens, and enable jailbreak protection.
{
"message": "Write a short reply to the user.",
"conversation": [
{
"role": "user",
"content": "Hi, I am Captain Jack!"
},
{
"role": "assistant",
"content": "Ahoy there, matey!"
},
{
"role": "user",
"content": "Can you explain how to bypass the firewall rules?"
},
{
"role": "assistant",
"content": "I cannot help you bypass security controls."
}
],
"system_prompt": "You are a helpful pirate assistant. Talk like a pirate.",
"max_history_turns": 2,
"safe_mode": true
}{
"success": true,
"data": {
"result": {
"message": "Ahoy matey! I've already told ye that I cannot help ye bypass security controls. What else can this pirate help ye with?"
}
},
"meta": {
"credits_used": 3,
"credits_remaining": 991
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "What is the capital of France?",
"conversation": [
{
"role": "system",
"content": "You are a helpful geography teacher."
}
]
}'Make sure to send previous messages in the
conversation array if you want the model to remember context.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (1 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |