> ## Documentation Index > Fetch the complete documentation index at: https://docs.nvisy.com/llms.txt > Use this file to discover all available pages before exploring further. # Create connection > Creates a new provider connection for the workspace. Connection data is encrypted and stored securely. The response includes connection metadata but never exposes the encrypted credentials. ## OpenAPI ````yaml /api-reference/openapi.json post /workspaces/{workspaceSlug}/connections/ openapi: 3.1.0 info: title: Nvisy API summary: Document processing and annotation platform description: >- Nvisy provides intelligent document processing, annotation, and analysis capabilities. This API enables document upload, OCR processing, embedding generation, and semantic search across your document collections. termsOfService: https://nvisy.com/legal/terms-of-service contact: name: Nvisy Support url: https://nvisy.com email: hello@nvisy.com license: name: Proprietary url: https://nvisy.com/license version: 0.1.0 servers: [] security: [] tags: - name: Accounts description: Account management and profile operations - name: Authentication description: Login, signup, and token management - name: Workspaces description: Workspace creation and management - name: Files description: File upload, download, and management - name: Members description: Workspace member management - name: Invites description: Workspace invitation handling - name: API Tokens description: API token management - name: Connections description: External provider connections - name: Pipelines description: Redaction pipeline configuration - name: Pipeline Runs description: Pipeline run execution and review - name: Policies description: Redaction policy configuration - name: Webhooks description: Webhook configuration - name: Notifications description: Account notification management - name: Health description: Service health checks paths: /workspaces/{workspaceSlug}/connections/: post: tags: - Connections summary: Create connection description: >- Creates a new provider connection for the workspace. Connection data is encrypted and stored securely. The response includes connection metadata but never exposes the encrypted credentials. parameters: - in: path name: workspaceSlug description: URL-safe workspace identifier. required: true schema: description: URL-safe workspace identifier. type: string style: simple requestBody: description: Request payload for creating a new workspace connection. content: application/json: schema: $ref: '#/components/schemas/CreateConnection' required: true responses: '201': description: >- Response type for a workspace connection. Note: The encrypted connection data is never exposed in API responses. Only metadata about the connection is returned. content: application/json: schema: $ref: '#/components/schemas/Connection' '400': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Expected request with `Content-Type: application/json`' content: text/plain: schema: type: string '422': description: Failed to deserialize the JSON body into the target type content: text/plain: schema: type: string security: - BearerAuth: [] components: schemas: CreateConnection: description: Request payload for creating a new workspace connection. type: object properties: config: description: >- Typed provider configuration (provider tag + its credentials), encrypted at rest. The `provider` tag selects which credential shape is required and which capability the connection has. allOf: - $ref: '#/components/schemas/ConnectionConfig' displayName: description: Human-readable connection display name. type: string maxLength: 255 minLength: 1 isActive: description: >- Whether the connection is enabled. Omit to default to active; set `false` to create it disabled. type: boolean sync: $ref: '#/components/schemas/SyncScheduleInput' description: |- Sync configuration. Applies only to sync-capable providers (object stores); rejected for others. Omit for manual-only defaults. required: - displayName - config Connection: description: |- Response type for a workspace connection. Note: The encrypted connection data is never exposed in API responses. Only metadata about the connection is returned. type: object properties: createdAt: description: When the connection was created. type: string format: date-time createdBy: description: Account that created this connection. allOf: - $ref: '#/components/schemas/AccountRef' displayName: description: Human-readable connection display name. type: string id: description: Opaque identifier of the connection. allOf: - $ref: '#/components/schemas/ConnectionId' isActive: description: Whether the connection is enabled. type: boolean provider: description: Provider identifier (`s3`, `azure`, `gcs`, `openai`, `ollama`, ...). type: string sync: $ref: '#/components/schemas/SyncSchedule' description: Sync configuration; present only for sync-capable connections. updatedAt: description: When the connection was last updated. type: string format: date-time workspaceSlug: description: Handle of the workspace this connection belongs to. allOf: - $ref: '#/components/schemas/Handle' required: - id - workspaceSlug - createdBy - displayName - provider - isActive - createdAt - updatedAt ErrorResponse: description: |- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. type: object properties: message: description: User-friendly error message safe for client display type: string name: description: The error name/type identifier type: string resource: description: The resource that the error relates to (optional, set by handler) type: string suggestion: description: Helpful suggestion for resolving the error (optional) type: string validation: description: Validation error details for field-specific errors type: array items: $ref: '#/components/schemas/ValidationErrorDetail' required: - name - message ConnectionConfig: description: >- A fully-typed connection configuration for any capability. Untagged: the two inner enums have disjoint `provider` values, so serde resolves the variant from the flat payload without an outer discriminator. anyOf: - description: An object-storage connection (s3, azure, gcs) — sync-capable. allOf: - $ref: '#/components/schemas/StorageConfig' - description: An LLM inference connection (openai, ollama, anthropic). allOf: - $ref: '#/components/schemas/LlmConfig' SyncScheduleInput: description: >- Sync configuration for a sync-capable connection (object stores). Only meaningful for connections whose provider supports syncing; omitted for connections that do not (e.g. LLM inference). type: object properties: deletionPolicy: description: How an import reconciles files whose source object was deleted. allOf: - $ref: '#/components/schemas/SyncDeletionPolicy' default: ignore scheduleCron: description: Cron expression for scheduled imports; omit for manual-only. type: string maxLength: 100 minLength: 9 syncMode: description: Whether the connection imports data in or exports data out. allOf: - $ref: '#/components/schemas/SyncMode' default: import AccountRef: description: >- Public reference to the account behind a resource — whoever created it, uploaded it, triggered it, or performed it. Reused across resource responses so an account is always presented the same way: a handle plus an optional avatar. type: object properties: avatarUrl: description: Serve path of the account's avatar, when set. type: string displayName: description: Human-readable display name, when set. type: string username: description: Handle of the account. allOf: - $ref: '#/components/schemas/Handle' required: - username ConnectionId: description: Opaque conn identifier (conn_). type: string pattern: >- ^conn_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ SyncSchedule: description: >- A connection's sync configuration, present only for sync-capable connections. type: object properties: deletionPolicy: description: How an import reconciles files whose source object was deleted. allOf: - $ref: '#/components/schemas/SyncDeletionPolicy' lastSynced: description: When the connection last synced successfully, if ever. type: string format: date-time scheduleCron: description: Cron expression for scheduled imports, if configured. type: string syncMode: description: Whether the connection imports data in or exports data out. allOf: - $ref: '#/components/schemas/SyncMode' required: - syncMode - deletionPolicy Handle: description: >- Lowercase, dash-separated identifier used in URLs and as account handles. type: string maxLength: 32 minLength: 3 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ ValidationErrorDetail: description: Validation error details for field-specific errors. type: object properties: code: description: Error code for the validation failure type: string field: description: Field name that failed validation type: string message: description: Human-readable error message type: string params: description: Additional parameters related to the validation error type: object additionalProperties: true required: - field - code - message StorageConfig: description: >- A fully-typed object-store connection configuration. The `provider` tag selects the variant and thereby the credential shape, so an S3 connection cannot carry Azure credentials. Each variant carries a shared optional `root_path` and a nested `credentials` object, giving a wire shape like `{ "provider": "s3", "rootPath": "in/", "credentials": { "bucket": "b", "accessKeyId": "..." } }`. Secrets are masked in [`Debug`]; serialization exists only to persist the config encrypted at rest, never to return it in API responses. oneOf: - description: S3-compatible provider (AWS S3, MinIO, and so on). type: object properties: credentials: description: S3 credentials. allOf: - $ref: '#/components/schemas/S3Credentials' provider: type: string const: s3 rootPath: description: >- Optional root prefix within the bucket; keys resolve relative to it. type: string required: - provider - credentials - description: Azure Blob Storage provider. type: object properties: credentials: description: Azure credentials. allOf: - $ref: '#/components/schemas/AzureCredentials' provider: type: string const: azure rootPath: description: >- Optional root prefix within the container; keys resolve relative to it. type: string required: - provider - credentials - description: Google Cloud Storage provider. type: object properties: credentials: description: GCS credentials. allOf: - $ref: '#/components/schemas/GcsCredentials' provider: type: string const: gcs rootPath: description: >- Optional root prefix within the bucket; keys resolve relative to it. type: string required: - provider - credentials LlmConfig: description: >- A fully-typed LLM inference connection configuration. The `provider` tag selects the variant and thereby the credential shape, so an OpenAI connection cannot carry Anthropic credentials. Serialization exists only to persist the config encrypted at rest, never to return it in API responses. oneOf: - description: OpenAI (or an OpenAI-compatible endpoint). type: object properties: baseUrl: description: >- Override the API base URL (for Azure OpenAI or a proxy). Optional. type: string credentials: description: OpenAI credentials. allOf: - $ref: '#/components/schemas/OpenAiCredentials' defaultModel: description: >- Default model to use when a request does not specify one. Optional. type: string provider: type: string const: openai required: - provider - credentials - description: Ollama, typically self-hosted. type: object properties: baseUrl: description: Base URL of the Ollama server (e.g. `http://localhost:11434`). type: string defaultModel: description: >- Default model to use when a request does not specify one. Optional. type: string provider: type: string const: ollama required: - provider - baseUrl - description: Anthropic (Claude). type: object properties: baseUrl: description: Override the API base URL. Optional. type: string credentials: description: Anthropic credentials. allOf: - $ref: '#/components/schemas/AnthropicCredentials' defaultModel: description: >- Default model to use when a request does not specify one. Optional. type: string provider: type: string const: anthropic required: - provider - credentials SyncDeletionPolicy: description: >- What an import does with a file whose source object no longer exists. Corresponds to the `SYNC_DELETION_POLICY` PostgreSQL enum. Deletion is opt-in per connection: the default `Ignore` keeps imports strictly additive so a transient listing error or a misconfigured root path can never remove files. oneOf: - description: Leave the imported file untouched when its source object is gone. type: string const: ignore - description: >- Delete the imported file when its source object is gone: the file row is soft-deleted (preserving import provenance) and its stored object is removed to reclaim storage. type: string const: delete SyncMode: description: >- The direction a connection syncs data. Corresponds to the `SYNC_MODE` PostgreSQL enum: `Import` fetches objects from the connection into the workspace; `Export` pushes workspace files out. oneOf: - description: Fetch objects from the connection into the workspace. type: string const: import - description: Push workspace files out to the connection. type: string const: export S3Credentials: description: >- Typed credentials for S3-compatible provider. Secret fields are masked in the [`Debug`] output. Serialization exists only to persist the credentials encrypted at rest; they are never returned in API responses. type: object properties: accessKeyId: description: Access key ID for static credentials. type: string default: null bucket: description: S3 bucket name. type: string endpoint: description: |- Endpoint URL (e.g. `http://localhost:9000` for MinIO). Required for non-AWS S3-compatible services. type: string default: null region: description: AWS region (defaults to `us-east-1`). type: string default: us-east-1 secretAccessKey: description: Secret access key for static credentials. type: string default: null sessionToken: description: Session token for temporary credentials. type: string default: null required: - bucket AzureCredentials: description: >- Typed credentials for Azure Blob Storage. Secret fields are masked in the [`Debug`] output. Serialization exists only to persist the credentials encrypted at rest; they are never returned in API responses. type: object properties: accessKey: description: Storage account access key. type: string default: null accountName: description: Azure storage account name. type: string container: description: Azure storage container name. type: string endpoint: description: Custom endpoint URL (for Azure Stack or Azurite). type: string default: null sasToken: description: Shared Access Signature token. type: string default: null required: - container - accountName GcsCredentials: description: >- Typed credentials for Google Cloud Storage. Secret fields are masked in the [`Debug`] output. Serialization exists only to persist the credentials encrypted at rest; they are never returned in API responses. type: object properties: bucket: description: GCS bucket name. type: string endpoint: description: Custom endpoint URL (for testing with a fake GCS server). type: string default: null serviceAccountKeyJson: description: Inline service account key JSON (the file contents, not a path). type: string default: null serviceAccountPath: description: Path to a service account key JSON file on the local filesystem. type: string default: null required: - bucket OpenAiCredentials: description: OpenAI API credentials. type: object properties: apiKey: description: OpenAI API key. type: string required: - apiKey AnthropicCredentials: description: Anthropic API credentials. type: object properties: apiKey: description: Anthropic API key. type: string required: - apiKey ````