# App Runtime API

The **App Runtime API** provides a set of RESTful endpoints that enable **external systems** to interact with entities created in **App Designer**.

These APIs allow clients to **insert, update, retrieve, and delete entity data** stored in the application database.\
All operations are executed through the ONEWEB runtime and follow the platform’s authentication and authorization rules.

The API endpoints can be accessed by appending the method paths to the application’s **context root**.

***

### API Capabilities

Using the App Runtime API, consumers can:

* Authenticate and establish a runtime session
* Query entity data in JSON format
* Retrieve entity records by key
* Persist entity data to the database
* Delete entity records
* Save parent–child entity structures
* Upload and download files

***

### Authentication Endpoint

#### `POST /login`

Authenticates the user and initializes a runtime session.

* **Description**\
  Performs the login process and returns a token or session identifier required for subsequent API calls.
* **HTTP Method**\
  `POST`

***

### Entity Data APIs

#### `GET /entity/{entityID}/search`

Searches for entity records using parameters provided in the request URL.

* **Description**\
  Returns entity data in JSON format for the specified `{entityID}` based on search criteria.
* **HTTP Method**\
  `GET`

***

#### `GET /entity/{entityID}/get`

Retrieves full entity data using a key parameter.

* **Description**\
  Returns JSON data for all modules of the specified entity after providing the entity key in the request URL.
* **HTTP Method**\
  `GET`

***

#### `POST /entity/{entityID}/save`

Persists entity data to the database.

* **Description**\
  Saves the JSON payload of the specified `{entityID}` into the database.
* **HTTP Method**\
  `POST`

***

#### `POST /entity/{entityID}/delete`

Deletes entity data from the database.

* **Description**\
  Removes entity data based on the key parameter.
* **HTTP Method**\
  `POST`

***

#### `POST /entities/save?mainEntityID={entityID}`

Saves hierarchical entity data in a single request.

* **Description**\
  Persists JSON data in **Parent–Child Tab** format for the specified main entity.
* **HTTP Method**\
  `POST`

***

### File Management APIs

#### `POST /file/upload`

Uploads a file to the server.

* **Description**\
  Uploads a file according to the configured file storage settings.
* **HTTP Method**\
  `POST`

***

#### `GET /file/{id}/download`

Downloads a previously uploaded file.

* **Description**\
  Retrieves the file associated with the specified file `{id}` from the server.
* **HTTP Method**\
  `GET`

***

### Summary

The App Runtime API enables secure, REST‑based interaction with application entities and files managed by ONEWEB.

Key characteristics:

* RESTful, session‑based API design
* JSON‑based request and response payloads
* Supports CRUD operations on entities
* Enables integration with external systems
* Fully governed by ONEWEB runtime security

This API forms the foundation for **external integration**, **automation**, and **system‑to‑system communication** within the ONEWEB platform.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onewebstack.com/oneweb-platform-th/api-reference/app-runtime-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.