{
  "openapi": "3.1.1",
  "info": {
    "title": "AfricaOne Developer API \u2014 first implementation slice",
    "version": "1.0.0",
    "description": "Local metadata mock and fail-closed city boundary only. OAuth, app registration, rate limiting, signed pagination, credentials, commerce and webhooks are pending. This contract is not a production availability claim."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:4331/developer/v1",
      "description": "Isolated loopback metadata mock; no credentials or player data."
    }
  ],
  "paths": {
    "/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "Inspect availability flags",
        "tags": ["Discovery"],
        "x-release-status": "local-mock-only",
        "x-audit-classification": "public-metadata-read",
        "x-quota-status": "pending-integration",
        "security": [],
        "responses": {
          "200": {
            "description": "Sanitized metadata.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "404": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/regions": {
      "get": {
        "operationId": "listRegions",
        "summary": "Inspect approved regions (none enabled in this slice)",
        "tags": ["Discovery"],
        "x-release-status": "local-mock-only",
        "x-audit-classification": "public-metadata-read",
        "x-quota-status": "pending-integration",
        "security": [],
        "responses": {
          "200": {
            "description": "Sanitized metadata.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Regions"
                }
              }
            }
          },
          "404": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Inspect implementation readiness",
        "tags": ["Discovery"],
        "x-release-status": "local-mock-only",
        "x-audit-classification": "public-metadata-read",
        "x-quota-status": "pending-integration",
        "security": [],
        "responses": {
          "200": {
            "description": "Sanitized metadata.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            }
          },
          "404": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/cities": {
      "get": {
        "operationId": "listCities",
        "summary": "Read reviewed city metadata",
        "tags": ["Cities"],
        "x-release-status": "local-mock-only",
        "x-audit-classification": "app-scoped-metadata-read",
        "x-quota-status": "pending-integration",
        "security": [
          {
            "developerBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sanitized metadata.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cities"
                }
              }
            }
          },
          "404": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "400": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Fail-closed RFC 9457 Problem Details. No stack traces or credentials.",
            "headers": {
              "X-Request-ID": {
                "description": "Server-generated opaque request correlation ID.",
                "schema": {
                  "type": "string"
                }
              },
              "X-AfricaOne-API-Version": {
                "schema": {
                  "const": "1.0"
                }
              },
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "Requires an injected trusted authorizer and reviewed city provider. The standalone mock has no authorizer and returns 401. No signed pagination yet: a result larger than limit returns 503 instead of dropping records. No production integration or PII.",
        "x-required-scopes": ["city.public.read"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "description": "Unknown, duplicate and cursor query parameters are rejected."
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "developerBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Verified by existing identity integration when supplied. No token issuer exists in this slice. Required scope: city.public.read; audience and environment must match; app must be active."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "title", "status", "detail", "instance", "code", "request_id"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Capabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "environment", "capabilities"],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "environment": {
            "enum": ["sandbox", "staging", "production"]
          },
          "capabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            }
          }
        }
      },
      "Status": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "environment", "status", "production_ready"],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "environment": {
            "enum": ["sandbox", "staging", "production"]
          },
          "status": {
            "const": "limited"
          },
          "production_ready": {
            "const": false
          }
        }
      },
      "Regions": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "data", "next_cursor"],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "data": {
            "type": "array",
            "maxItems": 0,
            "items": {
              "type": "object"
            }
          },
          "next_cursor": {
            "type": "null"
          }
        }
      },
      "City": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "country_code", "availability", "supported_capabilities"],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "country_code": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "availability": {
            "enum": ["closed", "closed_beta", "available"]
          },
          "supported_capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Cities": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "data", "next_cursor"],
        "properties": {
          "api_version": {
            "const": "1.0"
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/City"
            }
          },
          "next_cursor": {
            "type": "null"
          }
        }
      }
    }
  }
}