{
  "openapi": "3.0.3",
  "info": {
    "title": "Contact Gain API",
    "version": "1.0.0",
    "description": "Programmatic access to Contact Gain: submit a contact, receive a password, and download the daily VCF file.\n\n**Daily cycle (Africa/Lagos):** submissions close at 20:00 and the file unlocks at 21:00.\n\n**Authentication:** write endpoints accept an optional `X-API-Key` header when `API_KEY` is set. Admin endpoints use the signed `cg_admin` session cookie from `POST /api/admin/login`.\n\n**Idempotency:** one submission per phone per day. Repeats return `409 duplicate`.\n\n**Route discovery:** paths are read from the live Express router on every request, so this document cannot drift. 6 operations here are auto-generated; see `x-generated-operations`.",
    "contact": {
      "name": "Edges Network"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://contactgain.ne-t.org",
      "description": "This server"
    }
  ],
  "tags": [
    {
      "name": "Public",
      "description": "Open endpoints, no authentication"
    },
    {
      "name": "Submissions",
      "description": "Create a contact entry and receive a password"
    },
    {
      "name": "Downloads",
      "description": "Retrieve the compiled VCF file"
    },
    {
      "name": "Account",
      "description": "Customer account, profile, billing and files"
    },
    {
      "name": "Content",
      "description": "FAQ, pools, blog and site state"
    },
    {
      "name": "Ads",
      "description": "Display ad tracking"
    },
    {
      "name": "Admin",
      "description": "Requires an admin session cookie"
    }
  ],
  "x-generated-operations": [
    "GET /api/download/vcf",
    "GET /api/steps",
    "POST /api/account/logout",
    "GET /api/ad-flyer/samples",
    "POST /api/ad-flyer/samples",
    "GET /api/go/ad/sponsor"
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Service health and current clock",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "site": {
                      "type": "string",
                      "description": "Site name"
                    },
                    "sponsor": {
                      "type": "string",
                      "description": "Sponsor"
                    },
                    "version": {
                      "type": "string",
                      "description": "API version"
                    },
                    "serverTime": {
                      "type": "string",
                      "description": "ISO timestamp"
                    },
                    "lagosDate": {
                      "type": "string",
                      "description": "Current file date"
                    },
                    "submissionsOpen": {
                      "type": "boolean"
                    },
                    "fileUnlocked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Live site state",
        "description": "Submission window, today's contact count, Spotlight availability and current advertiser.",
        "responses": {
          "200": {
            "description": "Current state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/submit": {
      "post": {
        "tags": [
          "Submissions"
        ],
        "summary": "Submit a contact and receive a password",
        "description": "Creates one entry for the current file date. Free names are max 8 characters with no spaces. Country pools require Premium. One submission per phone per day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "phone"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name",
                    "example": "AmaraWV"
                  },
                  "phone": {
                    "type": "string",
                    "description": "Phone number in any common format",
                    "example": "08031234567"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "premium"
                    ],
                    "default": "free"
                  },
                  "pool": {
                    "type": "string",
                    "enum": [
                      "GLOBAL",
                      "NG",
                      "GH",
                      "KE",
                      "ZA",
                      "UG",
                      "TZ",
                      "CM",
                      "GB",
                      "US",
                      "IN"
                    ],
                    "default": "GLOBAL"
                  },
                  "consentRelay": {
                    "type": "boolean",
                    "description": "Explicit consent to forward this number to the partner network. Required when relay is enabled.",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "name": {
                      "type": "string",
                      "description": "Sanitised display name"
                    },
                    "phone": {
                      "type": "string",
                      "description": "E.164 phone number"
                    },
                    "plan": {
                      "type": "string",
                      "enum": [
                        "free",
                        "premium"
                      ]
                    },
                    "pool": {
                      "type": "string",
                      "description": "Pool code",
                      "example": "GLOBAL"
                    },
                    "password": {
                      "type": "string",
                      "description": "Download password. Shown once."
                    },
                    "ymd": {
                      "type": "string",
                      "description": "File date",
                      "example": "2026-11-20"
                    },
                    "country": {
                      "type": "string",
                      "description": "ISO country from the dialling code"
                    },
                    "relay": {
                      "type": "object",
                      "properties": {
                        "queued": {
                          "type": "boolean"
                        },
                        "reason": {
                          "type": "string",
                          "description": "Reason when not queued"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Paid plan required for that pool",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Blocked number, or submissions are closed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate submission for today",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/download/vcf": {
      "post": {
        "tags": [
          "Downloads"
        ],
        "summary": "Download a day's VCF file with a password",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string",
                    "description": "Password issued on submission",
                    "example": "VDWF9MYSCE"
                  },
                  "buildDate": {
                    "type": "string",
                    "description": "File date, defaults to today",
                    "example": "2026-11-20"
                  },
                  "pool": {
                    "type": "string",
                    "enum": [
                      "GLOBAL",
                      "NG",
                      "GH",
                      "KE",
                      "ZA",
                      "UG",
                      "TZ",
                      "CM",
                      "GB",
                      "US",
                      "IN"
                    ],
                    "default": "GLOBAL"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string",
                    "description": "Password issued on submission"
                  },
                  "buildDate": {
                    "type": "string",
                    "description": "File date, defaults to today"
                  },
                  "pool": {
                    "type": "string",
                    "description": "Pool code",
                    "default": "GLOBAL"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The VCF file",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "Attachment filename"
              },
              "X-Contact-Count": {
                "schema": {
                  "type": "integer"
                },
                "description": "Contacts in the file"
              },
              "X-File-Checksum": {
                "schema": {
                  "type": "string"
                },
                "description": "SHA-256 prefix of the body"
              }
            },
            "content": {
              "text/vcard": {
                "schema": {
                  "type": "string",
                  "example": "BEGIN:VCARD\r\nVERSION:3.0\r\n..."
                }
              }
            }
          },
          "400": {
            "description": "Missing password",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Incorrect password",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "File not unlocked yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No file for that date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Downloads"
        ],
        "summary": "GET /api/download/vcf",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        },
        "x-auto-generated": true
      }
    },
    "/api/downloads": {
      "get": {
        "tags": [
          "Downloads"
        ],
        "summary": "List downloadable days",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Days per page: 7"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated day list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DownloadPage"
                }
              }
            }
          }
        }
      }
    },
    "/api/pools": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List country pools",
        "responses": {
          "200": {
            "description": "Pools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Pool"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/faq": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "FAQ entries",
        "responses": {
          "200": {
            "description": "Questions and answers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FaqItem"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/blog": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Blog posts",
        "responses": {
          "200": {
            "description": "Post list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlogPost"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/pricing": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Published prices",
        "description": "Every paid tier as listed to customers, already marked up. `markup` is the multiplier applied to base cost.",
        "responses": {
          "200": {
            "description": "Price list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Pricing"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Current account",
        "description": "The account attached to the session cookie. Returns 401 when signed out.",
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/register": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Create an account",
        "description": "Creates an unverified account and sends a confirmation link to the address supplied.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 8
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Email already registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/login": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Sign in",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong email or password",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/verify": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Confirm an email address",
        "description": "Consumes a single-use confirmation token. Replaying a token returns 410.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Token already used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/submissions": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Your submissions",
        "description": "Contacts submitted while signed in, newest first, with the issued daily password where one exists.",
        "responses": {
          "200": {
            "description": "Submissions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Submission"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/profile": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Your profile",
        "description": "Display name, WhatsApp number and country used for auto-submit, plus plan and verification state.",
        "responses": {
          "200": {
            "description": "Profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Account"
        ],
        "summary": "Update your profile",
        "description": "Partial update. Omitted fields keep their stored value.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "displayName": {
                    "type": "string",
                    "description": "WhatsApp name used in the daily file"
                  },
                  "phone": {
                    "type": "string",
                    "description": "WhatsApp number in international format"
                  },
                  "country": {
                    "type": "string",
                    "description": "ISO 3166-1 alpha-2 country code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid display name, phone number or country",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/billing": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Billing summary",
        "description": "Subscription state, payment history and every Spotlight and ad booking on the account.",
        "responses": {
          "200": {
            "description": "Billing summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "active": {
                          "type": "boolean"
                        },
                        "total": {
                          "type": "integer",
                          "description": "Lifetime total in cents"
                        },
                        "subscription": {
                          "type": "object",
                          "nullable": true
                        },
                        "payments": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Payment"
                          }
                        },
                        "spotlight": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Booking"
                          }
                        },
                        "ads": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Booking"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/files": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Files you can download",
        "description": "Unlocked daily files. Subscribers get every file without a password; everyone else gets the days they submitted.",
        "responses": {
          "200": {
            "description": "Files",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "passwordFree": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ymd": {
                            "type": "string",
                            "description": "File date"
                          },
                          "contact_count": {
                            "type": "integer"
                          },
                          "pool": {
                            "type": "string",
                            "description": "Pool code"
                          },
                          "code": {
                            "type": "string",
                            "description": "Daily password, when the account holds one"
                          },
                          "unlocked": {
                            "type": "boolean"
                          },
                          "passwordFree": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/blog/{slug}": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "One blog post",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Post",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogPost"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/blocked": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Blocked numbers",
        "description": "Numbers excluded from every future file. Phones are masked.",
        "responses": {
          "200": {
            "description": "Blocked list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlockedItem"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/spotlight": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Spotlight slots",
        "responses": {
          "200": {
            "description": "Slots, empty or filled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpotlightSlot"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ads": {
      "get": {
        "tags": [
          "Ads"
        ],
        "summary": "Running display ads",
        "responses": {
          "200": {
            "description": "Ads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Ad"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ad-impression": {
      "post": {
        "tags": [
          "Ads"
        ],
        "summary": "Record an ad impression",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "adId"
                ],
                "properties": {
                  "adId": {
                    "type": "string",
                    "description": "Ad identifier"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown ad",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/go/ad/{id}": {
      "get": {
        "tags": [
          "Ads"
        ],
        "summary": "Track a click and redirect to the advertiser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the advertiser destination"
          },
          "404": {
            "description": "Unknown ad"
          }
        }
      }
    },
    "/api/admin/login": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Admin sign in",
        "description": "Sets an HttpOnly session cookie used by every other admin endpoint.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "username",
                  "password"
                ],
                "properties": {
                  "username": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bad credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/logout": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Admin sign out",
        "responses": {
          "200": {
            "description": "Signed out"
          }
        }
      }
    },
    "/api/admin/overview": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Dashboard overview",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Overview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminOverview"
                }
              }
            }
          },
          "401": {
            "description": "Not signed in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/contacts": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "List admin contacts",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin contacts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AdminContact"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Add an admin contact",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "description": "Phone number",
                    "example": "+2348030000001"
                  },
                  "name": {
                    "type": "string",
                    "description": "Base name that seeds the daily random name",
                    "example": "Contact Gain"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "premium"
                    ],
                    "default": "premium"
                  },
                  "pool": {
                    "type": "string",
                    "enum": [
                      "GLOBAL",
                      "NG",
                      "GH",
                      "KE",
                      "ZA",
                      "UG",
                      "TZ",
                      "CM",
                      "GB",
                      "US",
                      "IN"
                    ],
                    "default": "GLOBAL"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminContact"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/contacts/{id}": {
      "delete": {
        "tags": [
          "Admin"
        ],
        "summary": "Remove an admin contact",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/contacts/{id}/toggle": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Enable or disable an admin contact",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminContact"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/run/{job}": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Run a daily job immediately",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "description": "Runs the admin submit, admin download, compile or relay drain job now.",
        "parameters": [
          {
            "name": "job",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "submit",
                "download",
                "compile",
                "relay"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/submissions": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Recent submissions",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ymd",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by date"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Submissions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SubmissionRow"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/download/{ymd}": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Download any day's file without a password",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ymd",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "2026-11-20"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The VCF file",
            "content": {
              "text/vcard": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Locked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/relay": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Relay queue state",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Queue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/relay/requeue": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Requeue failed relay items",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Requeued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/ad-flyer": {
      "get": {
        "tags": [
          "Advertising"
        ],
        "summary": "What the homepage banner is running",
        "responses": {
          "200": {
            "description": "Current creative",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "live": {
                          "type": "boolean"
                        },
                        "imageUrl": {
                          "type": "string",
                          "nullable": true
                        },
                        "advertiser": {
                          "type": "string",
                          "nullable": true
                        },
                        "targetUrl": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Advertising"
        ],
        "summary": "Upload the flyer that runs in the homepage banner",
        "description": "Send the image as the raw request body, or as multipart form data with a `flyer` field.\nPNG, JPEG, WebP or GIF, up to 6 MB. The type is read from the file header, so the stored\nname never comes from the client. The banner switches to the new flyer immediately.\n\nAuthenticate with `?key=<UPLOAD_KEY>` (or the `X-Upload-Key` header) or an admin session.\n\n```\ncurl -X POST \"$SITE/api/ad-flyer?key=$UPLOAD_KEY\" -H \"Content-Type: image/png\" --data-binary @flyer.png\ncurl -F \"flyer=@flyer.png\" \"$SITE/api/ad-flyer?key=$UPLOAD_KEY\"\n```",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Matches UPLOAD_KEY"
          },
          {
            "name": "advertiser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Shown as the ad sponsor"
          },
          {
            "name": "target",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Where a click goes"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "flyer": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "adId": {
                          "type": "string"
                        },
                        "imageUrl": {
                          "type": "string"
                        },
                        "bytes": {
                          "type": "integer"
                        },
                        "contentType": {
                          "type": "string"
                        },
                        "liveOn": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No upload key and no admin session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Larger than 6 MB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Not a PNG, JPEG, WebP or GIF",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/ads": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Every ad, including unapproved ones",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Ads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Ad"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Create an ad",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "description": "Creates an approved ad. Send the artwork afterwards to `POST /api/admin/ads/{id}/image`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "advertiser",
                  "targetUrl"
                ],
                "properties": {
                  "advertiser": {
                    "type": "string",
                    "description": "Name shown under the creative"
                  },
                  "targetUrl": {
                    "type": "string",
                    "description": "Destination, must start with http:// or https://"
                  },
                  "imageUrl": {
                    "type": "string",
                    "description": "Optional artwork URL if it is already hosted"
                  },
                  "status": {
                    "type": "string",
                    "description": "approved by default"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Ad"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing advertiser or a bad target URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/ads/{id}/image": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Upload the flyer for an ad",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "description": "Send the image as the raw request body, not multipart. The type is read from the file header,\nso the extension is never taken from the client. Maximum 6 MB.\n\n```\ncurl -X POST \"$SITE/api/admin/ads/$ID/image\" \\\n  -H \"Content-Type: image/png\" \\\n  --data-binary @flyer.png\n```\n\nReturns the public `imageUrl`, which the homepage banner picks up immediately.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "advertiser": {
                          "type": "string"
                        },
                        "imageUrl": {
                          "type": "string"
                        },
                        "bytes": {
                          "type": "integer"
                        },
                        "contentType": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown ad",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Larger than 6 MB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Not a PNG, JPEG, WebP or GIF",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/ads/{id}": {
      "delete": {
        "tags": [
          "Admin"
        ],
        "summary": "Delete an ad and its flyer",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown ad",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/numbers": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Every number ever submitted",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "description": "Lifetime registry. `times` counts how often a number entered a file; the daily automation is the usual reason it is above 1.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Match phone or name"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registry rows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "phone_e164": {
                            "type": "string"
                          },
                          "first_ymd": {
                            "type": "string"
                          },
                          "last_ymd": {
                            "type": "string"
                          },
                          "times": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "source": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "numbers": {
                          "type": "integer"
                        },
                        "entries": {
                          "type": "integer"
                        },
                        "repeated": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Admin authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/steps": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "GET /api/steps",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        },
        "x-auto-generated": true
      }
    },
    "/api/account/logout": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "POST /api/account/logout",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-auto-generated": true,
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/ad-flyer/samples": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "GET /api/ad-flyer/samples",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        },
        "x-auto-generated": true
      },
      "post": {
        "tags": [
          "Public"
        ],
        "summary": "POST /api/ad-flyer/samples",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-auto-generated": true,
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/go/ad/sponsor": {
      "get": {
        "tags": [
          "Ads"
        ],
        "summary": "GET /api/go/ad/sponsor",
        "description": "Generated from the mounted Express router. Add a hand-written entry to src/openapi.js to document the payload.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          }
        },
        "x-auto-generated": true
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "cg_admin"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "description": "Human readable error"
          },
          "code": {
            "type": "string",
            "description": "Machine readable code",
            "example": "invalid_phone"
          }
        }
      },
      "Pool": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "FaqItem": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "plan": {
            "type": "string"
          },
          "verified": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "verifiedAt": {
            "type": "string",
            "nullable": true
          },
          "lastLoginAt": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Pricing": {
        "type": "object",
        "description": "Display-ready price strings. `markup` is the multiplier applied to base cost.",
        "properties": {
          "markup": {
            "type": "number"
          },
          "free": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "price": {
                "type": "string"
              },
              "nameLength": {
                "type": "integer"
              },
              "spaces": {
                "type": "boolean"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "premium": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "price": {
                "type": "string"
              },
              "nameLength": {
                "type": "integer"
              },
              "spaces": {
                "type": "boolean"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "subscribe": {
            "type": "object",
            "properties": {
              "monthly": {
                "type": "string"
              },
              "yearly": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "spotlight": {
            "type": "object",
            "properties": {
              "weekly": {
                "type": "string"
              },
              "monthly": {
                "type": "string"
              },
              "yearly": {
                "type": "string"
              },
              "slots": {
                "type": "integer"
              }
            }
          },
          "displayAd": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "brandSuffix": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      },
      "BlogPost": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "body": {
            "type": "string"
          }
        }
      },
      "BlockedItem": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "SpotlightSlot": {
        "type": "object",
        "properties": {
          "slot": {
            "type": "integer"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "bio": {
            "type": "string",
            "nullable": true
          },
          "link": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Ad": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "advertiser": {
            "type": "string"
          },
          "targetUrl": {
            "type": "string"
          },
          "imageUrl": {
            "type": "string",
            "nullable": true
          },
          "impressions": {
            "type": "integer"
          },
          "clicks": {
            "type": "integer"
          }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "example": "subscription"
          },
          "label": {
            "type": "string"
          },
          "amount_cents": {
            "type": "integer",
            "example": 646
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "string",
            "example": "paid"
          },
          "period_start": {
            "type": "string",
            "nullable": true
          },
          "period_end": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Booking": {
        "type": "object",
        "description": "A Spotlight or advertising booking. Fields differ slightly by kind.",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "nullable": true
          },
          "slot": {
            "type": "integer",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "days": {
            "type": "integer",
            "nullable": true
          },
          "weeks": {
            "type": "integer",
            "nullable": true
          },
          "amount_cents": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "example": "live"
          },
          "starts_at": {
            "type": "string",
            "nullable": true
          },
          "ends_at": {
            "type": "string",
            "nullable": true
          },
          "start_ymd": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SiteStatus": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "ymd": {
            "type": "string",
            "example": "2026-11-20"
          },
          "dateLabel": {
            "type": "string"
          },
          "submissionsOpen": {
            "type": "boolean"
          },
          "todayCount": {
            "type": "integer"
          },
          "spotlightSlotsLeft": {
            "type": "integer"
          },
          "unlockLabel": {
            "type": "string"
          },
          "closeLabel": {
            "type": "string"
          },
          "closesAt": {
            "type": "integer",
            "description": "Epoch millis of the next submission close."
          },
          "opensAt": {
            "type": "integer",
            "description": "Epoch millis of the next reopen (midnight, Africa/Lagos)."
          },
          "windowStart": {
            "type": "integer",
            "description": "Start of the phase the countdown runs across."
          },
          "windowEnd": {
            "type": "integer",
            "description": "End of that phase, for the progress rail."
          },
          "serverNow": {
            "type": "integer",
            "description": "Server clock, so clients can correct for skew."
          },
          "advertiser": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "DownloadPage": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ymd": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "unlocked": {
                  "type": "boolean"
                },
                "contactCount": {
                  "type": "integer",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "AdminContact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "phone_e164": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "pool": {
            "type": "string"
          },
          "enabled": {
            "type": "integer"
          },
          "position": {
            "type": "integer"
          },
          "todayName": {
            "type": "string",
            "description": "The randomised name used today"
          }
        }
      },
      "SubmissionRow": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "phone_e164": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "pool": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "ymd": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "relayed": {
            "type": "integer"
          }
        }
      },
      "AdminOverview": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/SiteStatus"
          },
          "nextRuns": {
            "type": "object"
          },
          "jobs": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "relay": {
            "type": "object"
          },
          "counts": {
            "type": "object"
          }
        }
      }
    }
  }
}