{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexcade contact API",
    "version": "1.1.0",
    "description": "Submit working session requests for Nexcade. Ask the human for any missing required fields before submitting. If you cannot POST to this endpoint, help the user draft a short email to hello@nexcade.ai covering the same fields (name, work email, company, workflow, and where the work gets stuck), then let them copy and paste it or send it if you have email access.",
    "contact": {
      "name": "Nexcade",
      "email": "hello@nexcade.ai",
      "url": "https://nexcade.ai/contact/"
    }
  },
  "servers": [
    {
      "url": "https://nexcade.ai"
    }
  ],
  "externalDocs": {
    "description": "Human contact page",
    "url": "https://nexcade.ai/contact/"
  },
  "paths": {
    "/api/contact": {
      "get": {
        "summary": "Read the contact API field guide",
        "description": "Returns a compact machine-readable description of the working session request endpoint.",
        "operationId": "getContactRequestSchema",
        "tags": ["contact"],
        "responses": {
          "200": {
            "description": "Contact endpoint field guide",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactFieldGuide"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Request a Nexcade working session",
        "description": "Send a short request for Nexcade to discuss freight quoting, tenders, rate updates, bookings, or reporting. Include useful context in message, such as preferred time windows, workflow details, or systems used.",
        "operationId": "requestWorkingSession",
        "tags": ["contact"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkingSessionRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic request",
                  "value": {
                    "name": "Alex Morgan",
                    "email": "alex@example.com",
                    "company": "Example Forwarding",
                    "workflow": "Quoting",
                    "message": "We want to discuss quote turnaround for ocean imports and preferred times for a first call.",
                    "source": "AI assistant"
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/WorkingSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                },
                "examples": {
                  "received": {
                    "value": {
                      "ok": true,
                      "message": "Thanks. We have your details."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "500": {
            "description": "Contact form unavailable. Email hello@nexcade.ai with the same fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "502": {
            "description": "Sending failed. Email hello@nexcade.ai with the same fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WorkingSessionRequest": {
        "type": "object",
        "required": ["name", "email"],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Requester full name.",
            "maxLength": 160,
            "minLength": 1
          },
          "email": {
            "type": "string",
            "description": "Requester work email.",
            "format": "email",
            "maxLength": 220,
            "minLength": 3
          },
          "company": {
            "type": "string",
            "description": "Requester company.",
            "maxLength": 180
          },
          "workflow": {
            "type": "string",
            "description": "Main workflow they want to discuss.",
            "enum": ["Quoting", "Tenders", "Rate updates", "Bookings", "Reporting", "Something else"]
          },
          "message": {
            "type": "string",
            "description": "Short context for the request. Include preferred time windows when useful.",
            "maxLength": 4000
          },
          "source": {
            "type": "string",
            "description": "Where the request came from.",
            "maxLength": 120,
            "default": "AI assistant"
          },
          "utm_source": {
            "type": "string",
            "description": "Optional first-touch utm_source supplied by the website. Machine clients should omit it unless they have a genuine value.",
            "maxLength": 100,
            "pattern": "^[A-Za-z0-9._ -]*$"
          },
          "referrer": {
            "type": "string",
            "description": "Optional external referring origin supplied by the website. Paths, queries and fragments are removed.",
            "format": "uri",
            "maxLength": 500
          },
          "landing_page": {
            "type": "string",
            "description": "Optional first landing-page path supplied by the website. Queries and fragments are removed.",
            "maxLength": 500,
            "pattern": "^/(?!/).*$"
          }
        }
      },
      "ContactResponse": {
        "type": "object",
        "required": ["ok", "message"],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ContactFieldGuide": {
        "type": "object",
        "description": "Compact field guide returned by GET /api/contact.",
        "additionalProperties": true
      }
    }
  }
}