{ "openapi": "3.1.0", "info": { "title": "InvestMoz territorial registry — implemented subset", "version": "0.1.0", "description": "Local session adapter. OAuth/OIDC, geometric queries, assignments, imports, hierarchy endpoint and administrative UI remain unimplemented. Response schemas require expansion before external certification." }, "servers": [ { "url": "/api/v1/geo" } ], "paths": { "/countries": { "get": { "summary": "Read currently published territories: countries", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/provinces": { "get": { "summary": "Read currently published territories: provinces", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/districts": { "get": { "summary": "Read currently published territories: districts", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/admin-posts": { "get": { "summary": "Read currently published territories: admin-posts", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/localities": { "get": { "summary": "Read currently published territories: localities", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/search": { "get": { "summary": "Read currently published territories: search", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "country_id", "in": "query", "schema": { "type": "string" } }, { "name": "province_id", "in": "query", "schema": { "type": "string" } }, { "name": "district_id", "in": "query", "schema": { "type": "string" } }, { "name": "admin_post_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/territories/{type}/{id}": { "get": { "summary": "Read published territory and translated names", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "required": true, "schema": { "enum": [ "country", "province", "district", "admin_post", "locality" ] } } ], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/territories": { "post": { "summary": "Create private territorial draft; designated editor with MFA", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "location_type": { "enum": [ "country", "province", "district", "admin_post", "locality" ] }, "parent_id": { "type": ["string", "null"], "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "valid_from": { "type": "string", "format": "date" }, "valid_to": { "type": ["string", "null"], "format": "date" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "name", "code", "location_type", "source_id", "valid_from", "reason" ] } } } }, "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/territories/{id}": { "patch": { "summary": "Replace draft attributes and invalidate editorial approvals", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "location_type": { "enum": [ "country", "province", "district", "admin_post", "locality" ] }, "parent_id": { "type": ["string", "null"], "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "valid_from": { "type": "string", "format": "date" }, "valid_to": { "type": ["string", "null"], "format": "date" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "version_no": { "type": "integer", "minimum": 1 } }, "required": [ "name", "code", "location_type", "source_id", "valid_from", "reason", "version_no" ] } } } }, "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/territories/{id}/transitions": { "post": { "summary": "Submit, review, publish, reject or archive; independent actors required", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "pending_review", "approved", "published", "rejected", "archived" ] }, "version_no": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 10 } }, "required": ["action", "version_no", "reason"] } } } }, "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/sources": { "post": { "summary": "Create source in pending state", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "responsible_entity": { "type": "string" }, "reference": { "type": "string" }, "license": { "type": "string" }, "checksum": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_version": { "type": "string" }, "collected_at": { "type": "string", "format": "date" }, "original_crs": { "type": "string" } }, "required": [ "name", "reference", "checksum", "source_version", "collected_at" ] } } } }, "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "201": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } }, "get": { "summary": "Management-only source metadata and decision evidence, MFA required", "security": [ { "laravelSession": [] } ], "parameters": [], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/sources/{id}/transitions": { "post": { "summary": "Independent source approval or revocation with evidence reference", "security": [ { "laravelSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": ["approved", "revoked"] }, "approval_reference": { "type": "string", "minLength": 10 } }, "required": ["action", "approval_reference"] } } } }, "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } }, "/drafts": { "get": { "summary": "Management-only territorial editorial records, MFA required", "security": [ { "laravelSession": [] } ], "parameters": [], "responses": { "200": { "description": "JSON result with X-Correlation-ID; private, no-store" }, "401": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "403": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "404": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "409": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "422": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" }, "429": { "description": "Request rejected; validation and workflow errors use Problem Details within territorial middleware" } } } } }, "components": { "securitySchemes": { "laravelSession": { "type": "apiKey", "in": "cookie", "name": "deployment_session_cookie", "description": "Actual name configured by Laravel; write requests also require Laravel CSRF/origin protection. This is not OAuth/OIDC." } } } }