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"
