> ## Documentation Index > Fetch the complete documentation index at: https://docs.engini.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create connection > Creates a new connection for the caller's account using the given field values (e.g. API key, credentials) for the target application. authenticationId selects which of the application's authentication methods to use; omit it to use the application's default. To connect via OAuth instead of directly supplying credentials, use POST /connections/get-sign-in-url followed by GET /connections/access-token/{state}. ## OpenAPI ````yaml /developers/api-reference/openapi.json post /v1/connections openapi: 3.0.0 info: title: Engini API version: v1 description: The Engini public API. servers: - url: https://api.engini.io security: - Bearer: [] - ApiKey: [] tags: - name: Auth description: Identify the caller a Developer API request is authenticated as. - name: On-prem agents description: >- Provision and manage agents that run Engini tasks inside a customer's network. - name: Applications description: >- Discover the applications (toolkits) available in Engini and their connection requirements. - name: Tools description: Browse and execute the tools exposed by Engini applications. - name: Toolsets description: Manage toolsets - named groupings of connections and tools. - name: McpServers description: >- Inspect and maintain MCP servers - the account-wide endpoints that expose Engini tools and workflows over the Model Context Protocol. Distinct from the MCPClient connection kind, which is Engini consuming a third-party MCP server. - name: Connections description: >- Manage connections to applications, including OAuth sign-in and default-connection selection. - name: Triggers description: >- Create triggers that fire when something changes in a connected app, and manage the destinations their events are delivered to. paths: /v1/connections: post: tags: - Connections summary: Create connection description: >- Creates a new connection for the caller's account using the given field values (e.g. API key, credentials) for the target application. authenticationId selects which of the application's authentication methods to use; omit it to use the application's default. To connect via OAuth instead of directly supplying credentials, use POST /connections/get-sign-in-url followed by GET /connections/access-token/{state}. operationId: Connections_CreateConnection parameters: [] requestBody: x-name: request description: >- The connection creation payload, including the connection name and application slug. content: application/json: schema: $ref: '#/components/schemas/CreateConnectionRequest' example: applicationSlug: example-app connectionName: My Example Connection authenticationId: 1 fields: apiKey: eng_example1234567890 required: true x-position: 1 responses: '200': description: The newly created connection. content: application/json: schema: $ref: '#/components/schemas/ConnectionPublicDetail' example: connectionId: 123 connectionName: My Example Connection description: null applicationSlug: example-app applicationName: Example App applicationLogo: https://example.com/logo.png isPublic: false createdBy: 00000000-0000-0000-0000-000000000000 createdDate: '2026-01-01T00:00:00Z' '400': description: Bad request - malformed body or invalid parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - missing or invalid bearer token or API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - the caller lacks access to the resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - the resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests - rate limit exceeded. headers: Retry-After: description: Number of seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error - an unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] - ApiKey: [] x-codeSamples: - lang: python label: Python source: >- from engini import Engini client = Engini() # reads ENGINI_API_KEY # authentication_id comes from the application's authentication methods connection = client.connections.create( "slack", "Sales", 2, {"token": "xoxb-your-bot-token"} ) - lang: typescript label: TypeScript source: >- import { Engini } from "@engini/sdk"; const client = new Engini(); // reads ENGINI_API_KEY // authenticationId comes from the application's authentication methods const connection = await client.connections.create( "slack", "Sales", 2, { token: "xoxb-your-bot-token" }, ); - lang: bash label: CLI source: >- engini connections create slack --auth 2 --name Sales --field token=xoxb-your-bot-token components: schemas: CreateConnectionRequest: type: object description: Request body for creating a connection. additionalProperties: false required: - applicationSlug - connectionName - fields properties: applicationSlug: type: string description: Slug of the application to connect to. connectionName: type: string description: Display name for the new connection. description: type: string description: Optional description of the connection. nullable: true authenticationId: type: integer description: >- Identifier of the authentication method to use; omit to use the application's default. format: int32 nullable: true fields: type: object description: Connection field values, keyed by field name. additionalProperties: type: string metadata: type: object description: Optional additional connection metadata, keyed by name. nullable: true additionalProperties: type: string oauthState: type: string description: >- Opaque state from the sign-in URL. When set on an OAuth method, credentials are taken from the stored sign-in and any client-supplied values for those keys are ignored. nullable: true ConnectionPublicDetail: allOf: - $ref: '#/components/schemas/ConnectionPublicListItem' - type: object description: >- Public-shape detail for /v1/Connections/{id} and create/update responses. additionalProperties: false properties: authenticationId: type: integer description: Identifier of the authentication method used by the connection. format: int32 authenticationType: type: string description: Name of the authentication type used by the connection. fields: type: object description: >- Connection field values, keyed by field name (sensitive values may be masked). additionalProperties: type: string nullable: true useSelectDBObjects: type: boolean description: Whether the connection uses selected database objects. connectionError: type: string description: Last connection error message, if any. nullable: true isAlive: type: boolean description: Whether the connection is currently healthy/reachable. metadata: type: object description: Additional connection metadata, keyed by name. nullable: true additionalProperties: type: string ErrorResponse: type: object description: >- Unified machine-readable error envelope returned by every non-200 Developer API response. additionalProperties: false required: - errorCode - message - requestId - timestamp properties: errorCode: type: string description: Machine-readable error code identifying the failure. message: type: string description: Human-readable error message. requestId: type: string description: Identifier of the request, for support/correlation. timestamp: type: string description: Timestamp when the error occurred (ISO 8601). details: type: array description: Per-field validation details, when applicable. nullable: true items: $ref: '#/components/schemas/ErrorDetail' ConnectionPublicListItem: type: object description: >- Public-shape list item for /v1/Connections. Applications are identified by slug only (no ApplicationId in the wire response). Internal queries continue to use ConnectionList which carries both. additionalProperties: false required: - connectionId - connectionName - applicationSlug - kind - isPublic - createdBy - createdDate properties: connectionId: type: integer description: Identifier of the connection. format: int32 connectionName: type: string description: Display name of the connection. description: type: string description: Description of the connection. nullable: true applicationSlug: type: string description: Slug of the connection's application. applicationName: type: string description: Display name of the connection's application. nullable: true applicationLogo: type: string description: URL of the application's logo image. nullable: true kind: type: string description: >- Which kind of connection this is: Regular, Key or MCPClient. Mirrors the parent application's AppConnectionType. The engini.io Connections page's "Keys" tab is exactly the Key subset. On-premise agents are served by /v1/on-prem-agents. isPublic: type: boolean description: Whether the connection is shared/public. createdBy: type: string description: Identifier of the user who created the connection. format: uuid createdDate: type: string description: When the connection was created. format: date-time updatedBy: type: string description: >- Identifier of the user who last updated the connection; null if never updated. format: uuid nullable: true updatedDate: type: string description: When the connection was last updated; null if never updated. format: date-time nullable: true ErrorDetail: type: object description: A single field-level error detail within an ErrorResponse. additionalProperties: false required: - field - issue properties: field: type: string description: Name of the field the issue relates to. issue: type: string description: Description of the issue with the field. securitySchemes: Bearer: type: http description: Enter your JWT token scheme: bearer bearerFormat: JWT ApiKey: type: apiKey description: >- Opaque Developer API key (prefix `eng_`). Authenticates as the key's owner and resolves the account automatically. name: x-api-key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.