--- title: "Create Starter" method: POST path: "/admin/api/v1/onboarding/create-starter" tags: ["Agent Configuration"] --- # Create Starter `POST /admin/api/v1/onboarding/create-starter` Scaffold a starter project + register the singleton agent row. ## Request body - CreateStarterBody — Body for ``POST /admin/api/v1/onboarding/create-starter``. ``name`` is optional. When omitted the server uses ``"Starter Agent"``. Empty string is rejected. - `framework` 'LANGGRAPH' | 'ADK', required - `name` string, nullable ## Response `200` Successful Response - StandaloneMutationResponseStandaloneAgentRead - `data` StandaloneAgentRead, required — GET response and the data payload of PATCH responses. - `id` string, uuid, required - `slug` string, nullable - `name` string, required - `description` string, nullable - `version` string, nullable - `status` 'draft' | 'active' | 'inactive' | 'deprecated' | 'error', required — Agent status enumeration. - `baseUrl` string, nullable - `baseEngineConfig` EngineConfig, required — Main engine configuration model for the entire Idun Agent Engine. - `server` ServerConfig — Configuration for the Engine's universal settings. - `api` ServerAPIConfig — API server configuration. - `port` integer - `agent` AgentConfig, required — Configuration for agent specification and settings. - `type` 'LANGGRAPH' | 'ADK' | 'CREWAI' | 'CUSTOM' | 'TRANSLATION_AGENT' | 'CORRECTION_AGENT' | 'DEEP_RESEARCH_AGENT', required — Supported agent frameworks for engine. - `config` union, required - LangGraphAgentConfig — Configuration model for LangGraph agents. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `graph_definition` string, required - `checkpointer` union - … - `store` object, nullable - AdkAgentConfig — Configuration model for ADK agents. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `agent` string, required — Agent definition (e.g. module.path:agent_instance) - `app_name` string — Application name for the agent - `session_service` union — Session service configuration - … - `memory_service` union — Memory service configuration - … - TranslationAgentConfig — Configuration model for the Translation Agent Template. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `graph_definition` string, required - `checkpointer` union - … - `store` object, nullable - `source_lang` string — Source language to translate from - `target_lang` string — Target language to translate to - `model_name` string — LLM model to use - CorrectionAgentConfig — Configuration model for the Correction Agent Template. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `language` string — Language to correct text in - `model_name` string — LLM model to use - `checkpointer` union - … - DeepResearchAgentConfig — Configuration model for the Deep Research Agent Template. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `model_name` string — LLM model to use - `project` string, required — Project identifier - `region` string, required — Region identifier - `tavily_api_key` string, required — Tavily API key for web search - `system_prompt` string — System prompt for the agent - `checkpointer` union - … - BaseAgentConfig — Base model for agent configurations. Extend for specific frameworks. - `name` string, required - `observability` IdunAgentSchemaEngineObservabilityObservabilityConfig — Provider-agnostic observability configuration based on Pydantic. Example YAML: observability: provider: "langfuse" # or "phoenix" enabled: true options: host: ${LANGFUSE_HOST} public_key: ${LANGFUSE_PUBLIC_KEY} secret_key: ${LANGFUSE_SECRET_KEY} run_name: "my-run" - … - `mcpServers` MCPServer[], nullable - `name` string, required — Unique identifier for this MCP server. - `transport` 'stdio' | 'sse' | 'streamable_http' | 'websocket' — Transport type used to reach the MCP server. - `url` string, nullable — Endpoint URL for HTTP/S based transports (SSE, streamable_http, websocket). - `command` string, nullable — Executable to run when using stdio transport. - `args` string[] — Arguments to pass to the command for stdio transport. - `headers` object — Optional headers for HTTP/S transports. - `env` object — Environment variables to set when spawning stdio servers. - `cwd` string, nullable — Working directory for stdio transports. - `encoding` string, nullable — Encoding used for stdio transport. - `encodingErrorHandler` 'strict' | 'ignore' | 'replace', nullable — Encoding error handler for stdio transport. - `timeoutSeconds` number, nullable — Timeout in seconds for HTTP/S transports (maps to `timeout`). - `sseReadTimeoutSeconds` number, nullable — Timeout in seconds waiting for SSE events (maps to `sse_read_timeout`). - `terminateOnClose` boolean, nullable — Whether to terminate Streamable HTTP sessions on close. - `sessionKwargs` object — Extra keyword arguments forwarded to MCP ClientSession. - `guardrails` GuardrailsV2 — Guardrails V2 configuration. - `input` union[] — List of input guardrails - union - BanListConfig — Ban List configuration. - … - DetectPIIConfig — Detect PII configuration. - … - BiasCheckConfig — Bias Check configuration. - … - CompetitionCheckConfig — Competition Check configuration. - … - CorrectLanguageConfig — Correct Language configuration. - … - GibberishTextConfig — Gibberish Text configuration. - … - NSFWTextConfig — NSFW Text configuration. - … - DetectJailbreakConfig — Detect Jailbreak configuration. - … - PromptInjectionConfig — Prompt Injection configuration. - … - RagHallucinationConfig — RAG Hallucination configuration. - … - RestrictToTopicConfig — Restrict To Topic configuration. - … - ToxicLanguageConfig — Toxic Language configuration. - … - CodeScannerConfig — Code Scanner configuration. - … - `output` union[] — List of output guardrails - union - BanListConfig — Ban List configuration. - … - DetectPIIConfig — Detect PII configuration. - … - BiasCheckConfig — Bias Check configuration. - … - CompetitionCheckConfig — Competition Check configuration. - … - CorrectLanguageConfig — Correct Language configuration. - … - GibberishTextConfig — Gibberish Text configuration. - … - NSFWTextConfig — NSFW Text configuration. - … - DetectJailbreakConfig — Detect Jailbreak configuration. - … - PromptInjectionConfig — Prompt Injection configuration. - … - RagHallucinationConfig — RAG Hallucination configuration. - … - RestrictToTopicConfig — Restrict To Topic configuration. - … - ToxicLanguageConfig — Toxic Language configuration. - … - CodeScannerConfig — Code Scanner configuration. - … - `observability` IdunAgentSchemaEngineObservabilityV2ObservabilityConfig[], nullable - `provider` 'LANGFUSE' | 'PHOENIX' | 'GCP_LOGGING' | 'GCP_TRACE' | 'LANGSMITH' — Supported observability providers. - `enabled` boolean - `config` union, required - LangfuseConfig — Langfuse configuration. - `provider` 'LANGFUSE' - `host` string - `publicKey` string - `secretKey` string - `runName` string - PhoenixConfig — Phoenix configuration. - `provider` 'PHOENIX' - `collectorEndpoint` string - `projectName` string - GCPLoggingConfig — GCP Logging configuration. - `provider` 'GCP_LOGGING' - `gcpProjectId` string — The project identifier where logs and traces will be sent. - `region` string — (Optional) The specific region/zone associated with the resource (e.g., us-central1). - `logName` string — The identifier for the log stream (e.g., application-log). - `resourceType` string — The resource type label (e.g., global, gce_instance, cloud_run_revision). - `severity` string — Minimum level to record (e.g., INFO, WARNING, ERROR, CRITICAL). - `transport` string — Selection for delivery method (e.g., BackgroundThread vs Synchronous). - GCPTraceConfig — GCP Trace configuration. - `provider` 'GCP_TRACE' - `gcpProjectId` string — The project identifier where logs and traces will be sent. - `region` string — (Optional) The specific region/zone associated with the resource (e.g., us-central1). - `traceName` string — The name for the trace or tracing session. - `samplingRate` number — A number between 0.0 and 1.0 indicating the probability of a request being traced (e.g., 1.0 for 100%, 0.1 for 10%). - `flushInterval` integer — Time in seconds to wait before sending buffered traces to the cloud. - `ignoreUrls` string — A list or comma-separated string of URL paths to exclude from tracing (e.g., /health, /metrics). - LangsmithConfig — Langsmith configuration. - `provider` 'LANGSMITH' - `apiKey` string — The unique authentication key from the LangSmith settings page. - `projectName` string — The name of the project in LangSmith to bucket these traces under (e.g., prod-chatbot-v1). - `endpoint` string — The URL endpoint, used primarily if you are self-hosting LangSmith or using a specific enterprise instance. (e.g., https://api.smith.langchain.com) - `runName` string — The display name for each trace run in LangSmith (e.g., my-agent). - `sso` SSOConfig — OIDC Single Sign-On configuration. When enabled, the engine validates JWT tokens on protected routes (``/agent/invoke``, ``/agent/stream``, ``/agent/copilotkit/stream``) against the configured OIDC provider's JWKS endpoint, discovered via ``{issuer}/.well-known/openid-configuration``. - `enabled` boolean — Toggle SSO enforcement on protected routes. - `issuer` string, required — OIDC issuer URL (e.g. https://accounts.google.com). Used to discover the JWKS endpoint via .well-known/openid-configuration. - `clientId` string, required — OAuth 2.0 client ID. Used as the default audience for JWT validation when 'audience' is not set. - `audience` string, nullable — Expected JWT 'aud' claim. Defaults to client_id if not set. Okta client credentials tokens use 'api://default'. - `allowedDomains` string[], nullable — Optional list of allowed email domains (e.g. ['company.com']). When set, only tokens whose email claim matches one of these domains are accepted. - `allowedEmails` string[], nullable — Optional list of specific email addresses allowed access. When set, only tokens whose email claim exactly matches one of these values are accepted. - `integrations` IntegrationConfig[], nullable - `provider` 'WHATSAPP' | 'DISCORD' | 'SLACK' | 'GOOGLE_CHAT' | 'TEAMS', required — Supported integration providers. - `enabled` boolean — Toggle this integration on or off. - `config` union, required — Provider-specific configuration. - WhatsAppIntegrationConfig — WhatsApp Business Cloud API configuration. Requires a Meta Business account with a WhatsApp Business API setup. The ``verify_token`` is used by Meta to validate the webhook endpoint during initial registration. - `accessToken` string, required — Meta Graph API permanent access token. - `phoneNumberId` string, required — WhatsApp Business phone number ID. - `verifyToken` string, required — Webhook verification token. Must match the token configured in the Meta App Dashboard webhook settings. - `apiVersion` string — Meta Graph API version. - DiscordIntegrationConfig — Discord bot configuration for the Interactions Endpoint webhook. Requires a Discord application with a bot user created at https://discord.com/developers/applications. The ``public_key`` is used to verify Ed25519 signatures on incoming interaction payloads. - `botToken` string, required — Discord bot token (used for REST API calls). - `applicationId` string, required — Discord application ID. - `publicKey` string, required — Ed25519 public key from the Discord application settings. Used to verify interaction webhook signatures. - `guildId` string, nullable — Optional guild (server) ID to restrict the integration to. - SlackIntegrationConfig — Slack Events API configuration. Requires a Slack app with a bot token and signing secret. The ``signing_secret`` is used to verify incoming webhook requests via HMAC-SHA256. - `botToken` string, required — Slack bot token (xoxb-...). - `signingSecret` string, required — Signing secret for verifying webhook requests. - GoogleChatIntegrationConfig — Google Chat app configuration. Requires a GCP project with the Google Chat API enabled, a service account for sending messages, and the project number for verifying inbound JWT bearer tokens. - `serviceAccountCredentialsJson` string, required — Service account credentials JSON for calling the Chat API. - `projectNumber` string, required — GCP project number used to verify inbound JWT tokens. - `localMode` boolean — When enabled, rewrites the webhook URL from http to https for JWT audience verification. Use this when developing behind a TLS-terminating proxy like ngrok. - TeamsIntegrationConfig — Microsoft Teams integration configuration. Single-tenant only: each customer registers their own Microsoft app in their own Azure AD and runs their own engine instance against it. Authentication uses Bot Framework's ``ConfigurationBotFrameworkAuthentication`` with ``MicrosoftAppType=SingleTenant`` hardcoded. - `appId` string, required — Microsoft App ID from the Azure AD app registration. - `appPassword` string, required — Client secret from the Azure AD app registration. - `appTenantId` string, required — Azure AD tenant ID that owns the app registration. - `prompts` PromptConfig[], nullable - `promptId` string, required — Logical prompt identifier - `version` integer, required — Prompt version number - `content` string, required — Prompt text, supports Jinja2 variables - `tags` string[] — Prompt tags - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `reload` StandaloneReloadResult, required — Reload outcome attached to every admin mutation response. ``reloaded`` means DB committed and runtime now uses the new config. ``restart_required`` means DB committed and process restart is needed. ``reload_failed`` means DB rolled back and runtime is unchanged. - `status` 'reloaded' | 'restart_required' | 'reload_failed', required — Outcome of a reload triggered by an admin mutation. - `message` string, required - `error` string, nullable ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/idun-group/apis/idun-agent-engine-server.md) · [All operations](https://skmtc.net/idun-group/apis/idun-agent-engine-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/idun-group/idun-agent-engine-server/versions/8909cd73cc1c/schema)