# Registering via REST

Each app can be registered with a set of endpoints that return the status of each app’s running instances. These endpoints are called `runners` and allow Lenses to get the running instances’ status by pinging these endpoints. The app state is consolidated based on the individual runner’s state, which is periodically checked.

Each runner can be only:

* **RUNNING** - When the health-check endpoints return 200 HTTP Status Code
* **UNKNOWN** - When the health-check endpoints return anything other than 200 HTTP Status Code

Lenses consolidates the individual runners’ statuses into a single app state:

* **RUNNING** - All Runners are `RUNNING`
* **WARNING** - At least 1 Runner is `UNKWOWN`
* **UNKNOWN** - No information about Runners, either they are unreachable

## Registering a new application

To add your external apps to Lenses, you can currently use the API by doing a `POST` to `api/v1/apps/external` endpoint.

```bash
curl -X POST \
  <LENSES_HOST_URL>/api/v1/apps/external \
  -H 'Content-Type: application/json' \
  -H 'X-Kafka-Lenses-Token: <LENSES_AUTH_TOKEN>' \
  -d '{
    "name": "Example_Producer_App",
    "metadata": {
        "version": "1.0.0",
        "owner": "Lenses",
        "deployment": "K8s",
        "tags": [
            "fraud",
            "detection",
            "app"
        ]
    },
    "input": [{"name": "fraud_input_topic"}],
    "output": [{"name": "fraud_output_topic"}],
    "runners": [{"url": "<YOUR_HEALTH_CHECK_URL_1>", "name": "Example_Runner"}]
}'
```

## Viewing your application in the Lenses

**Apps** are another type of built-in application. Go to `Workspace->Apps` to view your application.

In the application details page, you can see additional information about each application, and also information about each runner, along with metadata information, such as `Description`, and auditing information such as `Created At`, `Created By` and `Modified At`, `Modified By`.

## Scaling your application runners

You can add runners with a `POST` request to `api/v1/apps/external`. The body of the new request should be the same as the first one except for the `runners` key. What needs to be changed is only the array of the `runners` key.

```bash
curl -X POST \
  <LENSES_HOST_URL>/api/v1/apps/external \
  -H 'Content-Type: application/json' \
  -H 'X-Kafka-Lenses-Token: <LENSES_AUTH_TOKEN>' \
  -d '{
    "name": "Example_Producer_App",
    "metadata": {
        "version": "1.0.0",
        "owner": "Lenses",
        "deployment": "K8s",
        "tags": [
            "fraud",
            "detection",
            "app"
        ]
    },
    "input": [{"name": "fraud_input_topic"}],
    "output": [{"name": "fraud_output_topic"}],
    "runners": [{"url": "<YOUR_HEALTH_CHECK_URL_2>", "name": "Example_Runner"}]
}'
```

You can also remove runners with a DELETE request.

```bash
curl -X DELETE <LENSES_HOST_URL>/api/v1/apps/external/Example_Producer_App/runners \
-H 'Content-Type: application/json' \
-H 'X-Kafka-Lenses-Token: <LENSES_AUTH_TOKEN>' \
-d '{ "runners":["<YOUR_HEALTH_CHECK_URL_1>", "<YOUR_HEALTH_CHECK_URL_2>"]}'
```

## Sending metrics

You can send metrics for your application by sending them to the internal metrics topic of your Lenses installation, by default this is `__topology_metrics`**.**

Send using this schema, as JSON. The appName needs to match the registered application name you provided.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "lenses_record",
  "type": "object",
  "properties": {
    "appName": {
      "type": "string"
    },
    "pid": {
      "type": "string"
    },
    "machine": {
      "type": "string"
    },
    "topic": {
      "type": "string"
    },
    "messagesSentPerSecond": {
      "type": "number"
    },
    "bytesSentPerSecond": {
      "type": "number"
    },
    "messageSentTotal": {
      "type": "integer"
    },
    "messageErrorTotal": {
      "type": "integer"
    },
    "messagesReceivedPerSecond": {
      "type": "number"
    },
    "messageReceivedTotal": {
      "type": "integer"
    },
    "bytesReceivedPerSecond": {
      "type": "number"
    }
  },
  "required": [
    "appName",
    "pid",
    "machine",
    "topic",
    "messagesSentPerSecond",
    "bytesSentPerSecond",
    "messageSentTotal",
    "messageErrorTotal",
    "messagesReceivedPerSecond",
    "messageReceivedTotal",
    "bytesReceivedPerSecond"
  ]
}

```

## Remove your Application

You can remove the app by making a `DELETE` request to `/api/v1/apps/external/{name}`. By **Removing an App from Lenses**, you just drop Lenses’ visibility for that specific App.

```bash
curl -X DELETE <LENSES_HOST_URL>/api/v1/apps/external/Example_Producer_App \
-H 'Content-Type: application/json' \
-H 'X-Kafka-Lenses-Token: <LENSES_AUTH_TOKEN>'
```

Alternatively, you can use the Lenses UI to remove the App.


---

# 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.lenses.io/latest/devx/6.0/user-guide/applications/external-applications/registring-via-rest.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.