> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofunmiadewuyi.com/custos/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a set

> Requires the global `set.add` permission. `public` decides which half of the product the set belongs to and is effectively permanent — see the note on the Sets tag.




## OpenAPI

````yaml /custos/openapi.yaml post /sets
openapi: 3.1.0
info:
  title: Custos control-plane API
  version: 0.1.0
  description: >
    Seed specification. The auth, identity, key, host-list, and grant endpoints
    below are

    complete; the remaining control-plane endpoints are still being transcribed.
servers:
  - url: https://custos.example.com
    description: Your control plane
security:
  - bearerAuth: []
tags:
  - name: Auth
    description: Login, token refresh, and logout.
  - name: Identity
    description: The authenticated user.
  - name: Keys
    description: A user's SSH public keys.
  - name: Credentials
    description: Stored secrets, sealed at rest and audited on every read.
  - name: Permission requests
    description: Time-boxed access requests for gated credentials.
  - name: Sets
    description: >-
      Secret sets — an app's .env, either deployable (private) or team-shared
      (public).
  - name: Hosts
    description: Enrolled machines.
  - name: Health
    description: Liveness and readiness probes.
  - name: Notifications
    description: In-app notifications for the signed-in user.
  - name: Rotation reviews
    description: Credential rotation checklists raised when a user is suspended or removed.
  - name: Audit
    description: Install-wide trails.
  - name: Users
    description: Accounts and their lifecycle.
  - name: Invitations
    description: Onboarding new accounts.
  - name: Groups
    description: Resource groups — a grant on a group cascades to everything in it.
  - name: Grants
    description: Permission grants.
  - name: Enrollment
    description: Admitting a machine to the fleet. Daemon-facing.
  - name: Upgrades
    description: Rolling the daemon fleet forward.
paths:
  /sets:
    post:
      tags:
        - Sets
      summary: Create a set
      description: >
        Requires the global `set.add` permission. `public` decides which half of
        the product the set belongs to and is effectively permanent — see the
        note on the Sets tag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
                  description: >
                    1-63 characters, lowercase letters, numbers and hyphens,
                    starting and ending with a letter or number. Unique across
                    the install.
                public:
                  type: boolean
                  default: false
                  description: >
                    false (default) makes a deployable set: bindable to hosts,
                    never revealable. true makes a team-shared set: revealable,
                    never bindable.
                entries:
                  type: array
                  items:
                    $ref: '#/components/schemas/SetEntryInput'
      responses:
        '201':
          description: Set created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Set'
        '400':
          description: Invalid name, or empty or duplicate entry keys
        '403':
          description: Missing `set.add`
        '409':
          description: A set with that name already exists
        '503':
          description: Vault key wrapper not configured
components:
  schemas:
    SetEntryInput:
      type: object
      required:
        - key
      properties:
        key:
          type: string
          description: The environment variable name, e.g. DATABASE_URL.
        value:
          type: string
    Set:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        public:
          type: boolean
        keys:
          type: array
          items:
            type: string
          description: Environment variable names. Values are never returned here.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        permissions:
          type: array
          items:
            type: string
        backup_jobs:
          type: array
          description: Backup jobs pinning this set, limited to those the reader can see.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              enabled:
                type: boolean
              host_id:
                type: string
                format: uuid
              host_name:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        An opaque access token from /login or /refresh. Tokens are checked
        against the database on every request, so revocation is immediate.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.