> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mezmo.ferndocs.com/api-reference/log-analysis/screens/create-screen/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mezmo.ferndocs.com/_mcp/server.

# Creates a new screen

POST https://api.mezmo.com/v1/config/screen
Content-Type: application/json

Creates a new screen

Reference: https://mezmo.ferndocs.com/api-reference/log-analysis/screens/create-screen

## Authentication

- `Authorization` header (required) — This key is used for all apis with the exception of ingest. You can obtain it following [these instructions](https://docs.mezmo.com/docs/ingestion-key) and placing the key in the header of your call in the format of `Authorization: Token {accesstoken}` For example: ``` curl -H 'Authorization: Token <ACCESS TOKEN>' ```
- `servicekey` header (required) — (Deprecated) This key is used for v1 and v2 apis with the exception of ingest. Service keys can be used by placing your service key in the `Authorization` header of your api call. *NOTE* Usage of the service key auth mechanism has been deprecated in favor of IAM Access Tokens. Service keys can no longer be created, but can still be used for v1 and v2 apis while the transition takes place

## Request

### Body (application/json)

This endpoint expects a screenResource.

- `id` (string, required) — The identifier of this screen.
- `title` (string, required) — The title of this screen.
- `ratio` (enum, required) — The width to height aspect ratio of this screen.
  - Allowed values: `3:2`, `4:3`, `5:4`, `16:9`, `16:10`, `21:9`
- `rotate90Degrees` (boolean, required) — Whether the screen is rotated 90 degrees. Setting to true effectively swaps the width to height ratio.
- `background` (enum, required) — The background color to use when viewing the screen.
  - Allowed values: `dark`, `light`
- `account` (string, optional) — The account this screen belongs to.
- `categories` (list of string, optional) — A list of string categories the screen belongs to.
- `widgets` (list of ScreenResourceWidgetsItems, optional)

## Response

### 200

A new screen was created successfully! Entire memberResource is returned.

- `id` (string, required) — The identifier of this screen.
- `title` (string, required) — The title of this screen.
- `ratio` (enum, required) — The width to height aspect ratio of this screen.
  - Allowed values: `3:2`, `4:3`, `5:4`, `16:9`, `16:10`, `21:9`
- `rotate90Degrees` (boolean, required) — Whether the screen is rotated 90 degrees. Setting to true effectively swaps the width to height ratio.
- `background` (enum, required) — The background color to use when viewing the screen.
  - Allowed values: `dark`, `light`
- `account` (string, optional) — The account this screen belongs to.
- `categories` (list of string, optional) — A list of string categories the screen belongs to.
- `widgets` (list of ScreenResourceWidgetsItems, optional)

## Errors

### 400 Bad Request Error

The supplied request is invalid or malformed.

- `error` (string, optional) — A human-readable description of the error
- `code` (string, optional) — A unique code for the type of error
- `status` (string, optional) — The status of the request

## Types

### ScreenResourceWidgetsItems

- `id` (string, required) — The id of this widget.
- `type` (enum, required) — The type for this widget.
  - Allowed values: `count`, `gauge`, `table`, `time-shifted-graph`
- `operation` (enum, required) — The type of operation to perform on the field indicated in the “field” option. If the "field" option is set to all lines, only "count" can be used and other values may not display any results.
  - Allowed values: `count`, `min`, `max`, `avg`, `cum`, `diff`, `percentile-75`, `percentile-85`, `percentile-95`, `percentile-99`
- `duration` (string, required) — How far into the past to graph this widget. Time shifted graph widgets must use time shifted durations e.g. "iso-weekly-compare". All other widgets must use regular durations e.g. "hourly".
- `field` (string, required) — Which field is being operated on and displayed in this widget. Use the special field “__ALL__LINES__” to perform the operation on all lines.
- `position` (ScreenResourceWidgetsItemsPosition, required) — The positional coordinates of a widget. Screens coordinates start at at the top left at [1, 1] and increase down and to the right of a screen.
- `match` (string, optional) — A special matching operation done on each value of the field. If the field is a string type then this value is used for equivalence matching. For number types, the supported operators are \["\*", ">N", "\<N", "=N", ">=N", "\<=N"]. If the field is set the special type "**ALL\_LINES**", this option is disabled.
- `filter` (string, optional) — An extra query filter to run to match lines. Must be specified as a Mezmo line query e.g. “statusCode:>=400”.
- `label` (string, optional) — A label that is displayed on the widget.
- `sort` (string, optional) — The order in which the rows of a table are sorted. This option is specific to the "table" widget.
- `rows` (integer, optional) — How many rows to include for the table. This option is specific to the "table" widget.
- `leftLabel` (string, optional) — Label to display on the left side of a table. This option is specific to the "table" widget.
- `rightLabel` (string, optional) — Label to display on the right side of a table. This option is specific to the "table" widget.
- `showBarChart` (boolean, optional) — Whether the rows of a table should also be displayed as a bar chart. This option is specific to the "table" widget.
- `groupBy` (string, optional) — An additional field with which to group results. This option is specific to the "table" widget.
- `min` (double, optional) — The minimum bounds of the gauge. This option is specific to the "gauge" widget.
- `max` (double, optional) — The maximum bounds of the gauge. This option is specific to the "gauge" widget.
- `units` (string, optional) — A label for the units of this widget. This option is specific to the "count" and "gauge" widgets.
- `format` (string, optional) — How to format the results of this widget. This option is specific to the "count", "gauge", and "table" widgets.

### ScreenResourceWidgetsItemsPosition

The positional coordinates of a widget. Screens coordinates start at at the top left at [1, 1] and increase down and to the right of a screen.

- `start` (list of any, required) — The top left corner of the widget as an [x, y] coordinate.
- `end` (list of any, required) — The bottom right corner of the widget as an [x, y] coordinate.

## Examples

**Request**

```json
{
  "title": "Payment Service Dashboard",
  "ratio": "16:9",
  "rotate90Degrees": false,
  "background": "light"
}
```

**Response**

```json
{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "title": "Payment Service Dashboard",
  "ratio": "16:9",
  "rotate90Degrees": false,
  "background": "light",
  "account": "acme-corp",
  "categories": [
    "payments",
    "production"
  ],
  "widgets": [
    {
      "id": "widget-001",
      "type": "count",
      "operation": "count",
      "duration": "1h",
      "field": "__ALL__LINES__",
      "position": {
        "start": [
          1,
          1
        ],
        "end": [
          6,
          4
        ]
      },
      "match": "ERROR",
      "filter": "service:payment-service AND logLevel:ERROR",
      "label": "Error Count Last Hour",
      "sort": "desc",
      "rows": 10,
      "leftLabel": "Timestamp",
      "rightLabel": "Error Message",
      "showBarChart": true,
      "groupBy": "errorType",
      "min": 0,
      "max": 100,
      "units": "errors",
      "format": "number-integer"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.mezmo.com/v1/config/screen"

payload = {
    "title": "Payment Service Dashboard",
    "ratio": "16:9",
    "rotate90Degrees": False,
    "background": "light"
}
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.mezmo.com/v1/config/screen';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"title":"Payment Service Dashboard","ratio":"16:9","rotate90Degrees":false,"background":"light"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mezmo.com/v1/config/screen"

	payload := strings.NewReader("{\n  \"title\": \"Payment Service Dashboard\",\n  \"ratio\": \"16:9\",\n  \"rotate90Degrees\": false,\n  \"background\": \"light\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.mezmo.com/v1/config/screen")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Payment Service Dashboard\",\n  \"ratio\": \"16:9\",\n  \"rotate90Degrees\": false,\n  \"background\": \"light\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.mezmo.com/v1/config/screen")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Payment Service Dashboard\",\n  \"ratio\": \"16:9\",\n  \"rotate90Degrees\": false,\n  \"background\": \"light\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mezmo.com/v1/config/screen', [
  'body' => '{
  "title": "Payment Service Dashboard",
  "ratio": "16:9",
  "rotate90Degrees": false,
  "background": "light"
}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.mezmo.com/v1/config/screen");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"title\": \"Payment Service Dashboard\",\n  \"ratio\": \"16:9\",\n  \"rotate90Degrees\": false,\n  \"background\": \"light\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "title": "Payment Service Dashboard",
  "ratio": "16:9",
  "rotate90Degrees": false,
  "background": "light"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mezmo.com/v1/config/screen")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```