API Reference | MortgageGuidelines API Docs

Generated reference

This page is generated from the shared route contract used by the API service and the downloadable OpenAPI document.

Account

1 endpoint

get/v1/me

Get authenticated API key details

Returns the authenticated public API key record and resolved tenant configuration.

curl -X GET "https://api.mortgageguidelines.com/v1/me" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

const response = await fetch("https://api.mortgageguidelines.com/v1/me", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();

{
  "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"
      ]
    }
  }
}

Discovery

1 endpoint

get/v1/sources

List the sources available to the authenticated API key

Returns enabled agency sources plus tenant and shared source selections available to this API key.

curl -X GET "https://api.mortgageguidelines.com/v1/sources" \
  -H "X-API-Key: mgapi_live_your_key_here"

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

const data = await response.json();

{
  "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"
  ]
}

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 -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"
  }
}'

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();

{
  "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 -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

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();

{
  "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 -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Authorization: Bearer mgapi_live_your_key_here"

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();

{
  "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"
    }
  ]
}

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 upstream token events, and then `public_api_complete`.

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"
  }
}'

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();

{
  "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
  }
}

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":{"tokensUsed":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`.

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"
  }
}'

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();

{
  "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
  }
}

data: {"type":"content","content":"The conversation can continue using the existing ID."}

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

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