---
title: "Configurations Model"
description: "Use the operation-specific API reference schemas when reading or changing them; this guide explains the shared concepts without duplicating the complete model."
canonical: https://docs.ordering.co/api-reference/guides/configs-model/
---

# Configurations Model

Configurations store project-level settings. Use the operation-specific API reference schemas when reading or changing them; this guide explains the shared concepts without duplicating the complete model.

## Operations

The public API Reference contains these configuration operations:

| Action | Method   | Resource            |
| ------ | -------- | ------------------- |
| List   | `GET`    | `/configs`          |
| Find   | `GET`    | `/configs/{config}` |
| Create | `POST`   | `/configs`          |
| Update | `PUT`    | `/configs/{config}` |
| Delete | `DELETE` | `/configs/{config}` |

The operation guide specifies request fields, sparse projections, authentication, responses, and errors.

## Shared concepts

- `key` identifies the setting and must be unique when creating a configuration.
- `value` stores the configured value. Its representation depends on `type`.
- `options` defines allowed choices for types that require them.
- `public` and `hidden` contribute to list visibility for callers without privileged access.
- `protected` causes the response to return `PROTECT` instead of the stored value.
- Metadata such as `name`, `description`, category, dependency, rank, and support information can guide administrative presentation but is not guaranteed in every operation projection.

## Configuration types

Types `1`–`4` remain part of the model described here:

| Type | Meaning                                                                         |
| ---- | ------------------------------------------------------------------------------- |
| `1`  | A direct value.                                                                 |
| `2`  | One value selected from `options`.                                              |
| `3`  | Multiple option values in the legacy pipe-delimited representation, such as \`1 |
| `4`  | Multiple option values represented as a JSON array, such as `[1, 2, 3]`.        |

If available, the operation also accepts type `5` for an image-backed configuration. On create, `image` is required and `value` is not; successful image handling stores the resulting value. Exact accepted image formats and limits remain operation-schema and upload-policy concerns and are not inferred here.

For types `2`, `3`, and `4`, requests require `options`. Each option has a non-empty `text` and `value`:

```json
[
  {
    "text": "Example option",
    "value": "example"
  }
]
```

## Visibility and roles

Listing differs from individual reads and mutations:

- List results for callers other than administrators or servers are limited to public, non-hidden configurations, with scoped exceptions for plugins and business managers.
- Find, create, update, and delete are restricted to server `-1` or administrator `0`.
- The list operation specifies API-key or bearer authentication, while guest filtering may be available without a user session. Confirm the authentication requirements for your project before making the request.

Do not interpret `public=true` as permission to expose protected values. Each operation has its own authentication, request fields, and response rules.