{"openapi":"3.1.0","info":{"title":"PlatPhorm Shipments API","version":"0.0.3","description":"Public-safe USPS REST API v3 shipping-rate calculator, domestic and international estimator, customs validation helper, package preset system, e-commerce quote utility, and MCP shipping tooling surface. Rates are live carrier responses when USPS is configured; Shipments returns honest degraded states and no fabricated rates when the provider is unavailable.","contact":{"name":"PlatPhormNews","url":"https://platphormnews.com","email":"Michael@barbineworldwide.com"}},"servers":[{"url":"https://shipments.platphormnews.com","description":"Canonical production Shipments service"}],"tags":[{"name":"Rates","description":"Public-safe domestic and international rate calculation"},{"name":"Customs","description":"Customs field validation helpers"},{"name":"Packages","description":"Built-in and editable package presets"},{"name":"Status","description":"Carrier, integration, and platform status"},{"name":"MCP","description":"JSON-RPC 2.0 MCP endpoint metadata"},{"name":"Discovery","description":"Public route, discovery, and trust surfaces"}],"paths":{"/api/health":{"get":{"tags":["Status"],"summary":"Get public-safe Shipments health JSON","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/health":{"get":{"tags":["Status"],"summary":"Get public-safe Shipments health JSON","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/status":{"get":{"tags":["Status"],"summary":"Get public Shipments service status","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/usps/status":{"get":{"tags":["Status"],"summary":"Get USPS provider configuration and availability status","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/quickbooks/status":{"get":{"tags":["Status"],"summary":"Get QuickBooks integration status","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/services":{"get":{"tags":["Status"],"summary":"List USPS service metadata; rate amounts are not static","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/packages/presets":{"get":{"tags":["Packages"],"summary":"List 17 public-safe package presets","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/packages/presets/automotive":{"get":{"tags":["Packages"],"summary":"List 16 automotive package presets","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/rates":{"post":{"tags":["Rates"],"summary":"Calculate a public-safe Shipments rate request","description":"Returns live USPS rates when the provider is configured and available. If not, returns no fabricated rate amounts and an explicit degraded/unavailable provider state.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomesticRateRequest"}}}},"responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/rates/domestic":{"post":{"tags":["Rates"],"summary":"Calculate domestic USPS rates or return an honest degraded state","description":"Returns live USPS rates when the provider is configured and available. If not, returns no fabricated rate amounts and an explicit degraded/unavailable provider state.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomesticRateRequest"}}}},"responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/rates/calculate":{"post":{"tags":["Rates"],"summary":"Backward-compatible domestic USPS rate endpoint","description":"Returns live USPS rates when the provider is configured and available. If not, returns no fabricated rate amounts and an explicit degraded/unavailable provider state.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomesticRateRequest"}}}},"responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/rates/international":{"post":{"tags":["Rates"],"summary":"Calculate international USPS rates or return an honest degraded state","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternationalRateRequest"}}}},"responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/customs/validate":{"post":{"tags":["Customs"],"summary":"Validate customs declaration fields without fabricating compliance certainty","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/ecommerce/quote":{"post":{"tags":["Rates"],"summary":"Create a public-safe e-commerce quote response without private persistence by default","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/v1/reports/quote":{"post":{"tags":["Status"],"summary":"Future protected quote report generation","description":"Public Phase 1 returns explicit degraded/future-protected metadata. Enforcement can be enabled with PLATPHORM_REQUIRE_API_KEY.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/api/mcp":{"get":{"tags":["MCP"],"summary":"Read MCP endpoint metadata","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}},"post":{"tags":["MCP"],"summary":"Execute JSON-RPC 2.0 MCP requests","description":"Supports initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"examples":{"initialize":{"value":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}},"/openapi.yaml":{"get":{"tags":["Discovery"],"summary":"OpenAPI YAML document","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"OpenAPI JSON document","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Concise LLM discovery document","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/llms-full.txt":{"get":{"tags":["Discovery"],"summary":"Full LLM discovery document","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/llms-index.json":{"get":{"tags":["Discovery"],"summary":"Structured LLM discovery index","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/rss.xml":{"get":{"tags":["Discovery"],"summary":"Public-safe RSS changelog feed","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/feed.xml":{"get":{"tags":["Discovery"],"summary":"RSS feed alias","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/sitemap.xml":{"get":{"tags":["Discovery"],"summary":"Validated public sitemap","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/sitemap-main.xml":{"get":{"tags":["Discovery"],"summary":"Main public sitemap","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}},"/.well-known/trust.json":{"get":{"tags":["Discovery"],"summary":"Shipments trust policy","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiOk"},{"$ref":"#/components/schemas/ApiError"}]}}}}}}}},"components":{"securitySchemes":{"PlatPhormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Future protected-action platform key. Public-safe Phase 1 calculator, status, docs, discovery, and read-only MCP introspection do not require it by default."},"PlatPhormBearer":{"type":"http","scheme":"bearer","description":"Future protected-action bearer token using PLATPHORM_API_KEY."}},"schemas":{"ApiOk":{"type":"object","properties":{"ok":{"const":true},"data":{"type":"object"}},"required":["ok","data"]},"ApiError":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]},"DomesticRateRequest":{"type":"object","required":["destinationZip","weight"],"properties":{"originZip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"destinationZip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"weight":{"type":"number","minimum":0.1,"maximum":70},"length":{"type":"number","minimum":0.1},"width":{"type":"number","minimum":0.1},"height":{"type":"number","minimum":0.1},"mailClass":{"type":"string","enum":["ALL","USPS_GROUND_ADVANTAGE","PRIORITY_MAIL","PRIORITY_MAIL_EXPRESS","PARCEL_SELECT","MEDIA_MAIL"]},"priceType":{"type":"string","enum":["RETAIL","COMMERCIAL","CONTRACT"]}}},"InternationalRateRequest":{"type":"object","required":["destinationCountry","weight"],"properties":{"originZip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"destinationCountry":{"type":"string","minLength":2,"maxLength":2,"description":"15 countries are available in the validator."},"foreignPostalCode":{"type":"string"},"weight":{"type":"number","minimum":0.1,"maximum":70},"length":{"type":"number","minimum":0.1},"width":{"type":"number","minimum":0.1},"height":{"type":"number","minimum":0.1},"contentType":{"type":"string","enum":["MERCHANDISE","GIFT","DOCUMENT","SAMPLE","RETURNED_GOODS","OTHER"]},"declaredValue":{"type":"number","minimum":0.01},"hsCode":{"type":"string"}}}}},"security":[],"x-platphorm-auth-policy":{"publicSafeByDefault":true,"requireApiKey":false,"acceptedHeaders":["Authorization: Bearer $PLATPHORM_API_KEY","X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"],"futureProtectedActions":["protected rate quote persistence","shipping label creation","carrier account operations","QuickBooks and e-commerce sync","package preset mutation","bulk rate comparisons","report generation","administrative sync jobs"]}}