---
title: "Create list"
method: POST
path: "/api/lists"
tags: ["Static Lists"]
---

# Create list

`POST /api/lists`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/lists`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `lst`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/lists/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the [upload](/developer/rest-api/ua/operations/static-lists/#updatestaticlist) endpoint. You can upload up to 100 lists per project.

## Request body

- ListMetadataObject: Contains all user-specified data when defining a static list in Airship.
  - `description` string: An optional description for the list.
  - `extra` unknown
  - `name` string, required: The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable. Note: Since the `name` portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The `encodeURIComponent` function in JavaScript can be used.

## Response `201`

The list was created successfully.

- OkResponseObject: Returned with 2xx Responses. At a minimum, successful calls return `true` for the `ok` key. If your call includes a verbose response (as with `GET` requests, etc.), the `ok` key will appear in the top-most object, outside the verbose response.
  - `ok` boolean, required: Success.
  - `operation_id` string, uuid: A unique string identifying the operations that modify resources. Use the operation ID to locate and track grouped operations (i.e., a batch push operation may generate multiple `push_id` strings, but a single `operation_id`) or operations that change an existing resource.

## Other responses

- `400`: There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.
- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.
- `403`: Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
- `409`: The request conflicts with another request.

## Changes

- **2025-08-28** `3304568aaadc`: 2 breaking
  - the `description` request property's minLength was increased from `0` to `1`
  - added the pattern `^[a-zA-Z0-9_-]*$` to the request property `name`
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/lists/post.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)