{"openapi":"3.1.0","info":{"title":"MortgageGuidelines Public API","version":"1.0.0","description":"Server-to-server API for creating conversations, sending messages, listing available sources, and reading conversation history."},"servers":[{"url":"https://api.mortgageguidelines.com","description":"Replace this with your deployed public API origin."}],"tags":[{"name":"Account","description":"Authenticated API key inspection."},{"name":"Discovery","description":"Available source selections for the authenticated API key."},{"name":"Conversations","description":"Conversation lifecycle and history."},{"name":"Messages","description":"Message creation, completion, and streaming responses."}],"components":{"schemas":{"PublicApiTenantSource":{"type":"object","properties":{"key":{"type":"string","minLength":1,"example":"product-guides"},"label":{"type":"string","minLength":1,"example":"Product Guides"},"description":{"type":"string","example":"Client-specific product guidelines"},"groupLabel":{"type":"string","example":"Internal Content"},"defaultOn":{"type":"boolean","example":true}},"required":["key","label","defaultOn"]},"PublicApiTenantBucketSecondarySource":{"type":"object","properties":{"type":{"type":"string","enum":["tenant_bucket"]},"key":{"type":"string","minLength":1,"example":"product-guides"},"label":{"type":"string","minLength":1,"example":"Product Guides"},"description":{"type":"string","example":"Client-specific product guidelines"},"groupLabel":{"type":"string","example":"Internal Content"},"defaultOn":{"type":"boolean","example":true}},"required":["type","key","label","defaultOn"]},"PublicApiSharedSecondarySource":{"type":"object","properties":{"type":{"type":"string","enum":["shared_source"]},"sourceType":{"type":"string","minLength":1,"example":"mortgage_guidelines"},"label":{"type":"string","minLength":1,"example":"Mortgage Guidelines"},"description":{"type":"string","example":"Shared platform content available to multiple clients"},"groupLabel":{"type":"string","example":"Shared Content"},"defaultOn":{"type":"boolean","example":false}},"required":["type","sourceType","label","defaultOn"]},"PublicApiSecondarySource":{"anyOf":[{"$ref":"#/components/schemas/PublicApiTenantBucketSecondarySource"},{"$ref":"#/components/schemas/PublicApiSharedSecondarySource"}]},"PublicApiTenantConfig":{"type":"object","properties":{"clientName":{"type":"string","minLength":1,"example":"Test Client"},"clientOrganization":{"type":"string","example":"Mortgage Guidelines"},"enabledSources":{"type":"array","items":{"type":"string"},"example":["fannie_mae","fha"]},"baseSources":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]},"clientSourceType":{"type":"string","example":"mortgage_guidelines"},"tenantSourceSidebarMode":{"type":"string","enum":["hidden","flat","grouped"],"example":"flat"},"tenantSourceKeys":{"type":"array","items":{"type":"string"},"example":["product-guides"]},"tenantSources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiTenantSource"}},"secondarySources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSecondarySource"}},"defaultTenantSourceKeys":{"type":"array","items":{"type":"string"},"example":["product-guides"]},"defaultSharedSourceTypes":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]},"assignedSharedSourceTypes":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]}},"required":["clientName","enabledSources","baseSources"]},"PublicApiMeKey":{"type":"object","properties":{"id":{"type":"string","minLength":1,"example":"pak_test"},"name":{"type":"string","minLength":1,"example":"Atlantic Bay Production"},"status":{"type":"string","enum":["active","revoked"],"example":"active"},"scopes":{"type":"array","items":{"type":"string"},"example":["chat:read","chat:write","sources:read"]},"last_four":{"type":"string","minLength":1,"example":"test"},"tenant":{"$ref":"#/components/schemas/PublicApiTenantConfig"}},"required":["id","name","status","scopes","last_four","tenant"]},"PublicApiMeResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"key":{"$ref":"#/components/schemas/PublicApiMeKey"}},"required":["request_id","key"]},"PublicApiErrorCode":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","rate_limited","idempotency_conflict","upstream_error","internal_error"]},"PublicApiError":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/PublicApiErrorCode"},"message":{"type":"string","description":"Human-readable error message.","example":"Invalid request body"},"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"}},"required":["code","message","request_id"]},"PublicApiErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/PublicApiError"}},"required":["error"]},"PublicApiSourcesResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"agency_source_types":{"type":"array","items":{"type":"string"},"example":["fannie_mae","fha"]},"enabled_sources":{"type":"array","items":{"type":"string"},"example":["fannie_mae","fha"]},"base_sources":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]},"tenant_source_sidebar_mode":{"type":["string","null"],"enum":["hidden","flat","grouped"],"example":"flat"},"tenant_sources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiTenantSource"}},"tenant_source_keys":{"type":"array","items":{"type":"string"},"example":["product-guides"]},"secondary_sources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSecondarySource"}},"default_tenant_source_keys":{"type":"array","items":{"type":"string"},"example":["product-guides"]},"default_shared_source_types":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]},"assigned_shared_source_types":{"type":"array","items":{"type":"string"},"example":["mortgage_guidelines"]}},"required":["request_id","agency_source_types","enabled_sources","base_sources","tenant_sources","tenant_source_keys","secondary_sources","default_tenant_source_keys","default_shared_source_types","assigned_shared_source_types"]},"PublicApiCreateConversationResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"conversation_id":{"type":"string","minLength":1,"description":"Unique conversation identifier returned by the API.","example":"conv_3c2fd2bcf41f4f12"}},"required":["request_id","conversation_id"]},"PublicApiUser":{"type":"object","properties":{"external_user_id":{"type":"string","minLength":1,"description":"Stable identifier from your system for the end user.","example":"user_123"},"email":{"type":"string","format":"email","description":"Optional email address for the external user.","example":"user@example.com"},"name":{"type":"string","description":"Optional display name for the external user.","example":"Test User"}},"required":["external_user_id"]},"PublicApiArbitraryRecord":{"type":"object","additionalProperties":{},"description":"Arbitrary metadata bag preserved by the API when possible.","example":{"external_ticket_id":"ticket_789","channel":"crm"}},"PublicApiCreateConversationRequest":{"type":"object","properties":{"title":{"type":"string","description":"Optional conversation title.","example":"FHA gift funds"},"user":{"$ref":"#/components/schemas/PublicApiUser"},"metadata":{"$ref":"#/components/schemas/PublicApiArbitraryRecord"}},"required":["user"]},"PublicApiCitation":{"type":"object","additionalProperties":{},"description":"Opaque citation payload returned by the upstream chat service.","example":{"documentId":"doc_1","excerpt":"Gift funds are generally allowed with documentation."}},"PublicApiSource":{"type":"object","additionalProperties":{},"description":"Opaque source payload returned by the upstream chat service.","example":{"url":"https://selling-guide.fanniemae.com/","title":"Fannie Mae Selling Guide"}},"PublicApiCompletionMetadata":{"type":"object","properties":{"tokens_used":{"type":"integer","minimum":0,"description":"Total tokens recorded for the completion.","example":123}},"required":["tokens_used"],"additionalProperties":{}},"PublicApiMessageResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"conversation_id":{"type":"string","minLength":1,"description":"Unique conversation identifier returned by the API.","example":"conv_3c2fd2bcf41f4f12"},"conversation_created":{"type":"boolean","description":"Present only on POST /v1/messages. Indicates whether the API created the conversation during this request.","example":true},"message_id":{"type":"string","minLength":1,"description":"Unique message identifier returned by the API.","example":"msg_1fecc99b7f334e6c"},"response":{"type":"string","example":"Gift funds are generally allowed with documentation."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiCitation"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSource"}},"metadata":{"$ref":"#/components/schemas/PublicApiCompletionMetadata"}},"required":["request_id","conversation_id","message_id","response","citations","sources","metadata"]},"PublicApiSearchOptions":{"type":"object","properties":{"agency_source_types":{"type":"array","items":{"type":"string"},"description":"Subset of agency sources to include in this request.","example":["fha","va"]},"tenant_source_keys":{"type":"array","items":{"type":"string"},"description":"Subset of tenant bucket sources to include in this request.","example":["product-guides"]},"shared_source_types":{"type":"array","items":{"type":"string"},"description":"Subset of shared source types to include in this request.","example":["mortgage_guidelines"]}}},"PublicApiConversationConfig":{"type":"object","properties":{"title":{"type":"string","description":"Optional conversation title used when the API creates a new conversation.","example":"FHA gift funds"},"metadata":{"$ref":"#/components/schemas/PublicApiArbitraryRecord"}}},"PublicApiSendMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4000,"description":"Prompt or question to send to the assistant.","example":"What documentation is required?"},"user":{"$ref":"#/components/schemas/PublicApiUser"},"stream":{"type":"boolean","description":"Set to true to receive a text/event-stream response.","example":false},"metadata":{"$ref":"#/components/schemas/PublicApiArbitraryRecord"},"search_options":{"$ref":"#/components/schemas/PublicApiSearchOptions"}},"required":["message","user"]},"PublicApiFirstMessageRequest":{"allOf":[{"$ref":"#/components/schemas/PublicApiSendMessageRequest"},{"type":"object","properties":{"conversation_id":{"type":"string","minLength":1,"description":"Existing conversation identifier. Omit this to let the API create a new conversation.","example":"conv_3c2fd2bcf41f4f12"},"conversation":{"$ref":"#/components/schemas/PublicApiConversationConfig"}}}]},"PublicApiConversationMetadata":{"type":"object","additionalProperties":{},"example":{"external_ticket_id":"ticket_789"}},"PublicApiConversation":{"type":"object","properties":{"conversation_id":{"type":"string","minLength":1,"description":"Unique conversation identifier returned by the API.","example":"conv_3c2fd2bcf41f4f12"},"title":{"type":["string","null"],"example":"FHA gift funds"},"status":{"type":["string","null"],"example":"active"},"created_at":{"type":["string","null"],"description":"Timestamp string returned by the backing data store.","example":"2025-04-19T18:20:00.000Z"},"updated_at":{"type":["string","null"],"description":"Timestamp string returned by the backing data store.","example":"2025-04-19T18:21:30.000Z"},"message_count":{"type":"integer","minimum":0,"example":2},"metadata":{"$ref":"#/components/schemas/PublicApiConversationMetadata"}},"required":["conversation_id","message_count","metadata"]},"PublicApiConversationResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"conversation":{"$ref":"#/components/schemas/PublicApiConversation"}},"required":["request_id","conversation"]},"PublicApiMessage":{"type":"object","properties":{"message_id":{"type":"string","minLength":1,"description":"Unique message identifier returned by the API.","example":"msg_1fecc99b7f334e6c"},"role":{"type":["string","null"],"example":"assistant"},"content":{"type":["string","null"],"example":"Gift funds are generally allowed with documentation."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiCitation"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiSource"}},"metadata":{"$ref":"#/components/schemas/PublicApiArbitraryRecord"},"created_at":{"type":["string","null"],"description":"Timestamp string returned by the backing data store.","example":"2025-04-19T18:21:30.000Z"}},"required":["message_id","citations","sources","metadata"]},"PublicApiConversationMessagesResponse":{"type":"object","properties":{"request_id":{"type":"string","minLength":1,"description":"Unique request identifier returned by the API.","example":"req_9b8f0b5fcb5b4eaa"},"conversation_id":{"type":"string","minLength":1,"description":"Unique conversation identifier returned by the API.","example":"conv_3c2fd2bcf41f4f12"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiMessage"}}},"required":["request_id","conversation_id","messages"]}},"parameters":{},"securitySchemes":{"PublicApiBearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Use `Authorization: Bearer mgapi_live_...`."},"PublicApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative header for the same public API key."}}},"paths":{"/v1/me":{"get":{"operationId":"getPublicApiKeyDetails","summary":"Get authenticated API key details","description":"Returns the authenticated public API key record and resolved tenant configuration.","tags":["Account"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X GET \"https://api.mortgageguidelines.com/v1/me\" \\\n  -H \"Authorization: Bearer mgapi_live_your_key_here\""},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/me\", {\n  headers: {\n    Authorization: \"Bearer mgapi_live_your_key_here\",\n  },\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"}],"responses":{"200":{"description":"Authenticated API key metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMeResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","key":{"id":"pak_test","name":"Atlantic Bay Production","status":"active","scopes":["chat:read","chat:write","sources:read"],"last_four":"test","tenant":{"clientName":"Atlantic Bay","clientOrganization":"Atlantic Bay Mortgage Group","enabledSources":["fannie_mae","fha"],"baseSources":["mortgage_guidelines"],"tenantSourceSidebarMode":"flat","tenantSources":[{"key":"product-guides","label":"Product Guides","description":"Internal product guidance","defaultOn":true}],"secondarySources":[{"type":"tenant_bucket","key":"product-guides","label":"Product Guides","defaultOn":true}],"defaultTenantSourceKeys":["product-guides"],"defaultSharedSourceTypes":["mortgage_guidelines"],"assignedSharedSourceTypes":["mortgage_guidelines"]}}}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}},"/v1/sources":{"get":{"operationId":"listAvailableSources","summary":"List the sources available to the authenticated API key","description":"Returns enabled agency sources plus tenant and shared source selections available to this API key.","tags":["Discovery"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X GET \"https://api.mortgageguidelines.com/v1/sources\" \\\n  -H \"X-API-Key: mgapi_live_your_key_here\""},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/sources\", {\n  headers: {\n    \"X-API-Key\": \"mgapi_live_your_key_here\",\n  },\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"}],"responses":{"200":{"description":"Available source configuration for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiSourcesResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","agency_source_types":["fannie_mae","fha"],"enabled_sources":["fannie_mae","fha"],"base_sources":["mortgage_guidelines"],"tenant_source_sidebar_mode":"flat","tenant_sources":[{"key":"product-guides","label":"Product Guides","description":"Internal product guidance","defaultOn":true}],"tenant_source_keys":["product-guides"],"secondary_sources":[{"type":"tenant_bucket","key":"product-guides","label":"Product Guides","defaultOn":true},{"type":"shared_source","sourceType":"mortgage_guidelines","label":"Mortgage Guidelines","defaultOn":false}],"default_tenant_source_keys":["product-guides"],"default_shared_source_types":["mortgage_guidelines"],"assigned_shared_source_types":["mortgage_guidelines"]}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}},"/v1/conversations":{"post":{"operationId":"createConversation","summary":"Create a conversation explicitly","description":"Creates a conversation before sending any assistant messages. Use this when you need a stable conversation ID up front.","tags":["Conversations"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.mortgageguidelines.com/v1/conversations\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer mgapi_live_your_key_here\" \\\n  -H \"Idempotency-Key: first-turn-user-123-001\" \\\n  -d '{\n  \"title\": \"FHA gift funds\",\n  \"user\": {\n    \"external_user_id\": \"user_123\",\n    \"email\": \"user@example.com\",\n    \"name\": \"Test User\"\n  },\n  \"metadata\": {\n    \"external_ticket_id\": \"ticket_789\"\n  }\n}'"},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/conversations\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n    Authorization: \"Bearer mgapi_live_your_key_here\",\n    \"Idempotency-Key\": \"first-turn-user-123-001\",\n  },\n  body: JSON.stringify({\n  \"title\": \"FHA gift funds\",\n  \"user\": {\n    \"external_user_id\": \"user_123\",\n    \"email\": \"user@example.com\",\n    \"name\": \"Test User\"\n  },\n  \"metadata\": {\n    \"external_ticket_id\": \"ticket_789\"\n  }\n}),\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"},{"schema":{"type":"string","example":"first-turn-user-123-001"},"required":false,"description":"Optional replay key for supported non-streaming POST requests.","name":"Idempotency-Key","in":"header"}],"requestBody":{"description":"Conversation creation payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateConversationRequest"},"example":{"title":"FHA gift funds","user":{"external_user_id":"user_123","email":"user@example.com","name":"Test User"},"metadata":{"external_ticket_id":"ticket_789"}}}}},"responses":{"201":{"description":"Conversation created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateConversationResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12"}}}},"400":{"description":"Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"409":{"description":"The supplied idempotency key conflicts with an existing request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"idempotency_conflict","message":"Idempotency key was reused with a different request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}},"/v1/messages":{"post":{"operationId":"sendFirstMessage","summary":"Send a message and optionally create the conversation","description":"Creates the conversation when `conversation_id` is omitted, sends the user message, and returns the assistant response.","tags":["Messages"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.mortgageguidelines.com/v1/messages\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer mgapi_live_your_key_here\" \\\n  -H \"Idempotency-Key: first-turn-user-123-001\" \\\n  -d '{\n  \"message\": \"What are FHA gift fund rules?\",\n  \"user\": {\n    \"external_user_id\": \"user_123\",\n    \"email\": \"user@example.com\",\n    \"name\": \"Test User\"\n  },\n  \"conversation\": {\n    \"title\": \"FHA gift funds\",\n    \"metadata\": {\n      \"external_ticket_id\": \"ticket_789\"\n    }\n  },\n  \"metadata\": {\n    \"channel\": \"crm\"\n  }\n}'"},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/messages\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n    Authorization: \"Bearer mgapi_live_your_key_here\",\n    \"Idempotency-Key\": \"first-turn-user-123-001\",\n  },\n  body: JSON.stringify({\n  \"message\": \"What are FHA gift fund rules?\",\n  \"user\": {\n    \"external_user_id\": \"user_123\",\n    \"email\": \"user@example.com\",\n    \"name\": \"Test User\"\n  },\n  \"conversation\": {\n    \"title\": \"FHA gift funds\",\n    \"metadata\": {\n      \"external_ticket_id\": \"ticket_789\"\n    }\n  },\n  \"metadata\": {\n    \"channel\": \"crm\"\n  }\n}),\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"},{"schema":{"type":"string","example":"first-turn-user-123-001"},"required":false,"description":"Optional replay key for supported non-streaming POST requests.","name":"Idempotency-Key","in":"header"}],"requestBody":{"description":"First-message payload. Supply `conversation_id` to continue an existing conversation or omit it to create one automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiFirstMessageRequest"},"example":{"message":"What are FHA gift fund rules?","user":{"external_user_id":"user_123","email":"user@example.com","name":"Test User"},"conversation":{"title":"FHA gift funds","metadata":{"external_ticket_id":"ticket_789"}},"metadata":{"channel":"crm"}}}}},"responses":{"200":{"description":"Non-streaming assistant response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMessageResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","conversation_created":true,"message_id":"msg_1fecc99b7f334e6c","response":"Gift funds are generally allowed with documentation.","citations":[{"documentId":"doc_1"}],"sources":[{"url":"https://selling-guide.fanniemae.com/","title":"Fannie Mae Selling Guide"}],"metadata":{"tokens_used":123}}},"text/event-stream":{"schema":{"type":"string","description":"Server-sent events stream.","example":"data: {\"type\":\"public_api_conversation\",\"request_id\":\"req_9b8f0b5fcb5b4eaa\",\"conversation_id\":\"conv_3c2fd2bcf41f4f12\",\"conversation_created\":true}\n\ndata: {\"type\":\"content\",\"content\":\"Gift funds are generally allowed with \"}\n\ndata: {\"type\":\"content_postprocessed\",\"content\":\"Gift funds are generally allowed with documentation.\"}\n\ndata: {\"type\":\"complete\",\"metadata\":{\"tokensUsed\":123}}\n\ndata: {\"type\":\"public_api_complete\",\"request_id\":\"req_9b8f0b5fcb5b4eaa\",\"conversation_id\":\"conv_3c2fd2bcf41f4f12\",\"message_id\":\"msg_1fecc99b7f334e6c\"}\n"}}}},"400":{"description":"Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"404":{"description":"The requested conversation was not found for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"409":{"description":"The supplied idempotency key conflicts with an existing request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"idempotency_conflict","message":"Idempotency key was reused with a different request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"502":{"description":"The upstream chat service failed or returned an unexpected response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"upstream_error","message":"Chat service stream failed","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}},"/v1/conversations/{conversationId}":{"get":{"operationId":"getConversation","summary":"Get a conversation","description":"Returns the conversation metadata for a conversation owned by the authenticated API key.","tags":["Conversations"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X GET \"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12\" \\\n  -H \"Authorization: Bearer mgapi_live_your_key_here\""},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12\", {\n  headers: {\n    Authorization: \"Bearer mgapi_live_your_key_here\",\n  },\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","minLength":1,"example":"conv_3c2fd2bcf41f4f12"},"required":true,"description":"Conversation identifier returned by the API.","name":"conversationId","in":"path"},{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"}],"responses":{"200":{"description":"Conversation record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiConversationResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","conversation":{"conversation_id":"conv_3c2fd2bcf41f4f12","title":"FHA gift funds","status":"active","created_at":"2025-04-19T18:20:00.000Z","updated_at":"2025-04-19T18:21:30.000Z","message_count":2,"metadata":{"external_ticket_id":"ticket_789"}}}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"404":{"description":"The requested conversation was not found for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}},"/v1/conversations/{conversationId}/messages":{"get":{"operationId":"listConversationMessages","summary":"List messages in a conversation","description":"Returns the stored messages for a conversation owned by the authenticated API key.","tags":["Conversations"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X GET \"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages\" \\\n  -H \"Authorization: Bearer mgapi_live_your_key_here\""},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages\", {\n  headers: {\n    Authorization: \"Bearer mgapi_live_your_key_here\",\n  },\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","minLength":1,"example":"conv_3c2fd2bcf41f4f12"},"required":true,"description":"Conversation identifier returned by the API.","name":"conversationId","in":"path"},{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"}],"responses":{"200":{"description":"Conversation messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiConversationMessagesResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","messages":[{"message_id":"msg_user_123","role":"user","content":"What are FHA gift fund rules?","citations":[],"sources":[],"metadata":{"channel":"crm"},"created_at":"2025-04-19T18:20:00.000Z"},{"message_id":"msg_1fecc99b7f334e6c","role":"assistant","content":"Gift funds are generally allowed with documentation.","citations":[{"documentId":"doc_1"}],"sources":[{"url":"https://selling-guide.fanniemae.com/","title":"Fannie Mae Selling Guide"}],"metadata":{"tokens_used":123},"created_at":"2025-04-19T18:21:30.000Z"}]}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"404":{"description":"The requested conversation was not found for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}},"post":{"operationId":"sendConversationMessage","summary":"Send a message to an existing conversation","description":"Sends a user message to an existing conversation and returns the assistant response.","tags":["Messages"],"security":[{"PublicApiBearer":[]},{"PublicApiKeyHeader":[]}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: mgapi_live_your_key_here\" \\\n  -H \"Idempotency-Key: follow-up-user-123-001\" \\\n  -d '{\n  \"message\": \"What documentation is required?\",\n  \"user\": {\n    \"external_user_id\": \"user_123\"\n  }\n}'"},{"lang":"ts","label":"TypeScript fetch","source":"const response = await fetch(\"https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n    \"X-API-Key\": \"mgapi_live_your_key_here\",\n    \"Idempotency-Key\": \"follow-up-user-123-001\",\n  },\n  body: JSON.stringify({\n    message: \"What documentation is required?\",\n    user: {\n      external_user_id: \"user_123\",\n    },\n  }),\n});\n\nconst data = await response.json();"}],"parameters":[{"schema":{"type":"string","minLength":1,"example":"conv_3c2fd2bcf41f4f12"},"required":true,"description":"Conversation identifier returned by the API.","name":"conversationId","in":"path"},{"schema":{"type":"string","example":"Bearer mgapi_live_1234567890abcdef"},"required":false,"description":"Bearer auth header in the format `Bearer mgapi_live_...`.","name":"Authorization","in":"header"},{"schema":{"type":"string","example":"mgapi_live_1234567890abcdef"},"required":false,"description":"Alternative API key header.","name":"X-API-Key","in":"header"},{"schema":{"type":"string","example":"first-turn-user-123-001"},"required":false,"description":"Optional replay key for supported non-streaming POST requests.","name":"Idempotency-Key","in":"header"}],"requestBody":{"description":"Message payload for an existing conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiSendMessageRequest"},"example":{"conversation_id":"conv_3c2fd2bcf41f4f12","message":"What documentation is required?","user":{"external_user_id":"user_123"}}}}},"responses":{"200":{"description":"Non-streaming assistant response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiMessageResponse"},"example":{"request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c","response":"Gift funds are generally allowed with documentation.","citations":[{"documentId":"doc_1"}],"sources":[{"url":"https://selling-guide.fanniemae.com/","title":"Fannie Mae Selling Guide"}],"metadata":{"tokens_used":123}}},"text/event-stream":{"schema":{"type":"string","description":"Server-sent events stream.","example":"data: {\"type\":\"content\",\"content\":\"The conversation can continue using the existing ID.\"}\n\ndata: {\"type\":\"complete\",\"metadata\":{\"tokensUsed\":88}}\n\ndata: {\"type\":\"public_api_complete\",\"request_id\":\"req_9b8f0b5fcb5b4eaa\",\"conversation_id\":\"conv_3c2fd2bcf41f4f12\",\"message_id\":\"msg_1fecc99b7f334e6c\"}\n"}}}},"400":{"description":"Invalid request body, invalid source selection, or unsupported streaming/idempotency combination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"401":{"description":"Missing, invalid, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"403":{"description":"The API key does not include the required scope for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"404":{"description":"The requested conversation was not found for the authenticated API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"409":{"description":"The supplied idempotency key conflicts with an existing request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"idempotency_conflict","message":"Idempotency key was reused with a different request body","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"429":{"description":"The API key exceeded one of its configured rate limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"rate_limited","message":"API key rate limit exceeded","request_id":"req_9b8f0b5fcb5b4eaa"}}}}},"502":{"description":"The upstream chat service failed or returned an unexpected response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"},"example":{"error":{"code":"upstream_error","message":"Chat service stream failed","request_id":"req_9b8f0b5fcb5b4eaa"}}}}}}}}},"webhooks":{}}