[toc]

This guide describes how to use the API endpoints of SciLifeLab Serve to fetch information about the platform, lists of the public apps, information about individual apps. To follow this guide you are expected to be comfortable with HTTP requests, query parameters, and JSON responses.

You can make an API request by simply opening a particular URL in your web browser or by using a terminal tool like [curl](https://curl.se/). In response, you will always receive a JSON formatted output.

## Basic API endpoints

### Health check

**GET** `https://serve.scilifelab.se/openapi/v1/are-you-there`

Simplest API endpoint useful for testing and verifications. Returns "true" if system is up and running.

### System version

**GET** `https://serve.scilifelab.se/openapi/v1/system-version`

Returns the current version of SciLifeLab Serve. Response includes `system-version`, `build-date`,  `image-tag`

### API information

**GET** `https://serve.scilifelab.se/openapi/v1/api-info`

The Open API basic API information endpoint, in accordance to the standard. Includes info about the latest API version.


## Fetching public apps

### List public apps

**GET** `https://serve.scilifelab.se/openapi/v1/public-apps`

**GET** `https://serve.scilifelab.se/openapi/v1/public-apps?limit=5`

This endpoint gets a list of apps that are publicly available and listed in the public app catalogue of SciLifeLab Serve. It returns a list of app information, ordered by date created from the most recent to the oldest. If needed, you can limit the number of returned apps by adding a `limit` filter.

#### Returned fields (per app)

Each list item includes, at minimum:

- `id`
- `name`
- `url`
- `description`
- `created_on`
- `updated_on`
- `access`
- `k8s_user_app_status`
- `latest_user_action`
- `app_status`
- `app_type`
- `table_field.url` (will be depreciated in the next version of the API)

#### Example output

The response contains an `data` object with:

```json
{
  "data": [
    {
      "id": 123,
      "name": "Some Public App",
      "url": "https://…",
      "description": "…",
      "created_on": "2025-12-01T10:00:00Z",
      "updated_on": "2025-12-10T12:00:00Z",
      "access": "public",
      "latest_user_action": "…",
      "k8s_user_app_status": "Running",
      "app_status": "Running",
      "app_type": "Streamlit",
      "table_field": {"url": "https://…"}
    }
  ]
}
```

#### Errors

- HTTP 403 if `limit` is invalid.
- HTTP 500 if the system is unable to collect the list of public apps.

### Retrieve info about a single public app

**GET** `https://serve.scilifelab.se/openapi/v1/public-apps/<APP_ID>`

This endpoint retrieves information about a single public app instance. The requested URL needs to include the ID of the application in the SciLifeLab Serve database.

#### Returned fields

The response contains an `app` object with:

- `id`
- `name`
- `url`
- `description`
- `created_on`
- `updated_on`
- `access`
- `k8s_user_app_status`
- `app_status`
- `app_type`

#### Errors

The endpoint returns HTTP 404 in the following cases:

- No app exists with the given `APP_ID`.
- The app exists but is of an incorrect type.
- The app is not public.
- The app has been deleted.

If `APP_ID` is missing or less than 1, the API returns HTTP 403. 

Unexpected failures retrieving the app return HTTP 500.

## Content statistics

**GET** `https://serve.scilifelab.se/openapi/v1/content-stats`

This endpoint allows to get aggregated statistics about usage of SciLifeLab Serve.

#### Returned fields

- `stats_date_utz`  
- `stats_success`  
- `stats_message`  
- `stats_notes`  
- `n_projects`  
- `n_users`  
- `n_apps`
- `n_apps_public`  
- `apps_by_type`  
- `new_users_by_year`  
- `users_by_university`  
- `apps_by_image_registry`  

#### Errors

The returned value of `stats_success` indicates whether all statistic sub-queries succeeded. If statistics gathering fails, each error message is added to and displayed in the value of `stats_message`. 

Numeric counts default to '-1' if the related computation fails.