> For the complete documentation index, see [llms.txt](https://docs.qapilot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qapilot.io/api-documentation/qapilot-application-upload-app-source-api.md).

# QApilot – Application Upload (App Source) API

API to help upload app source - an alternative to manually uploading it from the platform UI

## &#x20;<a href="#qapilot-application-upload-webhook-api" id="qapilot-application-upload-webhook-api"></a>

### 1. Overview <a href="#id-1-overview" id="id-1-overview"></a>

The Application Upload Webhook API allows users to upload or update an application in an existing AppSource in QApilot without manually uploading the application through the QApilot UI.

**Scope:** This API is supported exclusively for **Cloud AppSource**.

The API uses Basic Authentication to authenticate the user and an AppSource-specific API token to identify and authorize the target AppSource.

Additionally, the API validates the uploaded application's package name against the existing application to ensure that an application belonging to a different package cannot be uploaded to the same AppSource.

### 2. API Details <a href="#id-2-api-details" id="id-2-api-details"></a>

| Property            | Details                                            |
| ------------------- | -------------------------------------------------- |
| API Name            | Application Upload Webhook                         |
| Endpoint            | `https://api.qapilot.io/internal/appsource/upload` |
| HTTP Method         | `POST`                                             |
| Content Type        | `multipart/form-data`                              |
| Authentication      | HTTP Basic Authentication                          |
| Required Header     | `x-api-token`                                      |
| Supported AppSource | Cloud AppSource only                               |

### 3. Authentication <a href="#id-3-authentication" id="id-3-authentication"></a>

The API requires two authentication mechanisms.

#### 3.1 Basic Authentication <a href="#id-31-basic-authentication" id="id-31-basic-authentication"></a>

Provide a valid QApilot username and password using HTTP Basic Authentication.

These credentials follow the same authentication mechanism used for MCP integration in QApilot.

Example:

```http
Authorization: Basic <base64-encoded-credentials>
```

The encoded credentials represent the username and password in the standard HTTP Basic Authentication format.

#### 3.2 AppSource API Token <a href="#id-32-appsource-api-token" id="id-32-appsource-api-token"></a>

The `x-api-token` header must contain the authentication token associated with the target AppSource.

**How to obtain the token:**

1. Log in to QApilot.
2. Navigate to the required AppSource.
3. Click on the three-dot menu (⋮) associated with the AppSource.
4. Click on Generate Token.
5. Copy the generated token and include it in the request header.

Example:

```http
x-api-token: <APP_SOURCE_API_TOKEN>
```

The API uses this token to validate the request against the intended AppSource.

### 4. Request Specification <a href="#id-4-request-specification" id="id-4-request-specification"></a>

#### 4.1 Headers <a href="#id-41-headers" id="id-41-headers"></a>

| Header          | Required | Description                                                              |
| --------------- | -------- | ------------------------------------------------------------------------ |
| `Authorization` | Yes      | Basic Authentication credentials                                         |
| `x-api-token`   | Yes      | API token associated with the target AppSource                           |
| `Content-Type`  | Yes      | `multipart/form-data`; the client should generate the multipart boundary |

#### 4.2 Request Body <a href="#id-42-request-body" id="id-42-request-body"></a>

The request body must use `multipart/form-data` and contain the application file in the `file` field.

| Field  | Type | Required | Description                                                  |
| ------ | ---- | -------- | ------------------------------------------------------------ |
| `file` | File | Yes      | Application binary to upload to the existing Cloud AppSource |

The uploaded application must be compatible with the target AppSource and must have the same package name as the application already associated with it.

### 5. Sample Request <a href="#id-5-sample-request" id="id-5-sample-request"></a>

#### cURL <a href="#curl" id="curl"></a>

```bash
curl --location \  --request POST \  'https://<QAPILOT_BASE_URL>https://api.qapilot.io/internal/appsource/upload' \  --user '<USERNAME>:<PASSWORD>' \  --header 'x-api-token: <APP_SOURCE_API_TOKEN>' \  --form 'file=@"/path/to/application.apk"'
```

**Replace the following placeholders:**

* `<QAPILOT_BASE_URL>` — Base URL of the QApilot environment.
* `<USERNAME>` — Valid QApilot username.
* `<PASSWORD>` — Valid QApilot password.
* `<APP_SOURCE_API_TOKEN>` — API token of the target Cloud AppSource.
* `/path/to/application.apk` — Local path to the application file.

The example uses an APK file. Supply the appropriate application artifact supported by the target Cloud AppSource.

The `--user` option configures Basic Authentication. The `--form` option sends the application file as multipart form data.

### 6. Expected Behaviour <a href="#id-6-expected-behaviour" id="id-6-expected-behaviour"></a>

The API processes the request through the following validation and upload flow.

#### Step 1: Authenticate the User <a href="#step-1-authenticate-the-user" id="step-1-authenticate-the-user"></a>

The API validates the supplied Basic Authentication credentials.

* Valid credentials: Continue processing.
* Invalid or missing credentials: Reject the request.

#### Step 2: Validate the AppSource Token <a href="#step-2-validate-the-appsource-token" id="step-2-validate-the-appsource-token"></a>

The API validates the `x-api-token` header against the target AppSource.

* Valid token: Continue processing.
* Invalid or missing token: Reject the request.

#### Step 3: Validate the Uploaded File <a href="#step-3-validate-the-uploaded-file" id="step-3-validate-the-uploaded-file"></a>

The API checks that the request contains a valid application file.

* Valid file: Continue processing.
* Missing, empty, malformed, or otherwise invalid file: Reject the request as applicable.

#### Step 4: Validate the Application Package Name <a href="#step-4-validate-the-application-package-name" id="step-4-validate-the-application-package-name"></a>

The API checks whether the uploaded application's package name matches the package name of the application already associated with the target AppSource.

* **Package names match:** Continue with the upload.
* **Package names differ:** Reject the request with an appropriate validation error.

This validation prevents an application belonging to a different package from being uploaded to the existing AppSource.

#### Step 5: Upload the Application <a href="#step-5-upload-the-application" id="step-5-upload-the-application"></a>

After all validations succeed, the API uploads the application to the corresponding existing Cloud AppSource.

No new AppSource is created as part of this operation.

### 7. Error Handling <a href="#id-7-error-handling" id="id-7-error-handling"></a>

The API rejects requests that fail authentication, token validation, file validation, or package-name validation.

The following table describes the expected error scenarios. Exact HTTP status codes, response fields, and error messages should follow the implementation.

| Scenario                                                    | Expected Behaviour                                           |
| ----------------------------------------------------------- | ------------------------------------------------------------ |
| Missing or invalid Basic Authentication credentials         | Reject the request with an authentication error              |
| Missing `x-api-token` header                                | Reject the request with a validation or authentication error |
| Invalid AppSource API token                                 | Reject the request                                           |
| Missing application file                                    | Reject the request with a file validation error              |
| Invalid or unsupported application file                     | Reject the request with an appropriate file validation error |
| Uploaded package name differs from the existing application | Reject the request with a package-name mismatch error        |
| Successful validation and upload                            | Return a success response                                    |

Clients should inspect the HTTP status code and response body to determine whether the upload succeeded or failed.

> Note: Specific status codes, error codes, and response payloads are intentionally not prescribed here because they were not included in the API specification.

### 8. Important Notes and Constraints <a href="#id-8-important-notes-and-constraints" id="id-8-important-notes-and-constraints"></a>

1. **Cloud AppSource only:** This API is not intended for local or other unsupported AppSource types.
2. **Existing AppSource:** The API uploads the application to an existing AppSource identified through its API token.
3. **Package-name validation:** The uploaded application must have the same package name as the existing application. A mismatch results in rejection.
4. **Authentication required:** Both Basic Authentication and the AppSource-specific API token must be supplied.
5. **Multipart upload:** The application must be submitted using the `file` form-data field.
6. **No automatic package replacement on mismatch:** An application with a different package name must not be uploaded to the target AppSource.

### 9. Example Workflow <a href="#id-9-example-workflow" id="id-9-example-workflow"></a>

1. The user obtains the Basic Authentication credentials and API token.
2. The user selects the application file to upload.
3. The client sends a `POST` request to `https://api.qapilot.io/internal/appsource/upload`.
4. QApilot validates the credentials and API token.
5. QApilot validates the uploaded file and compares its package name with the existing application's package name.
6. If all validations pass, QApilot uploads the application to the existing Cloud AppSource.
7. If any validation fails, QApilot rejects the request and returns an appropriate error response.

### 10. Summary <a href="#id-10-summary" id="id-10-summary"></a>

The Application Upload API provides a programmatic way to upload an application to an existing QApilot Cloud AppSource.

It supports Basic Authentication, AppSource-specific token validation, multipart file uploads, and package-name consistency checks to ensure that only the intended application is uploaded to the target AppSource.

**Endpoint:** `POST https://api.qapilot.io/internal/appsource/upload`

**Required inputs:** Basic Authentication credentials, `x-api-token`, and the application file in the `file` form-data field.
