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

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