MortgageGuidelines API

API Reference

Generated endpoint reference backed by the shared route contract.

Public responses include customer-facing identifiers, answer text, sanitized citations, sanitized source summaries, and metadata.tokens_used. Model names, provider details, prompt context, retrieval diagnostics, and internal service configuration are intentionally excluded.

Account

1 endpoint

get/v1/me

Get authenticated API key details

Returns the authenticated public API key summary and client identity.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/me" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/me", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "key": {
    "id": "pak_test",
    "name": "Example Lending Production",
    "status": "active",
    "scopes": [
      "chat:read",
      "chat:write",
      "sources:read"
    ],
    "last_four": "test",
    "client": {
      "name": "Example Lending",
      "organization": "Example Lending Group"
    }
  }
}

Discovery

1 endpoint

get/v1/sources

List the sources available to the authenticated API key

Returns selectable agency, tenant, and shared sources available to this API key.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/sources" \
  -H "X-API-Key: mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/sources", {
  headers: {
    "X-API-Key": "mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "agency_source_types": [
    "fannie_mae",
    "fha"
  ],
  "tenant_source_keys": [
    "product-guides"
  ],
  "tenant_sources": [
    {
      "key": "product-guides",
      "label": "Product Guides",
      "description": "Internal product guidance",
      "defaultOn": true
    }
  ],
  "default_tenant_source_keys": [
    "product-guides"
  ],
  "shared_source_types": [
    "mortgage_guidelines"
  ],
  "shared_sources": [
    {
      "sourceType": "mortgage_guidelines",
      "label": "Mortgage Guidelines",
      "defaultOn": true
    }
  ],
  "default_shared_source_types": [
    "mortgage_guidelines"
  ]
}

Conversations

3 endpoints

post/v1/conversations

Create a conversation explicitly

Creates a conversation before sending any assistant messages. Use this when you need a stable conversation ID up front.

Idempotency

  • `Idempotency-Key` is supported for non-streaming POST requests so that safe retries return the original completed response.
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/conversations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12"
}
get/v1/conversations/{conversationId}

Get a conversation

Returns the conversation metadata for a conversation owned by the authenticated API key.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "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"
    }
  }
}
get/v1/conversations/{conversationId}/messages

List messages in a conversation

Returns the stored messages for a conversation owned by the authenticated API key.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "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": [
        {
          "documentTitle": "Fannie Mae Selling Guide",
          "section": "B3-4.3-04",
          "url": "https://selling-guide.fanniemae.com/",
          "pageNumber": 12
        }
      ],
      "sources": [
        {
          "url": "https://selling-guide.fanniemae.com/",
          "title": "Fannie Mae Selling Guide",
          "description": "Document from selling-guide.fanniemae.com",
          "citationCount": 1
        }
      ],
      "metadata": {
        "tokens_used": 123
      },
      "created_at": "2025-04-19T18:21:30.000Z"
    }
  ]
}

Messages

2 endpoints

post/v1/messages

Send a message and optionally create the conversation

Creates the conversation when `conversation_id` is omitted, sends the user message, and returns the assistant response.

Idempotency

  • `Idempotency-Key` is supported only for non-streaming requests.
  • Reusing the same key with a different request body returns `409 idempotency_conflict`.

Streaming

  • When `stream: true`, the response content type becomes `text/event-stream`.
  • The first event is `public_api_conversation`, followed by sanitized token, citation, source, and completion events, and then `public_api_complete`.
  • Streaming metadata contains only `tokens_used`.
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "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"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "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"
  }
}),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "conversation_created": true,
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
Streaming example
data: {"type":"public_api_conversation","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","conversation_created":true}

data: {"type":"content","content":"Gift funds are generally allowed with "}

data: {"type":"content_postprocessed","content":"Gift funds are generally allowed with documentation."}

data: {"type":"complete","metadata":{"tokens_used":123}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}
post/v1/conversations/{conversationId}/messages

Send a message to an existing conversation

Sends a user message to an existing conversation and returns the assistant response.

Idempotency

  • `Idempotency-Key` is supported only for non-streaming requests.
  • Matching retries replay the stored JSON response snapshot.

Streaming

  • When `stream: true`, the response content type becomes `text/event-stream`.
  • Existing-conversation streams omit the leading `public_api_conversation` event and always finish with `public_api_complete`.
  • Streaming metadata contains only `tokens_used`.
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mgapi_live_your_key_here" \
  -H "Idempotency-Key: follow-up-user-123-001" \
  -d '{
  "message": "What documentation is required?",
  "user": {
    "external_user_id": "user_123"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "mgapi_live_your_key_here",
    "Idempotency-Key": "follow-up-user-123-001",
  },
  body: JSON.stringify({
    message: "What documentation is required?",
    user: {
      external_user_id: "user_123",
    },
  }),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
Streaming example
data: {"type":"content","content":"The conversation can continue using the existing ID."}

data: {"type":"complete","metadata":{"tokens_used":88}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}