{ "openapi": "3.0.3", "info": { "title": "Interplanetary Shipping API", "description": "This API enables interplanetary shipping capabilities through the Cosmo Cargo platform.\n\n## Authentication\nAll endpoints require a valid API key passed in the `X-API-Key` header.\n", "version": "1.0.0", "contact": { "name": "Cosmo Cargo API Support", "email": "api@sh.example.com", "url": "https://developers.sh.example.com" } }, "servers": [ { "url": "https://api.sh.example.com/v1", "description": "Production environment" }, { "url": "https://api.staging.sh.example.com/v1", "description": "Staging environment" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "InterplanetaryShipment": { "type": "object", "required": [ "originPlanet", "destinationPlanet", "cargo", "shippingClass" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "originPlanet": { "type": "string", "enum": ["Earth", "Mars", "Venus", "Mercury", "Jupiter"] }, "destinationPlanet": { "type": "string", "enum": ["Earth", "Mars", "Venus", "Mercury", "Jupiter"] }, "cargo": { "$ref": "#/components/schemas/Cargo" }, "shippingClass": { "type": "string", "enum": ["STANDARD", "EXPRESS", "PRIORITY"], "description": "Shipping speed class" }, "radiationShielding": { "type": "boolean", "default": true, "description": "Whether cargo needs radiation shielding" }, "status": { "type": "string", "enum": [ "SCHEDULED", "LAUNCHED", "IN_TRANSIT", "APPROACHING", "LANDED", "DELIVERED" ], "readOnly": true }, "estimatedDelivery": { "type": "string", "format": "date-time", "readOnly": true }, "trackingNumber": { "type": "string", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true } } }, "Cargo": { "type": "object", "required": ["weight", "volume", "category"], "properties": { "weight": { "type": "number", "format": "float", "description": "Weight in metric tons" }, "volume": { "type": "number", "format": "float", "description": "Volume in cubic meters" }, "category": { "type": "string", "enum": [ "GENERAL", "HAZARDOUS", "BIOLOGICAL", "MINERAL", "EQUIPMENT" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Simple string-to-string dictionary for cargo metadata", "example": { "manufacturer": "SpaceTech Inc", "batchNumber": "ST-2024-001" } }, "safetyChecks": { "type": "object", "properties": { "default": { "type": "string", "description": "Default safety check procedure" } }, "required": ["default"], "additionalProperties": { "$ref": "#/components/schemas/SafetyCheck" }, "description": "Dictionary with fixed keys and complex value types", "example": { "default": "Standard equipment check", "radiation": { "procedure": "Radiation level check", "frequency": "DAILY" } } }, "temperatureControl": { "type": "object", "properties": { "required": { "type": "boolean" }, "minTemp": { "type": "number", "description": "Minimum temperature in Celsius" }, "maxTemp": { "type": "number", "description": "Maximum temperature in Celsius" } } } } }, "SafetyCheck": { "type": "object", "properties": { "procedure": { "type": "string" }, "frequency": { "type": "string", "enum": ["DAILY", "WEEKLY", "MONTHLY"] } } }, "SpecializedCargo": { "allOf": [ { "$ref": "#/components/schemas/Cargo" }, { "type": "object", "properties": { "specialization": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["CRYO", "QUANTUM", "ANTIMATTER"] } } }, { "type": "object", "properties": { "containmentLevel": { "type": "integer", "minimum": 1, "maximum": 5 } } }, { "type": "object", "properties": { "cryogenicTemp": { "type": "number", "maximum": -150, "description": "Required for CRYO type" }, "coherenceTime": { "type": "number", "minimum": 0, "description": "Required for QUANTUM type" }, "antimatterMass": { "type": "number", "minimum": 0, "description": "Required for ANTIMATTER type" } } } ] } }, "required": ["specialization"] } ] }, "ShippingRoute": { "type": "object", "properties": { "routeType": { "type": "string", "enum": ["DIRECT", "MULTI_HOP"] }, "route": { "oneOf": [ { "type": "object", "properties": { "direct": { "type": "object", "properties": { "estimatedDays": { "type": "integer", "minimum": 1 }, "fuelType": { "type": "string", "enum": ["ION", "CHEMICAL", "SOLAR"] } }, "required": ["estimatedDays", "fuelType"] } }, "required": ["direct"] }, { "type": "object", "properties": { "multiHop": { "type": "object", "properties": { "stops": { "type": "array", "items": { "type": "string", "enum": [ "Earth", "Mars", "Venus", "Mercury", "Jupiter" ] }, "minItems": 2 }, "stopDuration": { "type": "integer", "minimum": 0 } }, "required": ["stops", "stopDuration"] } }, "required": ["multiHop"] } ] }, "requirements": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "gravitationalAssist": { "type": "object", "properties": { "planet": { "type": "string" }, "minVelocity": { "type": "number" } }, "required": ["planet", "minVelocity"] } }, "required": ["gravitationalAssist"] }, { "type": "object", "properties": { "refuel": { "type": "object", "properties": { "station": { "type": "string" }, "amount": { "type": "number" } }, "required": ["station", "amount"] } }, "required": ["refuel"] } ] } } }, "required": ["routeType", "route"] }, "Error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "PaymentMethod": { "oneOf": [ { "type": "object", "title": "Credit Card", "properties": { "type": { "type": "string", "const": "credit_card" }, "cardNumber": { "type": "string", "pattern": "^[0-9]{16}$" }, "expiryDate": { "type": "string", "pattern": "^(0[1-9]|1[0-2])/[0-9]{2}$" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$" } }, "required": ["type", "cardNumber", "expiryDate", "cvv"] }, { "type": "object", "title": "Bank Transfer", "properties": { "type": { "type": "string", "const": "bank_transfer" }, "accountNumber": { "type": "string", "minLength": 10, "maxLength": 20 }, "routingNumber": { "type": "string", "pattern": "^[0-9]{9}$" }, "bankName": { "type": "string" } }, "required": ["type", "accountNumber", "routingNumber", "bankName"] }, { "type": "object", "title": "Crypto Payment", "properties": { "type": { "type": "string", "const": "crypto" }, "currency": { "type": "string", "enum": ["BTC", "ETH", "USDC"] }, "walletAddress": { "type": "string", "minLength": 26, "maxLength": 42 } }, "required": ["type", "currency", "walletAddress"] } ], "discriminator": { "propertyName": "type" } }, "CargoContents": { "anyOf": [ { "type": "object", "title": "Liquid Cargo", "description": "Properties specific to liquid cargo", "properties": { "state": { "type": "string", "const": "liquid" }, "viscosity": { "type": "number", "minimum": 0, "description": "Viscosity in cP" }, "density": { "type": "number", "minimum": 0, "description": "Density in kg/m³" }, "flammable": { "type": "boolean" } }, "required": ["state", "viscosity", "density"] }, { "type": "object", "title": "Solid Cargo", "description": "Properties specific to solid cargo", "properties": { "state": { "type": "string", "const": "solid" }, "hardness": { "type": "number", "minimum": 0, "maximum": 10, "description": "Mohs hardness scale" }, "fragile": { "type": "boolean" } }, "required": ["state", "hardness"] }, { "type": "object", "title": "Gas Cargo", "description": "Properties specific to gaseous cargo", "properties": { "state": { "type": "string", "const": "gas" }, "pressure": { "type": "number", "minimum": 0, "description": "Pressure in bar" }, "compressed": { "type": "boolean" } }, "required": ["state", "pressure"] } ], "discriminator": { "propertyName": "state" } }, "PrimitiveUnion": { "anyOf": [ { "type": "string", "description": "Text identifier" }, { "type": "number", "description": "Numeric identifier" }, { "type": "boolean", "description": "Flag value" } ] }, "NullableString": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "FlexibleArray": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "number" } }, "required": ["id", "value"] } ] } }, "MixedRequirements": { "anyOf": [ { "type": "object", "title": "Option A", "properties": { "common": { "type": "string", "description": "Common field across all variants" }, "optionA": { "type": "string" }, "specificToA": { "type": "number", "minimum": 0 } }, "required": ["common", "optionA"] }, { "type": "object", "title": "Option B", "properties": { "common": { "type": "string", "description": "Common field across all variants" }, "optionB": { "type": "boolean" }, "specificToB": { "type": "array", "items": { "type": "string" } } }, "required": ["common", "optionB", "specificToB"] }, { "type": "object", "title": "Option C", "properties": { "common": { "type": "string", "description": "Common field across all variants" }, "optionC": { "type": "integer", "enum": [1, 2, 3] } }, "required": ["common"] } ] }, "LargeUnion": { "oneOf": [ { "type": "object", "title": "Type 1", "properties": { "type": { "const": 1 }, "data": { "type": "string" } }, "required": ["type", "data"] }, { "type": "object", "title": "Type 2", "properties": { "type": { "const": 2 }, "data": { "type": "number" } }, "required": ["type", "data"] }, { "type": "object", "title": "Type 3", "properties": { "type": { "const": 3 }, "data": { "type": "boolean" } }, "required": ["type", "data"] }, { "type": "object", "title": "Type 4", "properties": { "type": { "const": 4 }, "data": { "type": "array", "items": { "type": "string" } } }, "required": ["type", "data"] }, { "type": "object", "title": "Type 5", "properties": { "type": { "const": 5 }, "data": { "type": "object", "additionalProperties": true } }, "required": ["type", "data"] } ], "discriminator": { "propertyName": "type" } }, "EnhancedShipment": { "description": "An enhanced shipment that combines base shipment properties with premium features", "allOf": [ { "$ref": "#/components/schemas/InterplanetaryShipment" }, { "type": "object", "properties": { "premiumFeatures": { "oneOf": [ { "type": "object", "title": "Insurance Package", "properties": { "featureType": { "type": "string", "const": "insurance" }, "coverageAmount": { "type": "number", "minimum": 1000, "description": "Coverage amount in credits" }, "deductible": { "type": "number", "minimum": 0, "description": "Deductible amount in credits" }, "coverageType": { "type": "string", "enum": ["BASIC", "COMPREHENSIVE", "PLATINUM"], "description": "Type of insurance coverage" } }, "required": [ "featureType", "coverageAmount", "coverageType" ] }, { "type": "object", "title": "Advanced Tracking", "properties": { "featureType": { "type": "string", "const": "tracking" }, "updateFrequency": { "type": "string", "enum": ["HOURLY", "REAL_TIME", "QUANTUM_ENTANGLED"], "description": "How often tracking updates are provided" }, "sensors": { "type": "array", "items": { "type": "string", "enum": [ "LOCATION", "TEMPERATURE", "RADIATION", "ACCELERATION", "QUANTUM_STATE" ] }, "minItems": 1, "description": "Active sensors for tracking" } }, "required": ["featureType", "updateFrequency", "sensors"] }, { "type": "object", "title": "Priority Handling", "properties": { "featureType": { "type": "string", "const": "priority" }, "queuePosition": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Priority queue position (1 is highest)" }, "guaranteedDelivery": { "type": "boolean", "description": "Whether delivery date is guaranteed" }, "compensationRate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Compensation percentage for late delivery" } }, "required": [ "featureType", "queuePosition", "guaranteedDelivery" ] } ], "discriminator": { "propertyName": "featureType" } }, "securityOptions": { "description": "Additional security measures for the shipment", "anyOf": [ { "type": "object", "title": "Biometric Lock", "properties": { "biometricLock": { "type": "object", "properties": { "type": { "type": "string", "enum": ["FINGERPRINT", "RETINAL", "DNA"] }, "authorizedPersonnel": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": ["type", "authorizedPersonnel"] } }, "required": ["biometricLock"] }, { "type": "object", "title": "Quantum Encryption", "properties": { "quantumEncryption": { "type": "object", "properties": { "qubits": { "type": "integer", "minimum": 128, "maximum": 4096 }, "entanglementKey": { "type": "string", "pattern": "^QK-[A-Z0-9]{16}$" } }, "required": ["qubits", "entanglementKey"] } }, "required": ["quantumEncryption"] }, { "type": "object", "title": "Armed Escort", "properties": { "armedEscort": { "type": "object", "properties": { "escortShips": { "type": "integer", "minimum": 1, "maximum": 5 }, "weaponClass": { "type": "string", "enum": ["DEFENSIVE", "OFFENSIVE", "MIXED"] } }, "required": ["escortShips", "weaponClass"] } }, "required": ["armedEscort"] } ] } }, "required": ["premiumFeatures"] } ] }, "ComplexRoute": { "description": "A complex routing configuration with nested logical operators", "type": "object", "properties": { "routeId": { "type": "string", "format": "uuid" }, "configuration": { "allOf": [ { "type": "object", "properties": { "baseRoute": { "$ref": "#/components/schemas/ShippingRoute" } }, "required": ["baseRoute"] }, { "oneOf": [ { "type": "object", "title": "Emergency Route", "properties": { "routeClass": { "type": "string", "const": "emergency" }, "hazardType": { "type": "string", "enum": [ "ASTEROID_FIELD", "SOLAR_FLARE", "PIRATE_ACTIVITY", "WORMHOLE_INSTABILITY" ] }, "alternativeStops": { "type": "array", "items": { "anyOf": [ { "type": "object", "title": "Space Station", "properties": { "type": { "const": "station" }, "stationId": { "type": "string" }, "dockingBay": { "type": "integer" } }, "required": ["type", "stationId"] }, { "type": "object", "title": "Emergency Beacon", "properties": { "type": { "const": "beacon" }, "coordinates": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "required": ["x", "y", "z"] } }, "required": ["type", "coordinates"] } ] }, "minItems": 1 } }, "required": ["routeClass", "hazardType", "alternativeStops"] }, { "type": "object", "title": "Optimized Route", "properties": { "routeClass": { "type": "string", "const": "optimized" }, "optimizationCriteria": { "anyOf": [ { "type": "object", "properties": { "criterion": { "const": "fuel_efficiency" }, "targetSaving": { "type": "number", "minimum": 0, "maximum": 50, "description": "Target fuel saving percentage" } }, "required": ["criterion", "targetSaving"] }, { "type": "object", "properties": { "criterion": { "const": "time_optimization" }, "maxDays": { "type": "integer", "minimum": 1 } }, "required": ["criterion", "maxDays"] }, { "type": "object", "properties": { "criterion": { "const": "safety_priority" }, "avoidanceZones": { "type": "array", "items": { "type": "string", "enum": [ "ASTEROID_BELT", "RADIATION_ZONE", "CONTESTED_SPACE" ] }, "minItems": 1 } }, "required": ["criterion", "avoidanceZones"] } ] } }, "required": ["routeClass", "optimizationCriteria"] } ], "discriminator": { "propertyName": "routeClass" } } ] } }, "required": ["routeId", "configuration"] }, "FuelStation": { "type": "object", "description": "A fuel station along interplanetary routes", "required": ["stationId", "name", "location"], "properties": { "stationId": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique identifier for the fuel station" }, "name": { "type": "string", "description": "Name of the fuel station" }, "location": { "type": "string", "enum": [ "Earth Orbit", "Mars Orbit", "Venus Orbit", "Jupiter Orbit", "Asteroid Belt" ], "description": "Orbital location of the station" }, "fuelTypes": { "type": "array", "items": { "type": "string", "enum": ["ION", "CHEMICAL", "SOLAR", "NUCLEAR"] }, "description": "Available fuel types at this station" }, "capacity": { "type": "number", "description": "Maximum fuel capacity in metric tons" }, "currentAvailability": { "type": "number", "minimum": 0, "maximum": 100, "description": "Current fuel availability percentage" } } } } }, "paths": { "/interplanetary/shipments": { "post": { "tags": ["Interplanetary"], "summary": "Create a shipment", "description": "Creates a new interplanetary shipment with the provided details", "operationId": "createInterplanetaryShipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterplanetaryShipment" }, "example": { "originPlanet": "Earth", "destinationPlanet": "Mars", "cargo": { "weight": 2.5, "volume": 3.0, "category": "EQUIPMENT", "temperatureControl": { "required": true, "minTemp": -10, "maxTemp": 25 } }, "shippingClass": "PRIORITY", "radiationShielding": true } } } }, "responses": { "201": { "description": "Shipment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterplanetaryShipment" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "INVALID_INPUT", "message": "Invalid planet combination or cargo specifications" } } } } } } }, "/interplanetary/shipments/{trackingNumber}": { "get": { "tags": ["Interplanetary"], "summary": "Track shipment", "description": "Get the current status and tracking information for an interplanetary shipment", "operationId": "trackInterplanetaryShipment", "parameters": [ { "name": "trackingNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shipment tracking information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterplanetaryShipment" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NOT_FOUND", "message": "Shipment with tracking number not found" } } } } } } }, "/interplanetary/specialized-shipments": { "post": { "tags": ["Interplanetary"], "summary": "Create specialized shipment", "description": "Creates a new interplanetary shipment for specialized cargo types like cryo, quantum, or antimatter", "operationId": "createSpecializedShipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/InterplanetaryShipment" }, { "type": "object", "properties": { "cargo": { "$ref": "#/components/schemas/SpecializedCargo" } } } ] }, "example": { "originPlanet": "Earth", "destinationPlanet": "Mars", "cargo": { "weight": 1.5, "volume": 2.0, "category": "HAZARDOUS", "specialization": { "type": "CRYO", "containmentLevel": 4, "cryogenicTemp": -196.5 } }, "shippingClass": "PRIORITY", "radiationShielding": true } } } }, "responses": { "201": { "description": "Specialized shipment created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/InterplanetaryShipment" }, { "type": "object", "properties": { "cargo": { "$ref": "#/components/schemas/SpecializedCargo" } } } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interplanetary/route-planning": { "post": { "tags": ["Interplanetary"], "summary": "Plan shipping route", "description": "Plans a shipping route with either direct or multi-hop configuration", "operationId": "planShippingRoute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRoute" }, "examples": { "direct": { "value": { "routeType": "DIRECT", "route": { "direct": { "estimatedDays": 180, "fuelType": "ION" } } } }, "multiHop": { "value": { "routeType": "MULTI_HOP", "route": { "multiHop": { "stops": ["Earth", "Mars", "Jupiter"], "stopDuration": 5 } }, "requirements": [ { "gravitationalAssist": { "planet": "Venus", "minVelocity": 11.2 } }, { "refuel": { "station": "Mars-Station-1", "amount": 500 } } ] } } } } } }, "responses": { "200": { "description": "Route planned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRoute" } } } }, "400": { "description": "Invalid route configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interplanetary/fuel-stations": { "get": { "tags": ["Interplanetary"], "summary": "List fuel stations", "description": "Returns all available fuel stations along interplanetary routes", "operationId": "listFuelStations", "parameters": [ { "name": "location", "in": "query", "description": "Filter by orbital location", "schema": { "type": "string", "enum": [ "Earth Orbit", "Mars Orbit", "Venus Orbit", "Jupiter Orbit", "Asteroid Belt" ] } }, { "name": "fuelType", "in": "query", "description": "Filter by fuel type (pipe-delimited: fuelType=ION|CHEMICAL)", "schema": { "type": "array", "items": { "type": "string", "enum": ["ION", "CHEMICAL", "SOLAR", "NUCLEAR"] } }, "style": "pipeDelimited", "explode": false }, { "name": "features", "in": "query", "description": "Filter by station features (comma-separated: features=REPAIR_BAY,CARGO_TRANSFER)", "schema": { "type": "array", "items": { "type": "string", "enum": [ "REPAIR_BAY", "CARGO_TRANSFER", "CREW_REST", "EMERGENCY_DOCK" ] } }, "style": "form", "explode": false }, { "name": "status", "in": "query", "description": "Filter by station status (exploded: status=ACTIVE&status=MAINTENANCE)", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "MAINTENANCE", "DECOMMISSIONED", "UNDER_CONSTRUCTION" ] } }, "style": "form", "explode": true }, { "name": "sectors", "in": "query", "description": "Filter by space sectors (space-delimited: sectors=ALPHA%20BETA)", "schema": { "type": "array", "items": { "type": "string", "enum": ["ALPHA", "BETA", "GAMMA", "DELTA"] } }, "style": "spaceDelimited", "explode": false } ], "responses": { "200": { "description": "List of fuel stations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FuelStation" } } } } } } } } } }