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:

company_name

string

required

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

ticker

string

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

analysis_type

string

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

deal_id

integer

Optional deal ID to link analysis results to a deal

stream

boolean

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

Response:

status

string

Response status: "success" or "error"

analysis_id

string

Unique analysis ID for retrieving results

result

object

Analysis results including:

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

cdm_events

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:

query

string

required

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

time_range

string

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

deal_id

integer

Optional deal ID to link analysis results to a deal

stream

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:

borrower_name

string

required

Borrower company name

loan_amount

number

required

Loan amount in USD

loan_type

string

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

deal_id

integer

Optional deal ID to link analysis results to a deal

stream

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:

analysis_id

string

required

Analysis ID returned from analysis endpoint

Response:

status

string

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

result

object

Full analysis results (same as analysis endpoint response)

created_at

string

ISO 8601 timestamp of analysis creation

completed_at

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:

query

string

required

Research query/question

deal_id

integer

Optional deal ID to link research results to a deal

max_iterations

integer

Maximum number of research iterations. Default: 5

Response:

status

string

Response status: "success" or "error"

research_id

string

Unique research ID for retrieving results

message

string

Status message

cdm_events

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:

research_id

string

required

Research ID returned from query endpoint

Response:

status

string

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

answer

string

Comprehensive research answer

knowledge_items

array

Array of knowledge items with:

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

sources

array

Array of source URLs and metadata

statistics

object

Research statistics:

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

created_at

string

ISO 8601 timestamp of research creation

completed_at

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:

workflow_type

string

required

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

session_id

string

required

Chatbot session ID

workflow_params

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

deal_id

integer

Optional deal ID to link workflow results to a deal

Response:

status

string

Response status: "success" or "error"

workflow_type

string

Workflow type that was launched

message

string

Status message

workflow_result

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

cdm_events

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:

message

string

required

User message (can include workflow launch requests)

session_id

string

required

Chatbot session ID

deal_id

integer

Optional deal ID for context

document_id

integer

Optional document ID for context

conversation_history

array

Previous conversation messages (last 10 messages)

document_context

object

Document context (extracted CDM data)

Response:

status

string

Response status: "success" or "error"

response

string

Chatbot response message

workflow_launched

string

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

workflow_result

object

Workflow result object (if workflow was launched)

cdm_events

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:

status

string

Error status: "error"

message

string

Error message describing what went wrong

detail

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