API Overview

The Administrative Application exposes a REST API for managing all platform resources. All endpoints follow consistent patterns for CRUD operations, pagination, and error handling.

Base URL

https://your-admin-domain.com/api

Authentication & Authorization

API requests require authentication via Auth0. The session is managed through cookies set during the OAuth flow.

For programmatic access, use the session endpoint to verify authentication:

GET /api/auth/session

Role-Based Access Control (RBAC)

All API endpoints enforce permission checks based on the user's role within the organization:

Role	Description	Typical Permissions
System	Platform administrators	Full access to all resources
Admin	Organization administrators	Full access to organization resources
User	Standard users	Workflows (full), entities (read-only)
Guest	Read-only access	View all resources, no modifications

API requests will return 403 Forbidden if the user lacks the required permission:

{
  "error": "Forbidden: You do not have permission to create entities"
}

See RBAC Documentation for the complete permission matrix.

Common Patterns

Pagination

List endpoints support pagination with these query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`limit`	integer	10	Items per page

Response format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

Error Responses

All errors follow this format:

{
  "error": "Human-readable error message",
  "details": "Optional additional details"
}

Common HTTP Status Codes:

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Not authenticated
404	Not Found
409	Conflict - Duplicate resource
500	Internal Server Error

Filtering

Most list endpoints support filtering by organization:

GET /api/environments?organizationId={uuid}

Some endpoints support additional filters:

GET /api/variables?organizationId={uuid}&environmentId={uuid}
GET /api/workflow-entities?organizationId={uuid}&search={term}

API Endpoints

Organizations

Manage organizations (top-level tenant).

Method	Endpoint	Description
GET	`/api/organizations`	List all organizations
POST	`/api/organizations`	Create organization
GET	`/api/organizations/{id}`	Get organization by ID
PUT	`/api/organizations/{id}`	Update organization
DELETE	`/api/organizations/{id}`	Delete organization

Environments

Manage environments within an organization.

Method	Endpoint	Description
GET	`/api/environments`	List environments
POST	`/api/environments`	Create environment
GET	`/api/environments/{id}`	Get environment by ID
PUT	`/api/environments/{id}`	Update environment
DELETE	`/api/environments/{id}`	Delete environment

Query Parameters:

organizationId - Filter by organization (required for list)

Variables

Manage environment-scoped variables (write-only values).

Method	Endpoint	Description
GET	`/api/variables`	List variables
POST	`/api/variables`	Create variable
GET	`/api/variables/{id}`	Get variable by ID
PUT	`/api/variables/{id}`	Update variable
DELETE	`/api/variables/{id}`	Delete variable

Query Parameters:

organizationId - Filter by organization
environmentId - Filter by environment

note

Variable values are write-only for security. The API never returns the value field.

Models

Manage AI/LLM model configurations.

Method	Endpoint	Description	Permission
GET	`/api/models`	List models	`entities:read`
POST	`/api/models`	Create model	`entities:create`
GET	`/api/models/{id}`	Get model by ID	`entities:read`
PUT	`/api/models/{id}`	Update model	`entities:update`
DELETE	`/api/models/{id}`	Delete model	`entities:delete`

Query Parameters:

organizationId - Filter by organization (required)

note

Model credentials (token, clientKey, secretKey) are write-only. The API returns hasToken and hasClientKey boolean flags instead.

System Models

Platform-wide AI/LLM configurations managed by system administrators.

Method	Endpoint	Description	Permission
GET	`/api/system-models/visible`	List visible system models	Any authenticated
GET	`/api/system-models`	List all system models	System only
POST	`/api/system-models`	Create system model	System only
PUT	`/api/system-models/{id}`	Update system model	System only
DELETE	`/api/system-models/{id}`	Delete system model	System only

Roles

List available roles for user management.

Method	Endpoint	Description	Permission
GET	`/api/roles`	List assignable roles	Any authenticated

Response:

{
  "data": [
    { "id": "uuid", "name": "admin", "description": "Organization administrator" },
    { "id": "uuid", "name": "user", "description": "Standard user" },
    { "id": "uuid", "name": "guest", "description": "Read-only access" }
  ]
}

Workflows

Manage workflow definitions and canvas data.

Method	Endpoint	Description
GET	`/api/workflows`	List workflows
POST	`/api/workflows`	Create workflow
GET	`/api/workflows/{id}`	Get workflow by ID
PUT	`/api/workflows/{id}`	Update workflow
DELETE	`/api/workflows/{id}`	Delete workflow

Query Parameters:

organizationId - Filter by organization
environmentId - Filter by environment

Workflow Entities

Manage reusable workflow entity definitions.

Method	Endpoint	Description	Permission
GET	`/api/workflow-entities`	List entities	`entities:read`
POST	`/api/workflow-entities`	Create entity	`entities:create`
GET	`/api/workflow-entities/{id}`	Get entity by ID	`entities:read`
PUT	`/api/workflow-entities/{id}`	Update entity	`entities:update`
DELETE	`/api/workflow-entities/{id}`	Delete entity	`entities:delete`
GET	`/api/workflow-entities/{id}/usage-count`	Count workflow usage	`entities:read`

Query Parameters:

organizationId - Filter by organization
environmentId - Filter by environment
search - Search by name (case-insensitive)

Workflow Entity Types

Manage entity type definitions (Event, Prompt, Action, Result).

Method	Endpoint	Description
GET	`/api/workflow-entity-types`	List all types
POST	`/api/workflow-entity-types`	Create type
GET	`/api/workflow-entity-types/{id}`	Get type by ID
PUT	`/api/workflow-entity-types/{id}`	Update type
DELETE	`/api/workflow-entity-types/{id}`	Delete type

Prompt Templates

Manage prompt templates for the Prompt Builder with version history and sentiment analysis.

Method	Endpoint	Description	Permission
GET	`/api/prompt-templates`	List templates	`entities:read`
POST	`/api/prompt-templates`	Create template	`entities:create`
GET	`/api/prompt-templates/{id}`	Get template by ID	`entities:read`
PUT	`/api/prompt-templates/{id}`	Update template	`entities:update`
DELETE	`/api/prompt-templates/{id}`	Delete template	`entities:delete`
POST	`/api/prompt-templates/{id}/execute`	Execute with model	`entities:read`
POST	`/api/prompt-templates/{id}/analyze-sentiment`	Run sentiment analysis	`entities:read`
GET	`/api/prompt-templates/{id}/versions`	List version history	`entities:read`
GET	`/api/prompt-templates/{id}/versions/{version}`	Get specific version	`entities:read`

Query Parameters:

organizationId - Filter by organization (required)
environmentId - Filter by environment
search - Search by name (case-insensitive)

See Prompt Builder for detailed request/response examples.

Prompts

Manage standalone prompts (separate from Prompt Templates).

Method	Endpoint	Description
GET	`/api/prompts`	List prompts
POST	`/api/prompts`	Create prompt
GET	`/api/prompts/{id}`	Get prompt by ID
PUT	`/api/prompts/{id}`	Update prompt
DELETE	`/api/prompts/{id}`	Delete prompt

Query Parameters:

organizationId - Filter by organization

Processed Queue

Access processed messages stored in S3.

Method	Endpoint	Description
GET	`/api/processed-queue`	List processed messages
GET	`/api/processed-queue/{key}`	Get message by S3 key
DELETE	`/api/processed-queue/{key}`	Delete single message
DELETE	`/api/processed-queue?keys={k1,k2}`	Bulk delete messages
GET	`/api/processed-queue/counts`	Get counts by status

Query Parameters:

organizationId - Filter by organization (required)
environmentId - Filter by environment
status - Filter by status: success, fail, ignore

Request/Response Examples

Create Organization

POST /api/organizations
Content-Type: application/json

{
  "name": "Acme Corp",
  "description": "Main production organization"
}

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "description": "Main production organization",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Create Environment

POST /api/environments
Content-Type: application/json

{
  "name": "Production",
  "description": "Live production environment",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000"
}

Create Variable

POST /api/variables
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "OPENAI_API_KEY",
  "value": "sk-proj-xxxxxxxxxxxx"
}

Response (201):

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "OPENAI_API_KEY",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Note: value is not returned.

Create Model

POST /api/models
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GPT-4 Turbo",
  "description": "Production model",
  "modelUrl": "https://api.openai.com/v1/chat/completions",
  "token": "sk-proj-xxxxxxxxxxxx"
}

Response (201):

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GPT-4 Turbo",
  "description": "Production model",
  "modelUrl": "https://api.openai.com/v1/chat/completions",
  "hasToken": true,
  "hasClientKey": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Create Workflow Entity

POST /api/workflow-entities
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Check User Type",
  "description": "Evaluates if user is premium",
  "workflowEntityTypeId": "event-type-uuid",
  "condition": {
    "type": "group",
    "operator": "AND",
    "conditions": [
      {
        "type": "rule",
        "field": "message.type",
        "comparison": "equals",
        "value": "user.signup"
      }
    ]
  },
  "script": "// Optional post-condition script",
  "tfCondition": "True/False",
  "arguments": [
    {
      "argumentName": "userId",
      "argumentValue": "{{message.user.id}}",
      "argumentDescription": "The user's unique identifier"
    }
  ]
}

Create Workflow

POST /api/workflows
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "New User Welcome",
  "description": "Welcome flow for new signups",
  "workflowData": {
    "root": {
      "name": "Check User",
      "entityId": "entity-uuid",
      "entityType": "event",
      "presentation": {
        "type": "circle",
        "position": { "x": 100, "y": 200 }
      },
      "children": []
    }
  }
}

Create Prompt Template

POST /api/prompt-templates
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Welcome Message Generator",
  "description": "Generates personalized welcome messages",
  "promptText": "You are a friendly assistant. Write a warm welcome message for {{userName}} who just joined {{productName}}. Keep it under 280 characters.",
  "modelId": "880e8400-e29b-41d4-a716-446655440003",
  "variables": {
    "userName": "string",
    "productName": "string"
  },
  "variableSets": [
    {
      "name": "Happy User",
      "values": { "userName": "Sarah", "productName": "Pulse" }
    }
  ]
}

Response (201):

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "name": "Welcome Message Generator",
  "description": "Generates personalized welcome messages",
  "promptText": "You are a friendly assistant...",
  "version": 1,
  "modelId": "880e8400-e29b-41d4-a716-446655440003",
  "model": { "id": "880e8400...", "name": "GPT-4 Turbo" },
  "organization": { "name": "Acme Corp" },
  "environment": { "name": "Production" },
  "variables": { "userName": "string", "productName": "string" },
  "variableSets": [...],
  "rawSentimentAnalysis": null,
  "resultSentimentAnalysis": null,
  "createdAt": "2025-01-27T10:00:00Z",
  "updatedAt": "2025-01-27T10:00:00Z"
}

Update Prompt Template

PUT /api/prompt-templates/990e8400-e29b-41d4-a716-446655440004
Content-Type: application/json

{
  "name": "Welcome Message v2",
  "promptText": "Create an exciting welcome for {{userName}}!",
  "variableSets": [
    { "name": "Test 1", "values": { "userName": "Alex" } }
  ]
}

Note: Updates automatically increment the version and save previous state to history.

Create Prompt

POST /api/prompts
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "modelId": "880e8400-e29b-41d4-a716-446655440003",
  "title": "Customer Support Response",
  "content": "You are a helpful customer support agent. Respond to: {{customerMessage}}",
  "outputFormat": "text",
  "outputTemplate": null
}

Response (201):

{
  "id": "aa0e8400-e29b-41d4-a716-446655440005",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "modelId": "880e8400-e29b-41d4-a716-446655440003",
  "model": { "name": "GPT-4 Turbo" },
  "organization": { "name": "Acme Corp" },
  "title": "Customer Support Response",
  "content": "You are a helpful customer support agent...",
  "outputFormat": "text",
  "outputTemplate": null,
  "createdAt": "2025-01-27T10:00:00Z",
  "updatedAt": "2025-01-27T10:00:00Z"
}

Update Prompt

PUT /api/prompts/aa0e8400-e29b-41d4-a716-446655440005
Content-Type: application/json

{
  "title": "Customer Support Response v2",
  "content": "You are an empathetic support agent. Address: {{customerMessage}}",
  "outputFormat": "json",
  "outputTemplate": "{ \"response\": \"{{response}}\", \"sentiment\": \"{{sentiment}}\" }"
}

Delete Prompt

DELETE /api/prompts/aa0e8400-e29b-41d4-a716-446655440005

Response:

{
  "success": true,
  "id": "aa0e8400-e29b-41d4-a716-446655440005"
}

OpenAPI Specification

For the complete OpenAPI 3.0 specification, see openapi.yaml.

MCP (Model Context Protocol)

For AI agent integration, the platform also exposes an MCP-compatible API that allows tools like Claude Desktop and Cursor IDE to interact with the platform programmatically.

See MCP API Documentation for details.

Environments — Environment management UI
Settings — Variables, Models, and Users UI
RBAC — Role permissions reference
Workflows — Workflow canvas UI
Entity Submission — Detailed entity CRUD reference
MCP API — AI agent integration via Model Context Protocol

Base URL​

Authentication & Authorization​

Role-Based Access Control (RBAC)​

Common Patterns​

Pagination​

Error Responses​

Filtering​

API Endpoints​

Organizations​

Environments​

Variables​

Models​

System Models​

Roles​

Workflows​

Workflow Entities​

Workflow Entity Types​

Prompt Templates​

Prompts​

Processed Queue​

Request/Response Examples​

Create Organization​

Create Environment​

Create Variable​

Create Model​

Create Workflow Entity​

Create Workflow​

Create Prompt Template​

Update Prompt Template​

Create Prompt​

Update Prompt​

Delete Prompt​

OpenAPI Specification​

MCP (Model Context Protocol)​

Related Topics​

Base URL

Authentication & Authorization

Role-Based Access Control (RBAC)

Common Patterns

Pagination

Error Responses

Filtering

API Endpoints

Organizations

Environments

Variables

Models

System Models

Roles

Workflows

Workflow Entities

Workflow Entity Types

Prompt Templates

Prompts

Processed Queue

Request/Response Examples

Create Organization

Create Environment

Create Variable

Create Model

Create Workflow Entity

Create Workflow

Create Prompt Template

Update Prompt Template

Create Prompt

Update Prompt

Delete Prompt

OpenAPI Specification

MCP (Model Context Protocol)

Related Topics