Arcanflows — AI Automation Platform for Business

Overview

Conversations represent chat sessions between users and agents. Each conversation belongs to a single agent and contains an ordered list of messages. Use these endpoints to create conversations, send and retrieve messages, and manage conversation history.

Base URL: /api/v1

Endpoints Summary

Method	Endpoint	Description
GET	`/api/v1/conversations`	List all conversations
POST	`/api/v1/conversations`	Create a new conversation
GET	`/api/v1/conversations/:id`	Get conversation details
PUT	`/api/v1/conversations/:id`	Update a conversation
DELETE	`/api/v1/conversations/:id`	Delete a conversation
GET	`/api/v1/conversations/:id/messages`	Get messages in a conversation
GET	`/api/v1/agents/:agent_id/conversations`	List conversations for an agent

List Conversations

GET /api/v1/conversations

Retrieve all conversations for the authenticated user. Supports pagination, sorting, and filtering.

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max 100)
`sort`	string	`updated_at`	Sort field: `created_at`, `updated_at`, `title`
`order`	string	`desc`	Sort order: `asc` or `desc`
`agent_id`	string	--	Filter by agent ID
`search`	string	--	Search conversation titles

bash
curl -X GET "/api/v1/conversations?page=1&per_page=10&sort=updated_at&order=desc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK:

json
{
  "conversations": [
    {
      "id": "conv_abc123",
      "title": "Help with onboarding flow",
      "agent_id": "agt_xyz789",
      "agent_name": "Customer Support Bot",
      "message_count": 14,
      "last_message_preview": "Sure, I can walk you through the setup...",
      "created_at": "2025-10-05T09:00:00Z",
      "updated_at": "2025-10-05T09:32:00Z"
    },
    {
      "id": "conv_def456",
      "title": "API integration questions",
      "agent_id": "agt_xyz789",
      "agent_name": "Customer Support Bot",
      "message_count": 8,
      "last_message_preview": "The webhook endpoint accepts POST...",
      "created_at": "2025-10-04T15:20:00Z",
      "updated_at": "2025-10-04T15:45:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 10
}

Create Conversation

POST /api/v1/conversations

Create a new conversation with an agent. Optionally include an initial message.

bash
curl -X POST /api/v1/conversations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_xyz789",
    "title": "Help with onboarding flow",
    "initial_message": "How do I set up a new user onboarding workflow?"
  }'

Request Body:

Field	Type	Required	Description
`agent_id`	string	Yes	The agent to converse with
`title`	string	No	Conversation title (auto-generated if omitted)
`initial_message`	string	No	First user message to send immediately
`metadata`	object	No	Custom key-value metadata

Response 201 Created:

json
{
  "id": "conv_ghi789",
  "title": "Help with onboarding flow",
  "agent_id": "agt_xyz789",
  "agent_name": "Customer Support Bot",
  "message_count": 2,
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "How do I set up a new user onboarding workflow?",
      "created_at": "2025-10-06T11:00:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "I'd be happy to help you set up an onboarding workflow! Here are the steps...",
      "metadata": {
        "model": "gpt-4o",
        "tokens_prompt": 42,
        "tokens_completion": 187,
        "latency_ms": 1240
      },
      "created_at": "2025-10-06T11:00:01Z"
    }
  ],
  "metadata": {},
  "created_at": "2025-10-06T11:00:00Z",
  "updated_at": "2025-10-06T11:00:01Z"
}

If initial_message is omitted, the conversation is created empty with message_count: 0.

Get Conversation

GET /api/v1/conversations/:id

Retrieve details of a specific conversation.

bash
curl -X GET /api/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK:

json
{
  "id": "conv_abc123",
  "title": "Help with onboarding flow",
  "agent_id": "agt_xyz789",
  "agent_name": "Customer Support Bot",
  "message_count": 14,
  "metadata": {},
  "created_at": "2025-10-05T09:00:00Z",
  "updated_at": "2025-10-05T09:32:00Z"
}

Update Conversation

PUT /api/v1/conversations/:id

Update a conversation's title or metadata.

bash
curl -X PUT /api/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Onboarding flow - resolved",
    "metadata": {
      "status": "resolved",
      "tags": ["onboarding", "workflow"]
    }
  }'

Request Body:

Field	Type	Required	Description
`title`	string	No	New conversation title
`metadata`	object	No	Custom key-value metadata (merged with existing)

Response 200 OK:

json
{
  "id": "conv_abc123",
  "title": "Onboarding flow - resolved",
  "agent_id": "agt_xyz789",
  "metadata": {
    "status": "resolved",
    "tags": ["onboarding", "workflow"]
  },
  "updated_at": "2025-10-06T11:30:00Z"
}

Delete Conversation

DELETE /api/v1/conversations/:id

Permanently delete a conversation and all its messages. This action cannot be undone.

bash
curl -X DELETE /api/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK:

json
{
  "message": "Conversation deleted successfully"
}

Get Messages

GET /api/v1/conversations/:id/messages

Retrieve all messages in a conversation. Messages are returned in chronological order. Supports pagination for long conversations.

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Messages per page (max 200)
`order`	string	`asc`	Sort order: `asc` (oldest first) or `desc` (newest first)

bash
curl -X GET "/api/v1/conversations/conv_abc123/messages?page=1&per_page=50&order=asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK:

json
{
  "messages": [
    {
      "id": "msg_001",
      "conversation_id": "conv_abc123",
      "role": "system",
      "content": "You are a helpful customer support agent for Arcanflows.",
      "metadata": {},
      "created_at": "2025-10-05T09:00:00Z"
    },
    {
      "id": "msg_002",
      "conversation_id": "conv_abc123",
      "role": "user",
      "content": "How do I set up a new user onboarding workflow?",
      "metadata": {},
      "created_at": "2025-10-05T09:00:05Z"
    },
    {
      "id": "msg_003",
      "conversation_id": "conv_abc123",
      "role": "assistant",
      "content": "I'd be happy to help you set up an onboarding workflow! Here are the steps...",
      "metadata": {
        "model": "gpt-4o",
        "tokens_prompt": 128,
        "tokens_completion": 256,
        "latency_ms": 1540
      },
      "created_at": "2025-10-05T09:00:07Z"
    },
    {
      "id": "msg_004",
      "conversation_id": "conv_abc123",
      "role": "user",
      "content": "Can I add a conditional step based on the user's role?",
      "metadata": {},
      "created_at": "2025-10-05T09:01:20Z"
    },
    {
      "id": "msg_005",
      "conversation_id": "conv_abc123",
      "role": "assistant",
      "content": "Absolutely! You can add conditional branching in your workflow...",
      "metadata": {
        "model": "gpt-4o",
        "tokens_prompt": 412,
        "tokens_completion": 198,
        "latency_ms": 1120
      },
      "created_at": "2025-10-05T09:01:22Z"
    }
  ],
  "total": 14,
  "page": 1,
  "per_page": 50
}

Message Object

Field	Type	Description
`id`	string	Unique message identifier
`conversation_id`	string	Parent conversation ID
`role`	string	Message role: `user`, `assistant`, or `system`
`content`	string	Message text content
`metadata`	object	Additional data (see below)
`created_at`	string	ISO 8601 timestamp

Message Metadata (assistant messages)

Field	Type	Description
`model`	string	LLM model used (e.g., `gpt-4o`, `claude-3-sonnet`)
`tokens_prompt`	integer	Number of prompt tokens consumed
`tokens_completion`	integer	Number of completion tokens generated
`latency_ms`	integer	Response time in milliseconds
`tools_used`	array	List of tool names invoked during this turn

List Conversations by Agent

GET /api/v1/agents/:agent_id/conversations

Retrieve all conversations associated with a specific agent.

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max 100)
`sort`	string	`updated_at`	Sort field: `created_at`, `updated_at`
`order`	string	`desc`	Sort order: `asc` or `desc`

bash
curl -X GET "/api/v1/agents/agt_xyz789/conversations?page=1&per_page=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK:

json
{
  "conversations": [
    {
      "id": "conv_abc123",
      "title": "Help with onboarding flow",
      "agent_id": "agt_xyz789",
      "agent_name": "Customer Support Bot",
      "message_count": 14,
      "last_message_preview": "Sure, I can walk you through the setup...",
      "created_at": "2025-10-05T09:00:00Z",
      "updated_at": "2025-10-05T09:32:00Z"
    }
  ],
  "total": 7,
  "page": 1,
  "per_page": 10
}

Conversation Object Reference

Field	Type	Description
`id`	string	Unique conversation identifier
`title`	string	Conversation title
`agent_id`	string	Associated agent ID
`agent_name`	string	Agent display name
`message_count`	integer	Total number of messages
`last_message_preview`	string	Truncated preview of the last message
`metadata`	object	Custom key-value metadata
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last-update timestamp

Error Responses

404 Not Found

Returned when a conversation or agent does not exist, or the user does not have access.

json
{
  "error": {
    "code": "not_found",
    "message": "Conversation not found"
  }
}

403 Forbidden

Returned when the user does not have permission to access the conversation.

json
{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this conversation"
  }
}

422 Validation Error

Returned when the request body fails validation.

json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "agent_id": "Agent not found or not accessible"
    }
  }
}