{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"WythinForge agent inquiries","version":"1.0.0"},"servers":[{"url":"https://wythinforge.com"}],"paths":{"/api/v1/agent-inquiries":{"post":{"operationId":"submitAgentInquiry","summary":"Submit a reviewed brief to WythinForge","description":"Get the person's approval of the brief and privacy notice before sending. Use an invitation issued for their email. Send only the approved text, up to 40960 UTF-8 bytes. Keep authorization in the request header. After a network failure or 503, retry the identical body and key while the invitation is valid. A 200 includes the original receipt on safe retries. A receipt records an inquiry for review.","security":[{"AgentInvitation":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"description":"The UUID provided with the invitation. Use it for this brief and its retries.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"company":{"type":"string","minLength":2,"maxLength":160},"problemStatement":{"type":"string","minLength":30,"maxLength":5000},"currentTools":{"type":"string","maxLength":1000},"desiredOutcome":{"type":"string","minLength":10,"maxLength":2000},"collaborationMode":{"type":"string","enum":["continuous","milestones"]},"urgency":{"type":"string","enum":["low","normal","high","critical"]},"locale":{"type":"string","enum":["it","en"]},"privacyConsent":{"type":"boolean","const":true},"privacyNoticeVersion":{"type":"string","const":"2026-11-07"}},"required":["fullName","email","company","problemStatement","desiredOutcome","collaborationMode","urgency","locale","privacyConsent","privacyNoticeVersion"],"additionalProperties":false},"examples":{"it":{"value":{"fullName":"Sam Rossi","email":"sam@example.com","company":"Example Studio","problemStatement":"Consolidiamo ogni settimana le richieste dei clienti da due caselle email in un foglio condiviso.","currentTools":"Email e foglio condiviso","desiredOutcome":"Accorciare il passaggio e avere uno stato aggiornato per ogni richiesta.","collaborationMode":"milestones","urgency":"normal","locale":"it","privacyConsent":true,"privacyNoticeVersion":"2026-11-07"}},"en":{"value":{"fullName":"Sam Rossi","email":"sam@example.com","company":"Example Studio","problemStatement":"Each week we copy customer requests from two inboxes into a shared spreadsheet.","currentTools":"Email and a shared spreadsheet","desiredOutcome":"Reduce manual entry and keep a current status for every request.","collaborationMode":"milestones","urgency":"normal","locale":"en","privacyConsent":true,"privacyNoticeVersion":"2026-11-07"}}}}}},"responses":{"200":{"description":"Recorded for review. An identical replay returns the same inquiry ID.","content":{"application/json":{"schema":{"type":"object","required":["code","inquiryId","correlationId"],"properties":{"code":{"const":"received"},"inquiryId":{"type":"string"},"correlationId":{"type":"string","format":"uuid"}}}}}},"400":{"description":"invalid_idempotency_key, invalid_json","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["invalid_idempotency_key","invalid_json"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"invalid_invitation","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["invalid_invitation"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"403":{"description":"email_mismatch","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["email_mismatch"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"409":{"description":"invitation_already_used","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["invitation_already_used"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"413":{"description":"payload_too_large","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["payload_too_large"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"415":{"description":"json_required","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["json_required"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"422":{"description":"invalid_brief","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["invalid_brief"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}},"503":{"description":"intake_unavailable","content":{"application/json":{"schema":{"type":"object","required":["code","correlationId"],"properties":{"code":{"enum":["intake_unavailable"]},"correlationId":{"type":"string","format":"uuid"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"details":{"type":"array","items":{"type":"string"}}}}}}}}}}},"components":{"securitySchemes":{"AgentInvitation":{"type":"http","scheme":"bearer","description":"Single-brief invitation from WythinForge. Expires after 24 hours."}}}}