{ "openapi": "3.0.3", "info": { "title": "InvestMoz zone foundation API", "version": "2026-09-28", "description": "Implemented local routes only. Session cookies and CSRF; no bearer protocol invented. Admin: verified manager with confirmed MFA; legal/GIS/publish actions also require configured designated role. 30 requests/minute for management; public API uses application throttle. Approval in the portal is documentary review, not an administrative act. API v1 remains compatible and adds optional zee_id/zfi_id/park_id filters. Response schemas are deliberately open pending full contract typing." }, "paths": { "/api/v2/investment/admin/legal-sources": { "get": { "operationId": "InvestmentLegalSourceController_index_0", "summary": "InvestmentLegalSourceController@index", "parameters": [], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "InvestmentLegalSourceController_store_1", "summary": "InvestmentLegalSourceController@store", "parameters": [], "security": [ { "laravelSession": [] } ], "responses": { "201": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalSource" } } } } } }, "/api/v2/investment/admin/legal-sources/{id}/{action}": { "post": { "operationId": "InvestmentLegalSourceController_transition_2", "summary": "InvestmentLegalSourceController@transition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "validate", "revoke" ] } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/api/v2/investment/admin/zone-geometries/{id}/{action}": { "post": { "operationId": "InvestmentZoneGeometryController_review_3", "summary": "InvestmentZoneGeometryController@review", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "validate", "revoke" ] } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/api/v2/investment/admin/zone-links/{id}/{action}": { "post": { "operationId": "InvestmentZoneLinkController_transition_4", "summary": "InvestmentZoneLinkController@transition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "validate", "revoke" ] } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/api/v2/investment/admin/zone-relations/{id}/{action}": { "post": { "operationId": "InvestmentZoneRelationController_review_5", "summary": "InvestmentZoneRelationController@review", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "validate", "revoke" ] } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/api/v2/investment/admin/zones": { "get": { "operationId": "InvestmentZoneController_index_6", "summary": "InvestmentZoneController@index", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "zee", "zfi", "industrial_park" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "InvestmentZoneController_save_7", "summary": "InvestmentZoneController@save", "parameters": [], "security": [ { "laravelSession": [] } ], "responses": { "201": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } } } } }, "/api/v2/investment/admin/zones/{id}": { "get": { "operationId": "InvestmentZoneController_show_8", "summary": "InvestmentZoneController@show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } }, "put": { "operationId": "InvestmentZoneController_save_9", "summary": "InvestmentZoneController@save", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } } } } }, "/api/v2/investment/admin/zones/{id}/geometries": { "post": { "operationId": "InvestmentZoneGeometryController_store_10", "summary": "InvestmentZoneGeometryController@store", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "201": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Geometry" } } } } } }, "/api/v2/investment/admin/zones/{id}/links": { "post": { "operationId": "InvestmentZoneLinkController_store_11", "summary": "InvestmentZoneLinkController@store", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "201": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } } } }, "/api/v2/investment/admin/zones/{id}/relations": { "post": { "operationId": "InvestmentZoneRelationController_store_12", "summary": "InvestmentZoneRelationController@store", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "201": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Relation" } } } } } }, "/api/v2/investment/admin/zones/{id}/revisions": { "get": { "operationId": "InvestmentZoneController_revisions_13", "summary": "InvestmentZoneController@revisions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } } }, "/api/v2/investment/admin/zones/{id}/{action}": { "post": { "operationId": "InvestmentZoneController_transition_14", "summary": "InvestmentZoneController@transition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "publish", "suspend" ] } } ], "security": [ { "laravelSession": [] } ], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/api/v2/investment/zone-map": { "get": { "operationId": "InvestmentZoneGeometryController_map_15", "summary": "InvestmentZoneGeometryController@map", "parameters": [ { "name": "zone_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "bbox[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number" } }, "description": "west,south,east,north; no antimeridian wrap." } ], "security": [], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } } }, "/api/v2/investment/zones": { "get": { "operationId": "InvestmentZoneController_index_16", "summary": "InvestmentZoneController@index", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "zee", "zfi", "industrial_park" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "security": [], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } } }, "/api/v2/investment/zones/{id}": { "get": { "operationId": "InvestmentZoneController_show_17", "summary": "InvestmentZoneController@show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [], "responses": { "200": { "description": "Success. JSON; paginated lists. Private management responses use Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing manager/MFA/designated role or self-review." }, "404": { "description": "Not found or not publicly visible." }, "409": { "description": "Stale version or duplicate relation." }, "419": { "description": "Session/CSRF validation failed." }, "422": { "description": "Invalid data, source, geometry, overlap or workflow." }, "429": { "description": "Rate limit exceeded." } } } } }, "components": { "securitySchemes": { "laravelSession": { "type": "apiKey", "in": "cookie", "name": "laravel_session", "description": "Actual session cookie name is configured by Laravel. Send X-XSRF-TOKEN from the session; no credentials embedded." } }, "schemas": { "Version": { "type": "object", "properties": { "version_no": { "type": "integer", "minimum": 1 } }, "required": [ "version_no" ] }, "Zone": { "type": "object", "properties": { "version_no": { "type": "integer", "minimum": 1 }, "code": { "type": "string", "maxLength": 80 }, "category": { "type": "string", "enum": [ "zee", "zfi", "industrial_park", "pending" ] }, "name": { "type": "string", "maxLength": 255 }, "name_en": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "description_en": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true }, "district": { "type": "string", "nullable": true }, "operator_id": { "type": "string", "format": "uuid", "nullable": true }, "legal_source_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "code", "category", "name" ], "description": "PUT requires version_no. Save withdraws publication and requires a new independent review. No official status inferred from category." }, "LegalSource": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "HTTPS reference only; no remote download." }, "diploma": { "type": "string" }, "article": { "type": "string" }, "competent_entity": { "type": "string" }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date", "nullable": true } }, "required": [ "title", "url", "diploma", "article", "competent_entity", "valid_from" ] }, "Link": { "type": "object", "properties": { "opportunity_id": { "type": "integer", "minimum": 1 }, "association_type": { "type": "string", "enum": [ "official", "influence", "proximity", "potential", "historical" ] }, "role": { "type": "string", "enum": [ "primary", "beneficiary", "served", "enabled", "dependent", "related", "potential", "historical" ] }, "source_reference": { "type": "string", "minLength": 10, "maxLength": 2000 }, "justification": { "type": "string", "minLength": 10, "maxLength": 3000 }, "legal_source_id": { "type": "string", "format": "uuid", "nullable": true }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date", "nullable": true }, "priority": { "type": "integer", "minimum": 0, "maximum": 100 }, "is_primary": { "type": "boolean" } }, "required": [ "opportunity_id", "association_type", "role", "source_reference", "justification", "valid_from" ], "description": "Official association requires legal_source_id. Creates or reuses UUID mapping for existing opportunity; duplicate zone-item pair returns 409. Potential remains potential after review." }, "Relation": { "type": "object", "properties": { "cluster_id": { "type": "string", "format": "uuid", "nullable": true }, "corridor_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "association_type": { "type": "string", "enum": [ "official", "influence", "proximity", "potential", "historical" ] }, "role": { "type": "string", "enum": [ "primary", "beneficiary", "served", "enabled", "dependent", "related", "potential", "historical" ] }, "source_reference": { "type": "string", "minLength": 10, "maxLength": 2000 }, "justification": { "type": "string", "minLength": 10, "maxLength": 3000 }, "legal_source_id": { "type": "string", "format": "uuid", "nullable": true }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date", "nullable": true }, "priority": { "type": "integer", "minimum": 0, "maximum": 100 }, "is_primary": { "type": "boolean" } }, "required": [ "association_type", "role", "source_reference", "justification", "valid_from" ], "description": "Exactly one of cluster_id, corridor_id, project_id. Official association requires legal_source_id. Unique zone-target pair; duplicate returns 409." }, "Geometry": { "type": "object", "properties": { "geometry": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Point", "LineString", "Polygon", "MultiPolygon" ] }, "coordinates": { "type": "array", "items": {} } }, "required": [ "type", "coordinates" ] }, "purpose": { "type": "string", "enum": [ "official_perimeter", "influence", "site", "alternative" ] }, "legal_source_id": { "type": "string", "format": "uuid", "nullable": true }, "source_reference": { "type": "string" }, "validating_entity": { "type": "string" }, "observed_at": { "type": "string", "format": "date" } }, "required": [ "geometry", "purpose", "source_reference", "validating_entity", "observed_at" ], "description": "GeoJSON geometry in EPSG:4326, 2D, valid, nonempty, max 200000 encoded bytes. Official perimeter requires Polygon/MultiPolygon and legal source. No status inferred from geometry." } } } }