> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# GetOrCreateCompanionApp

# Package: companionApps

# Namespace: CompanionApps

# Method link: https://dev.wix.com/docs/api-reference/app-management/companion-apps/get-or-create-companion-app.md

## Introduction

Retrieves the companion app for the current site, creating and installing it if it doesn't exist.

The request must be made in the context of a Wix site.

If installation fails, the method returns an error but keeps the newly created companion app.
Call the method again to retry installation.

---

## REST API

### Schema

```
 Method: getOrCreateCompanionApp
 Description: Retrieves the companion app for the current site, creating and installing it if it doesn't exist.  The request must be made in the context of a Wix site.  If installation fails, the method returns an error but keeps the newly created companion app. Call the method again to retry installation.
 URL: https://www.wixapis.com/apps/v1/companion-apps/get-or-create
 Method: POST
 Return type: GetOrCreateCompanionAppResponse
  - name: companionApp | type: CompanionApp | description: Companion app that was retrieved, or created and installed successfully.  
     - name: id | type: string | description: Companion app GUID.  | read-only: true | validation: format GUID
     - name: status | type: CompanionAppStatus | description: Status of the companion app. `READY` means the companion app can be used, `CLONING` means site duplication is still in progress, and `CLONE_FAILED` means the duplication process didn't complete successfully.  
         - enum:
         -     CLONING: The companion app is being prepared during site duplication and may not be ready to use.
         -     READY: The companion app is ready to use on the current site.
         -     CLONE_FAILED: The companion app couldn't be prepared during site duplication. Retry duplication later or show the failure to the user.
     - name: createdDate | type: string | description: Date and time the companion app was created.  | read-only: true | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the companion app was last updated.  | read-only: true | validation: format date-time


```

### Examples

### Get or create a companion app
Retrieves the current site's companion app, or creates and installs it if it doesn't already exist.

```curl
curl -X POST \
'https://www.wixapis.com/apps/v1/companion-apps/get-or-create' \
-H 'Authorization: <AUTH>'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.companionApps.companionApps.getOrCreateCompanionApp()
 Description: Retrieves the companion app for the current site, creating and installing it if it doesn't exist.  The request must be made in the context of a Wix site.  If installation fails, the method returns an error but keeps the newly created companion app. Call the method again to retry installation.
 Return type: PROMISE<GetOrCreateCompanionAppResponse>
  - name: companionApp | type: CompanionApp | description: Companion app that was retrieved, or created and installed successfully.  
     - name: _id | type: string | description: Companion app GUID.  | read-only: true | validation: format GUID
     - name: status | type: CompanionAppStatus | description: Status of the companion app. `READY` means the companion app can be used, `CLONING` means site duplication is still in progress, and `CLONE_FAILED` means the duplication process didn't complete successfully.  
         - enum:
         -     CLONING: The companion app is being prepared during site duplication and may not be ready to use.
         -     READY: The companion app is ready to use on the current site.
         -     CLONE_FAILED: The companion app couldn't be prepared during site duplication. Retry duplication later or show the failure to the user.
     - name: _createdDate | type: Date | description: Date and time the companion app was created.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the companion app was last updated.  | read-only: true 


```

### Examples

### Get or create a companion app
Retrieves the current site's companion app, or creates and installs it if it doesn't already exist.

```javascript
import { companionApps } from "@wix/companion-apps";

async function getOrCreateCompanionApp() {
  const response = await companionApps.getOrCreateCompanionApp();
}

/* Promise resolves to:
 * {
 *   "companionApp": {
 *     "_id": "b59368ab-f194-452b-9fde-12123d4177ba",
 *     "status": "READY",
 *     "_createdDate": "2026-08-06T11:36:07.490Z",
 *     "_updatedDate": "2026-08-06T11:36:07.490Z"
 *   }
 * }
 */

```

### getOrCreateCompanionApp (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { companionApps } from '@wix/companion-apps';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { companionApps },
  // Include the auth strategy and host as relevant
});


async function getOrCreateCompanionApp() {
  const response = await myWixClient.companionApps.getOrCreateCompanionApp();
};
```

---