Agent Workflows API

Overview

CreditNexus provides comprehensive API endpoints for three AI agent workflows:

LangAlpha: Quantitative financial analysis with multi-agent orchestration
DeepResearch: Iterative web research with knowledge accumulation
PeopleHub: Business intelligence and psychometric analysis

All endpoints require authentication via JWT token in the Authorization header.

LangAlpha: Quantitative Analysis

Analyze Company

Perform comprehensive quantitative analysis of a company.

POST /api/quantitative-analysis/company
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "company_name": "Apple Inc.",
  "ticker": "AAPL",
  "analysis_type": "comprehensive",
  "deal_id": 123,
  "stream": false
}

Request Body:

string

required

Company name (e.g., “Apple Inc.”)

string

Stock ticker symbol (e.g., “AAPL”). Optional if company_name is provided.

string

Analysis type: "comprehensive", "financial", "market", or "risk". Default: "comprehensive"

integer

Optional deal ID to link analysis results to a deal

boolean

Enable Server-Sent Events (SSE) for real-time progress updates. Default: false

Response:

string

Response status: "success" or "error"

string

Unique analysis ID for retrieving results

object

Analysis results including:

summary: Executive summary
findings: Key findings
metrics: Financial metrics and ratios
data: Raw analysis data

array

Array of FINOS CDM-compliant events generated during analysis

Streaming Response (when stream=true): Server-Sent Events with the following event types:

started: Analysis has begun

{"type": "started", "data": {"analysis_id": "analysis_123", "message": "Analysis started"}}

progress: Progress update

{"type": "progress", "data": {"step": "Fetching market data", "progress": 25, "message": "25% complete"}}

completed: Analysis completed

{"type": "completed", "data": {"analysis_id": "analysis_123", "result": {...}}}

Code Reference: app/api/routes.py (line ~1169), app/services/quantitative_analysis_service.py

Analyze Market

Perform market analysis for sectors, trends, or economic indicators.

POST /api/quantitative-analysis/market
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "query": "Technology sector Q4 2024 performance",
  "time_range": "3M",
  "deal_id": 123,
  "stream": false
}

Request Body:

string

required

Market analysis query (e.g., “Technology sector trends”, “S&P 500 performance”)

string

Time range for analysis: "1M", "3M", "6M", "1Y", or "5Y". Default: "3M"

integer

Optional deal ID to link analysis results to a deal

boolean

Enable Server-Sent Events (SSE) for real-time progress updates. Default: false

Response: Same structure as company analysis response. Code Reference: app/api/routes.py (line ~1310), app/services/quantitative_analysis_service.py

Analyze Loan Application

Evaluate loan applications with quantitative metrics.

POST /api/quantitative-analysis/loan-application
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "borrower_name": "Acme Corp",
  "loan_amount": 1000000,
  "loan_type": "term_loan",
  "deal_id": 123,
  "stream": false
}

Request Body:

string

required

Borrower company name

number

required

Loan amount in USD

string

Loan type: "term_loan", "revolving", "bridge", or "other". Default: "term_loan"

integer

Optional deal ID to link analysis results to a deal

boolean

Enable Server-Sent Events (SSE) for real-time progress updates. Default: false

Response: Same structure as company analysis response. Code Reference: app/api/routes.py (line ~1361), app/services/quantitative_analysis_service.py

Get Analysis Results

Retrieve completed analysis results by analysis ID.

GET /api/quantitative-analysis/results/{analysis_id}
Authorization: Bearer {jwt_token}

Path Parameters:

string

required

Analysis ID returned from analysis endpoint

Response:

string

Analysis status: "pending", "running", "completed", or "failed"

object

Full analysis results (same as analysis endpoint response)

string

ISO 8601 timestamp of analysis creation

string

ISO 8601 timestamp of analysis completion (if completed)

Code Reference: app/api/routes.py (line ~1489), app/services/quantitative_analysis_service.py

DeepResearch: Iterative Web Research

Submit Research Query

Submit a research query for iterative web research.

POST /api/deep-research/query
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "query": "What are the latest developments in sustainable finance regulations?",
  "deal_id": 123,
  "max_iterations": 5
}

Request Body:

string

required

Research query/question

integer

Optional deal ID to link research results to a deal

integer

Maximum number of research iterations. Default: 5

Response:

string

Response status: "success" or "error"

string

Unique research ID for retrieving results

string

Status message

array

Array of FINOS CDM-compliant events generated during research

Code Reference: app/api/routes.py (line ~708), app/services/deep_research_service.py

Get Research Results

Retrieve completed research results by research ID.

GET /api/deep-research/results/{research_id}
Authorization: Bearer {jwt_token}

Path Parameters:

string

required

Research ID returned from query endpoint

Response:

string

Research status: "pending", "running", "completed", or "failed"

string

Comprehensive research answer

array

Array of knowledge items with:

title: Knowledge item title
content: Knowledge item content
sources: Array of source citations

array

Array of source URLs and metadata

object

Research statistics:

sources_used: Number of sources consulted
iterations: Number of research iterations
time_taken_seconds: Research duration

string

ISO 8601 timestamp of research creation

string

ISO 8601 timestamp of research completion (if completed)

Code Reference: app/api/routes.py (line ~793), app/services/deep_research_service.py

PeopleHub: Business Intelligence

Launch PeopleHub Workflow

Launch a PeopleHub research workflow via the digitizer chatbot API.

POST /api/digitizer-chatbot/launch-workflow
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "workflow_type": "peoplehub",
  "session_id": "chatbot-session-123",
  "workflow_params": {
    "person_name": "John Doe"
  },
  "deal_id": 123
}

Request Body:

string

required

Workflow type: "peoplehub", "deepresearch", or "langalpha"

string

required

Chatbot session ID

object

required

Workflow-specific parameters:

For peoplehub: {"person_name": "John Doe"}
For deepresearch: {"query": "research query"}
For langalpha: {"analysis_type": "company", "company_name": "Apple Inc."}

integer

Optional deal ID to link workflow results to a deal

Response:

string

Response status: "success" or "error"

string

Workflow type that was launched

string

Status message

object

Workflow result object with:

For peoplehub: Psychometric profile, research summary, credit assessment
For deepresearch: Research ID and status
For langalpha: Analysis ID and status

array

Array of FINOS CDM-compliant events generated during workflow

Code Reference: app/api/routes.py (line ~3903), app/services/digitizer_chatbot_service.py

Chatbot Integration

Chat with Digitizer Chatbot

Send a message to the digitizer chatbot, which can automatically launch agent workflows.

POST /api/digitizer-chatbot/chat
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "message": "Analyze Apple Inc. financials",
  "session_id": "chatbot-session-123",
  "deal_id": 123,
  "document_id": 456,
  "conversation_history": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi! How can I help?"}
  ],
  "document_context": {
    "borrower": "Apple Inc.",
    "loan_amount": 1000000
  }
}

Request Body:

string

required

User message (can include workflow launch requests)

string

required

Chatbot session ID

integer

Optional deal ID for context

integer

Optional document ID for context

array

Previous conversation messages (last 10 messages)

object

Document context (extracted CDM data)

Response:

string

Response status: "success" or "error"

string

Chatbot response message

string

Workflow type that was launched (if any): "langalpha", "deepresearch", or "peoplehub"

object

Workflow result object (if workflow was launched)

array

Array of FINOS CDM-compliant events

Code Reference: app/api/routes.py (line ~3835), app/services/digitizer_chatbot_service.py

Error Responses

All endpoints return standard error responses:

string

Error status: "error"

string

Error message describing what went wrong

object

Additional error details (if available)

Common Error Codes:

400 Bad Request: Invalid request parameters
401 Unauthorized: Missing or invalid JWT token
403 Forbidden: Insufficient permissions
404 Not Found: Analysis/research ID not found
500 Internal Server Error: Server error during processing

Rate Limiting

All agent workflow endpoints are rate-limited:

Default: 60 requests per minute per user
Streaming endpoints: Same rate limit applies
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Authentication

All endpoints require JWT authentication:

Login to get JWT token: POST /api/auth/login
Include token in Authorization header: Authorization: Bearer {jwt_token}
Token expiration: Tokens expire after configured TTL (default: 24 hours)

Code Reference: app/auth/jwt_auth.py

Next Steps

Agent Workflows Feature Documentation - Complete feature overview
Configuration Guide - Setup instructions
Agent Tools Documentation - Available tools and capabilities

Last Updated: 2025-01-14
API Version: 1.0

Market Opportunity

Get Started

Compliance

Roadmap

Architecture

Features

API Reference

Guides

Specifications

Legal

Overview

LangAlpha: Quantitative Analysis

Analyze Company

Analyze Market

Analyze Loan Application

Get Analysis Results

DeepResearch: Iterative Web Research

Submit Research Query

Get Research Results

PeopleHub: Business Intelligence

Launch PeopleHub Workflow

Chatbot Integration

Chat with Digitizer Chatbot

Error Responses

Rate Limiting

Authentication

Next Steps

​Overview

​LangAlpha: Quantitative Analysis

​Analyze Company

​Analyze Market

​Analyze Loan Application

​Get Analysis Results

​DeepResearch: Iterative Web Research

​Submit Research Query

​Get Research Results

​PeopleHub: Business Intelligence

​Launch PeopleHub Workflow

​Chatbot Integration

​Chat with Digitizer Chatbot

​Error Responses

​Rate Limiting

​Authentication

​Next Steps

Overview

LangAlpha: Quantitative Analysis

Analyze Company

Analyze Market

Analyze Loan Application

Get Analysis Results

DeepResearch: Iterative Web Research

Submit Research Query

Get Research Results

PeopleHub: Business Intelligence

Launch PeopleHub Workflow

Chatbot Integration

Chat with Digitizer Chatbot

Error Responses

Rate Limiting

Authentication

Next Steps