Models API

Complete API reference for managing AI/LLM model configurations with JavaScript, cURL, and MCP examples.

Overview

Models define AI/LLM service configurations for use in Prompt workflow entities. Each model stores connection details and authentication credentials. Credentials are write-only - they are never returned in API responses.

Authentication Types

Models support two mutually exclusive authentication methods:

Type	Fields	Use Case
Token	`token`	OpenAI, Anthropic, most cloud LLM providers
Client Key/Secret	`clientKey`, `secretKey`	AWS Bedrock (SigV4), enterprise APIs

warning

Provide either token OR clientKey/secretKey, not both. If using client key authentication, both fields are required.

Endpoints

Operation	Method	Endpoint
List	GET	`/api/models?organizationId={id}`
Create	POST	`/api/models`
Get by ID	GET	`/api/models/{id}`
Update	PUT	`/api/models/{id}`
Delete	DELETE	`/api/models/{id}`

List Models

Retrieve models for an organization, with options for including system models.

Query Parameters

Parameter	Type	Description
`organizationId`	UUID	Filter by organization (required for user models)
`modelType`	string	Filter by type: `user` or `system`
`includeSystem`	boolean	Include visible system models (paid plans only)
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 10)

cURL

# List organization models only
curl -X GET "https://console.rocketwavelabs.io/api/models?organizationId=ORG_UUID&modelType=user" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

# Include visible system models (for paid plans)
curl -X GET "https://console.rocketwavelabs.io/api/models?organizationId=ORG_UUID&includeSystem=true" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

# List system models only (admin)
curl -X GET "https://console.rocketwavelabs.io/api/models?modelType=system" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

// Using the ModelService
import { modelService } from '@/app/services/modelService';

// Get organization models
const result = await modelService.getAll(1, 10, 'ORG_UUID');

// Include system models (for model dropdowns)
const withSystem = await modelService.getAll(1, 10, 'ORG_UUID', true);

// Get all models for selection (org + visible system)
const forSelection = await modelService.getForSelection('ORG_UUID');

// Get system models only (admin)
const systemModels = await modelService.getSystemModels(1, 10);

// Using fetch directly
const response = await fetch('/api/models?organizationId=ORG_UUID&includeSystem=true', {
  credentials: 'include'
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_list',
    arguments: {
      organizationId: 'ORG_UUID',
      includeSystem: true,
      page: 1,
      limit: 10
    }
  })
});

Response

{
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "organizationId": "ORG_UUID",
      "name": "GPT-4 Turbo",
      "description": "Production OpenAI model",
      "modelUrl": "https://api.openai.com/v1/chat/completions",
      "hasToken": true,
      "hasClientKey": false,
      "modelType": "user",
      "isVisible": true,
      "organization": { "name": "Acme Corp" },
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    },
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "organizationId": null,
      "name": "Claude 3 Sonnet (System)",
      "description": "Platform-provided Claude model",
      "modelUrl": "https://api.anthropic.com/v1/messages",
      "hasToken": true,
      "hasClientKey": false,
      "modelType": "system",
      "isVisible": true,
      "organization": null,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 2, "totalPages": 1 }
}

Security

Credentials (token, clientKey, secretKey) are never returned. Instead, hasToken and hasClientKey indicate which authentication type is configured.

Create Model (Token Authentication)

Create a model using bearer token authentication (OpenAI, Anthropic, etc.).

cURL

curl -X POST "https://console.rocketwavelabs.io/api/models" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "organizationId": "ORG_UUID",
    "name": "GPT-4 Turbo",
    "description": "OpenAI GPT-4 for content generation",
    "modelUrl": "https://api.openai.com/v1/chat/completions",
    "token": "sk-proj-xxxxxxxxxxxxxxxxxxxx"
  }'

JavaScript

// Using the ModelService
import { modelService } from '@/app/services/modelService';

const model = await modelService.create({
  organizationId: 'ORG_UUID',
  name: 'GPT-4 Turbo',
  description: 'OpenAI GPT-4 for content generation',
  modelUrl: 'https://api.openai.com/v1/chat/completions',
  token: 'sk-proj-xxxxxxxxxxxxxxxxxxxx'
});

// Using fetch directly
const response = await fetch('/api/models', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    organizationId: 'ORG_UUID',
    name: 'GPT-4 Turbo',
    description: 'OpenAI GPT-4 for content generation',
    modelUrl: 'https://api.openai.com/v1/chat/completions',
    token: 'sk-proj-xxxxxxxxxxxxxxxxxxxx'
  })
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_create',
    arguments: {
      organizationId: 'ORG_UUID',
      name: 'GPT-4 Turbo',
      description: 'OpenAI GPT-4 for content generation',
      modelUrl: 'https://api.openai.com/v1/chat/completions',
      token: 'sk-proj-xxxxxxxxxxxxxxxxxxxx'
    }
  })
});

Response (201)

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "organizationId": "ORG_UUID",
  "name": "GPT-4 Turbo",
  "description": "OpenAI GPT-4 for content generation",
  "modelUrl": "https://api.openai.com/v1/chat/completions",
  "hasToken": true,
  "hasClientKey": false,
  "modelType": "user",
  "isVisible": true,
  "organization": { "name": "Acme Corp" },
  "createdAt": "2025-01-27T10:00:00Z",
  "updatedAt": "2025-01-27T10:00:00Z"
}

Create Model (Client Key/Secret Authentication)

Create a model using client key/secret authentication (AWS Bedrock, etc.).

cURL

curl -X POST "https://console.rocketwavelabs.io/api/models" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "organizationId": "ORG_UUID",
    "name": "Claude 3 Sonnet (Bedrock)",
    "description": "AWS Bedrock Claude model",
    "modelUrl": "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-sonnet/invoke",
    "clientKey": "AKIAXXXXXXXXXXXX",
    "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }'

JavaScript

const model = await modelService.create({
  organizationId: 'ORG_UUID',
  name: 'Claude 3 Sonnet (Bedrock)',
  description: 'AWS Bedrock Claude model',
  modelUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-sonnet/invoke',
  clientKey: 'AKIAXXXXXXXXXXXX',
  secretKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_create',
    arguments: {
      organizationId: 'ORG_UUID',
      name: 'Claude 3 Sonnet (Bedrock)',
      description: 'AWS Bedrock Claude model',
      modelUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-sonnet/invoke',
      clientKey: 'AKIAXXXXXXXXXXXX',
      secretKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    }
  })
});

Create System Model (Admin Only)

System models are platform-wide and available to all paid organizations.

cURL

curl -X POST "https://console.rocketwavelabs.io/api/models" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "Claude 3.5 Sonnet (Platform)",
    "description": "Platform-provided Claude model for all paid users",
    "modelUrl": "https://api.anthropic.com/v1/messages",
    "token": "sk-ant-xxxxxxxxxxxxxxxxxxxx",
    "modelType": "system",
    "isVisible": true
  }'

JavaScript

const systemModel = await modelService.create({
  name: 'Claude 3.5 Sonnet (Platform)',
  description: 'Platform-provided Claude model for all paid users',
  modelUrl: 'https://api.anthropic.com/v1/messages',
  token: 'sk-ant-xxxxxxxxxxxxxxxxxxxx',
  modelType: 'system',
  isVisible: true
});

Request Body (System Model)

Field	Type	Required	Description
`name`	string	Yes	Model display name
`description`	string	No	Model description
`modelUrl`	string	Yes	API endpoint URL
`token`	string	*	Bearer token (or use clientKey/secretKey)
`clientKey`	string	*	AWS access key ID
`secretKey`	string	*	AWS secret access key
`modelType`	string	Yes	Must be `"system"`
`isVisible`	boolean	No	Whether visible to organizations (default: true)

note

System models require the System role. organizationId should be omitted for system models.

Get Model by ID

Retrieve a single model by its ID.

cURL

curl -X GET "https://console.rocketwavelabs.io/api/models/MODEL_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

const model = await modelService.getById('MODEL_UUID');

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_get',
    arguments: { id: 'MODEL_UUID' }
  })
});

Update Model

Update an existing model's configuration.

cURL

curl -X PUT "https://console.rocketwavelabs.io/api/models/MODEL_UUID" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "GPT-4 Turbo (Updated)",
    "description": "Updated description",
    "modelUrl": "https://api.openai.com/v1/chat/completions",
    "token": "sk-proj-new-token"
  }'

JavaScript

const updated = await modelService.update('MODEL_UUID', {
  name: 'GPT-4 Turbo (Updated)',
  description: 'Updated description',
  modelUrl: 'https://api.openai.com/v1/chat/completions',
  token: 'sk-proj-new-token'  // Optional: omit to keep existing credentials
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_update',
    arguments: {
      id: 'MODEL_UUID',
      name: 'GPT-4 Turbo (Updated)',
      description: 'Updated description',
      modelUrl: 'https://api.openai.com/v1/chat/completions',
      token: 'sk-proj-new-token'
    }
  })
});

Request Body

Field	Type	Required	Description
`name`	string	Yes	Model display name
`description`	string	No	Model description
`modelUrl`	string	Yes	API endpoint URL
`token`	string	No	New bearer token (omit to keep existing)
`clientKey`	string	No	New AWS access key (omit to keep existing)
`secretKey`	string	No	New AWS secret key (omit to keep existing)
`isVisible`	boolean	No	Visibility setting (system models only)

Delete Model

Permanently delete a model.

cURL

curl -X DELETE "https://console.rocketwavelabs.io/api/models/MODEL_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

await modelService.delete('MODEL_UUID');

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_delete',
    arguments: { id: 'MODEL_UUID' }
  })
});

Response

{
  "success": true
}

warning

Deleting a model will cause any Prompt entities using it to fail. Update or remove affected Prompt entities before deletion.

Model Types

User Models

Belong to a specific organization
Require organizationId when creating
Only visible to that organization

System Models

Platform-wide, no organization association
Require System role to create/manage
Visible to all paid organizations (when isVisible: true)
Useful for providing pre-configured models to all users

Access Control

Model Type	Free Plan	Paid Plans	System Role
User Models	✅ Create/View Own	✅ Create/View Own	✅ Full Access
System Models	❌ No Access	✅ View Visible	✅ Full CRUD

Settings UI — Model management interface
Prompt Entity — Using models in workflows
Variables API — Environment variable management

Overview​

Authentication Types​

Endpoints​

List Models​

Query Parameters​

cURL​

JavaScript​

MCP​

Response​

Create Model (Token Authentication)​

cURL​

JavaScript​

MCP​

Response (201)​

Create Model (Client Key/Secret Authentication)​

cURL​

JavaScript​

MCP​

Create System Model (Admin Only)​

cURL​

JavaScript​

Request Body (System Model)​

Get Model by ID​

cURL​

JavaScript​

MCP​

Update Model​

cURL​

JavaScript​

MCP​

Request Body​

Delete Model​

cURL​

JavaScript​

MCP​

Response​

Model Types​

User Models​

System Models​

Access Control​

Related Topics​

Overview

Authentication Types

Endpoints

List Models

Query Parameters

cURL

JavaScript

MCP

Response

Create Model (Token Authentication)

cURL

JavaScript

MCP

Response (201)

Create Model (Client Key/Secret Authentication)

cURL

JavaScript

MCP

Create System Model (Admin Only)

cURL

JavaScript

Request Body (System Model)

Get Model by ID

cURL

JavaScript

MCP

Update Model

cURL

JavaScript

MCP

Request Body

Delete Model

cURL

JavaScript

MCP

Response

Model Types

User Models

System Models

Access Control

Related Topics