> ## Documentation Index > Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Custom Integration > Create a new custom integration instance. **Configuration Options:** - `env_vars`: Key-value pairs for environment variables - `secrets`: List of secret names to resolve from vault - `files`: List of files to create in workspace - `context_prompt`: Contextual guidance for AI agents - `connection_test`: Optional command to test connectivity **Name Requirements:** - Must be unique within the organization - Cannot be empty - Alphanumeric and hyphens recommended **Example Request:** ```json { "name": "production-postgres", "integration_type": "postgres", "description": "Production PostgreSQL database", "config": { "env_vars": { "DB_HOST": "postgres.prod.example.com", "DB_PORT": "5432", "DB_NAME": "production" }, "secrets": ["DB_PASSWORD"], "files": [ { "path": "~/.postgresql/client.crt", "secret_ref": "POSTGRES_CLIENT_CERT", "mode": "0600" } ], "context_prompt": "Production database - use connection pooling" }, "tags": ["production", "database"] } ``` ## OpenAPI ````yaml https://control-plane.kubiya.ai/api/openapi.json post /api/v1/custom-integrations openapi: 3.1.0 info: title: Agent Control Plane API description: Multi-tenant agent orchestration with Temporal workflows version: 1.0.0 servers: [] security: - BearerAuth: [] tags: - name: health description: πŸ₯ **Health & Status** - Check API health and availability - name: authentication description: πŸ” **Authentication** - Token validation and auth management - name: agents description: πŸ€– **Agents** - Create and manage AI agents with custom capabilities - name: skills description: πŸ› οΈ **Tool Sets** - Manage agent skills and tool configurations - name: integrations description: πŸ”Œ **Integrations** - Connect to external services (Kubiya managed) - name: custom-integrations description: >- βš™οΈ **Custom Integrations** - User-defined integration instances with env vars, secrets, and files - name: integration-templates description: >- πŸ“¦ **Integration Templates** - Pre-configured templates for common services (PostgreSQL, Redis, MongoDB, etc.) - name: secrets description: πŸ”‘ **Secrets** - Secure credential storage and retrieval - name: teams description: πŸ‘₯ **Teams** - Team management and collaboration - name: workflows description: πŸ“Š **Workflows** - Multi-step automation and orchestration - name: executions description: ▢️ **Executions** - Track and monitor workflow runs - name: jobs description: ⏰ **Jobs** - Scheduled and webhook-triggered tasks - name: policies description: πŸ›‘οΈ **Policies** - Access control and security policies - name: analytics description: πŸ“ˆ **Analytics** - Usage metrics and performance monitoring - name: projects description: πŸ“ **Projects** - Project organization and management - name: environments description: 🌍 **Environments** - Environment configuration (dev, staging, prod) - name: models description: 🧠 **Models** - LLM model configuration and management - name: runtimes description: ⚑ **Runtimes** - Agent execution runtime environments - name: workers description: πŸ‘· **Workers** - Worker registration and heartbeat monitoring - name: storage description: πŸ’Ύ **Storage** - File storage and cloud integration - name: context-graph description: πŸ•ΈοΈ **Context Graph** - Knowledge graph and context management - name: temporal-workflows description: >- βš™οΈ **Temporal Workflows** - Background workflows for context graph ingestion, connector operations, and scheduled jobs - name: templates description: πŸ“ **Templates** - Reusable configuration templates paths: /api/v1/custom-integrations: post: tags: - custom-integrations summary: Create Custom Integration description: |- Create a new custom integration instance. **Configuration Options:** - `env_vars`: Key-value pairs for environment variables - `secrets`: List of secret names to resolve from vault - `files`: List of files to create in workspace - `context_prompt`: Contextual guidance for AI agents - `connection_test`: Optional command to test connectivity **Name Requirements:** - Must be unique within the organization - Cannot be empty - Alphanumeric and hyphens recommended **Example Request:** ```json { "name": "production-postgres", "integration_type": "postgres", "description": "Production PostgreSQL database", "config": { "env_vars": { "DB_HOST": "postgres.prod.example.com", "DB_PORT": "5432", "DB_NAME": "production" }, "secrets": ["DB_PASSWORD"], "files": [ { "path": "~/.postgresql/client.crt", "secret_ref": "POSTGRES_CLIENT_CERT", "mode": "0600" } ], "context_prompt": "Production database - use connection pooling" }, "tags": ["production", "database"] } ``` operationId: create_custom_integration_api_v1_custom_integrations_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomIntegrationRequest' responses: '201': description: Integration created successfully content: application/json: schema: $ref: '#/components/schemas/CustomIntegrationResponse' '409': description: Integration with this name already exists '422': description: Validation error components: schemas: CreateCustomIntegrationRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: Integration name integration_type: type: string maxLength: 100 minLength: 1 title: Integration Type description: Integration type description: anyOf: - type: string - type: 'null' title: Description description: Description config: $ref: '#/components/schemas/CustomIntegrationConfig' description: Integration configuration tags: items: type: string type: array title: Tags description: Tags type: object required: - name - integration_type - config title: CreateCustomIntegrationRequest description: Request to create a custom integration example: config: context_prompt: Production database - handle with care env_vars: DB_HOST: postgres.prod.example.com DB_PORT: '5432' secrets: - DB_PASSWORD description: Production PostgreSQL database integration_type: postgres name: production-database tags: - production - database CustomIntegrationResponse: properties: id: type: string title: Id organization_id: type: string title: Organization Id name: type: string title: Name integration_type: type: string title: Integration Type description: anyOf: - type: string - type: 'null' title: Description status: type: string title: Status config: additionalProperties: true type: object title: Config tags: items: type: string type: array title: Tags created_at: type: string title: Created At updated_at: type: string title: Updated At created_by: anyOf: - type: string - type: 'null' title: Created By type: object required: - id - organization_id - name - integration_type - description - status - config - tags - created_at - updated_at - created_by title: CustomIntegrationResponse description: Custom integration response CustomIntegrationConfig: properties: env_vars: additionalProperties: type: string type: object title: Env Vars description: Environment variables secrets: items: type: string type: array title: Secrets description: Secret names from vault files: items: $ref: '#/components/schemas/FileConfig' type: array title: Files description: Files to create context_prompt: anyOf: - type: string - type: 'null' title: Context Prompt description: Contextual guidance for agent connection_test: anyOf: - $ref: '#/components/schemas/ConnectionTest' - type: 'null' description: Connection test config type: object title: CustomIntegrationConfig description: Custom integration configuration example: context_prompt: Production PostgreSQL database. Use connection pooling. env_vars: DB_HOST: postgres.prod.example.com DB_NAME: production DB_PORT: '5432' files: - mode: '0600' path: ~/.postgresql/client.crt secret_ref: POSTGRES_CLIENT_CERT secrets: - DB_PASSWORD - DB_SSL_CERT FileConfig: properties: path: type: string title: Path description: File path (e.g., ~/.postgresql/client.crt) content: anyOf: - type: string - type: 'null' title: Content description: File content (direct) secret_ref: anyOf: - type: string - type: 'null' title: Secret Ref description: Secret name to load content from mode: anyOf: - type: string - type: 'null' title: Mode description: File permissions (octal) default: '0644' description: anyOf: - type: string - type: 'null' title: Description description: Description of this file type: object required: - path title: FileConfig description: Configuration for a file to be written to workspace example: content: |- -----BEGIN CERTIFICATE----- ... description: PostgreSQL client certificate mode: '0600' path: ~/.postgresql/client.crt ConnectionTest: properties: enabled: type: boolean title: Enabled description: Whether to test connection default: true command: type: string title: Command description: Command to run for testing timeout: type: integer title: Timeout description: Timeout in seconds default: 5 type: object required: - command title: ConnectionTest description: Configuration for testing integration connectivity example: command: pg_isready -h $DB_HOST -p $DB_PORT enabled: true timeout: 5 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Enter your Kubiya API token (format: Bearer )' ````