Create a country

Creates a country. See the validation note in info: the ISO length and required rules in the model do not execute.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST /v1/countries. See the note in info: these constraints are not enforced server-side.

iso_alpha_2*string

Unique. The column is char(2): a longer value fails at the database as a 500.

iso_alpha_3*string

Unique. char(3).

iso_numeric*string

Unique. char(3).

icon?string

emoji?string

phone_prefix?string

order?integer

Display order. The column carries gorm:"default:999", which GORM parses into a DefaultValueInterface — so the column IS in the INSERT, and when the struct field is zero GORM substitutes the literal 999 into the statement and sets it on the struct in the same step. No RETURNING is involved for this column. On create BOTH an absent order and an explicit "order": 0 therefore store and return 999; there is no way to create a country with order 0. PUT behaves differently: UpdateCountry writes every column, so 0 goes through there.

name*string

description?string|null

active?boolean

The Go field is a non-pointer bool, so an omitted active is decoded as false and stored as false. The gorm:"default:true" tag sits on the INPUT struct, not on the column: models.Country takes active from BaseModelV2, where the column default is false.

metadata?|null

tags?array<string>

iban_length?integer

Response Body

`application/json`

curl -X POST "https://example.com/v1/countries" \  -H "Content-Type: application/json" \  -d '{    "iso_alpha_2": "CH",    "iso_alpha_3": "CHE",    "iso_numeric": "756",    "name": "string"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "iso_alpha_2": "CH",
  "iso_alpha_3": "CHE",
  "iso_numeric": "756",
  "icon": "string",
  "icon_url": "string",
  "emoji": "🇨🇭",
  "phone_prefix": "+41",
  "order": 999,
  "tags": [
    "string"
  ],
  "iban_length": 0,
  "name": "Switzerland",
  "description": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "modified_at": "2019-08-24T14:15:22Z",
  "modified_by": "e8d4374d-93a1-4e98-a6c6-fdcf00c5059f",
  "active": true,
  "metadata": {}
}

{
  "status": 404,
  "message": "Country not found",
  "code": "countries_m.country_not_found",
  "class": "business",
  "retryable": true,
  "details": [
    {
      "field": "string",
      "rule": "string",
      "param": "string",
      "message": "string"
    }
  ]
}

{
  "status": 404,
  "message": "Country not found",
  "code": "countries_m.country_not_found",
  "class": "business",
  "retryable": true,
  "details": [
    {
      "field": "string",
      "rule": "string",
      "param": "string",
      "message": "string"
    }
  ]
}

{
  "status": 404,
  "message": "Country not found",
  "code": "countries_m.country_not_found",
  "class": "business",
  "retryable": true,
  "details": [
    {
      "field": "string",
      "rule": "string",
      "param": "string",
      "message": "string"
    }
  ]
}

{
  "status": 429,
  "message": "rate limit exceeded",
  "code": "rate_limits_m.exceeded",
  "class": "temporary",
  "retryable": true
}

{
  "status": 404,
  "message": "Country not found",
  "code": "countries_m.country_not_found",
  "class": "business",
  "retryable": true,
  "details": [
    {
      "field": "string",
      "rule": "string",
      "param": "string",
      "message": "string"
    }
  ]
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05.123456789+02:00"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

429application/json

500application/json

503application/json

Graceful shutdown — LifecycleMiddleware, root router, not the envelope

ensureCacheAvailable could not reach the auth cache — the envelope

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`