{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/briq-cloud/json-schema/briq-cloud-briq-schema.json",
  "title": "Briq",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/briq-cloud-v1-openapi.json#/components/schemas/Briq",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "teamId": {
      "type": "string"
    },
    "stackId": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "image": {
      "type": "string",
      "minLength": 3,
      "maxLength": 255,
      "pattern": "^[a-z0-9][a-z0-9._\\/-]*(?::[\\w.-]+)?(?:@sha256:[a-f0-9]{64})?$"
    },
    "size": {
      "type": "string",
      "enum": [
        "nano",
        "small",
        "medium",
        "large"
      ]
    },
    "state": {
      "type": "string",
      "enum": [
        "creating",
        "running",
        "stopping",
        "stopped",
        "sleeping",
        "starting",
        "resizing",
        "destroying",
        "destroyed",
        "error"
      ]
    },
    "internalHost": {
      "type": "string",
      "description": "Its address on the team's private network"
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "port": {
            "type": "integer"
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "postgres",
              "mysql",
              "redis",
              "mongodb",
              "amqp",
              "bolt",
              "grpc"
            ],
            "default": "http",
            "description": "http: a URL; a database protocol (postgres, mysql, redis, mongodb, amqp, bolt, grpc): a TCP endpoint, reachable from outside over TLS, url is its address without the password"
          },
          "mode": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "public: anyone can open the URL; private: only whoever has the URL, which carries a secret checked before a request reaches the briq"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "id",
          "port",
          "mode",
          "url"
        ]
      },
      "description": "Its URL, once published (one at most), and its TCP endpoint, once published"
    },
    "ports": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "default": []
    },
    "databasePorts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "port": {
            "type": "integer"
          },
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "postgres",
              "mysql",
              "redis",
              "mongodb",
              "amqp",
              "bolt",
              "grpc"
            ]
          }
        },
        "required": [
          "port",
          "protocol"
        ]
      },
      "default": [],
      "description": "Its recipe's database ports: briq_expose one with its protocol for a TCP endpoint"
    },
    "expose": {
      "type": [
        "integer",
        "null"
      ],
      "default": null
    },
    "env": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 32768
          },
          {
            "type": "object",
            "properties": {
              "secret": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
              },
              "value": {
                "type": "string",
                "maxLength": 32768
              },
              "scope": {
                "type": "string",
                "enum": [
                  "boot",
                  "team"
                ]
              },
              "hosts": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 253,
                  "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$"
                },
                "minItems": 1,
                "maxItems": 20
              },
              "locations": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "header",
                    "body"
                  ]
                },
                "minItems": 1
              }
            },
            "required": [
              "secret"
            ],
            "additionalProperties": false
          }
        ]
      },
      "default": {},
      "description": "As declared: plain values, and { secret: NAME } for secrets, whose values never appear"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "startedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When its current run started (its last run, while it is not running)"
    },
    "sleep": {
      "type": "string",
      "pattern": "^(?:never|[1-9][0-9]{0,4}[mhd])$",
      "description": "When the briq goes to sleep: after this long without use (agent calls, visits to its stack's URLs). A string: \"30m\", \"3h\", \"7d\" or \"never\", never a number. A sleeping briq keeps its disk, costs nothing for compute, and the next use wakes it. \"never\" keeps it always on (Pro plan and above)"
    },
    "sleepsAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it goes to sleep unless it is used before then: every use moves this later. Null when it is not running or never sleeps"
    },
    "lastUsedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "costCentsSoFar": {
      "type": "number",
      "description": "Euro cents billed so far, fractions of a cent included"
    },
    "error": {
      "type": [
        "string",
        "null"
      ]
    },
    "destroysAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "default": null,
      "description": "When a briq in error is destroyed automatically; null in any other state"
    },
    "stoppedReason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "idle",
        "cap",
        "credits",
        "user",
        "provider",
        "exited"
      ],
      "default": null,
      "description": "Why it is stopped or sleeping. idle and provider: asleep, the next call or visit wakes it. cap and credits: a limit, asleep again once it has cleared. user and exited: only briq_start runs it again"
    },
    "lastExit": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "code": {
          "type": "integer"
        },
        "oomKilled": {
          "type": "boolean"
        },
        "at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "default": null,
      "required": [
        "code",
        "oomKilled",
        "at"
      ],
      "description": "The last time its process ended on its own: exit code (128 + n for signal n), whether it ran out of memory, and when"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "bytes": {
            "type": "integer"
          }
        },
        "required": [
          "path",
          "bytes"
        ]
      },
      "default": [],
      "description": "Its boot files, by path and size; their content is not returned"
    },
    "forkedFrom": {
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "volume": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "mount": {
          "type": "string"
        },
        "gb": {
          "type": "integer"
        }
      },
      "default": null,
      "required": [
        "mount",
        "gb"
      ],
      "description": "Its volume: where it is mounted and its size in GB; null without one"
    }
  },
  "required": [
    "id",
    "teamId",
    "stackId",
    "name",
    "image",
    "size",
    "state",
    "internalHost",
    "endpoints",
    "createdAt",
    "startedAt",
    "sleep",
    "sleepsAt",
    "lastUsedAt",
    "costCentsSoFar",
    "error"
  ]
}