API Endpoints

All endpoints require the x-api-key header. See Authentication.

Deals

List Deals

GET /deals

Returns a paginated list of your deals, ordered by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Number of deals to return (max 100)
`nextToken`	string	—	Pagination token from a previous response

Response

{
  "items": [
    {
      "dealId": "abc-123",
      "userId": "user-uuid",
      "companyName": "Acme Corp",
      "symbol": "ACME",
      "country": "United States",
      "status": "researching",
      "positionType": "long",
      "description": "Potential acquisition target",
      "investmentThesis": "Strong fundamentals with upcoming catalyst...",
      "targetPrice": 150,
      "currentPrice": 120,
      "notes": "Monitoring for Q3 earnings",
      "riskAssessment": "Moderate — pending regulatory approval",
      "documents": [],
      "relatedFilingIds": ["filing-abc"],
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T10:00:00Z"
    }
  ],
  "nextToken": null
}

Deal Object Fields

Field	Type	Description
`dealId`	string	Auto-generated UUID (read-only)
`userId`	string	Owner's user ID (read-only)
`companyName`	string	Company name
`symbol`	string	Ticker symbol (e.g., `"AAPL"`, `"8934.T"`)
`country`	string	Country name (defaults to `"United States"`)
`status`	string	One of: `researching`, `active`, `monitoring`, `closed`
`positionType`	string	Position direction: `long` or `short`
`description`	string	Deal description or notes
`investmentThesis`	string	Investment thesis
`targetPrice`	number	Target price
`currentPrice`	number	Current market price
`currentPriceDate`	string	Timestamp of last price update (read-only)
`notes`	string	Free-form notes
`riskAssessment`	string	Risk assessment
`documents`	array	Associated documents (read-only)
`relatedFilingIds`	array	Linked filing IDs
`createdAt`	string	ISO 8601 timestamp (read-only)
`updatedAt`	string	ISO 8601 timestamp (read-only)

Example

# List first 10 deals
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals?limit=10" | jq

Get a Deal

GET /deals/{dealId}

Returns a single deal by ID. You can only access deals you own.

Response

Returns a single deal object.

Errors

403 — Deal exists but you don't own it
404 — Deal not found

Example

curl -s -H "x-api-key: sa_your_key" \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals/abc-123 | jq

Create a Deal

POST /deals

Creates a new deal. The deal is automatically associated with your user account.

Request Body

{
  "companyName": "Acme Corp",
  "status": "researching",
  "symbol": "ACME",
  "description": "Potential acquisition target",
  "investmentThesis": "Strong fundamentals with upcoming catalyst...",
  "positionType": "long",
  "targetPrice": 150,
  "currentPrice": 120
}

Required Fields

Field	Type	Description
`companyName`	string	Company name
`status`	string	One of: `researching`, `active`, `monitoring`, `closed`

Optional Fields

Field	Type	Description
`description`	string	Deal description or notes
`symbol`	string	Ticker symbol (e.g., `"AAPL"`, `"8934.T"`)
`country`	string	Country name (defaults to `"United States"`)
`positionType`	string	Position direction: `long` or `short`
`investmentThesis`	string	Investment thesis
`targetPrice`	number	Target price
`currentPrice`	number	Current market price
`notes`	string	Free-form notes
`riskAssessment`	string	Risk assessment
`relatedFilingIds`	array	Linked filing IDs (e.g., `["filing-abc"]`)

Response (201 Created)

Returns the created deal object with auto-generated dealId, userId, createdAt, and updatedAt.

Example

curl -s -X POST \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "Acme Corp", "status": "researching", "symbol": "ACME"}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals | jq

Update a Deal

PUT /deals/{dealId}

Updates an existing deal. You can only update deals you own. Only include the fields you want to change.

Request Body

Only include the fields you want to change.

{
  "status": "active",
  "description": "Moving to active phase",
  "targetPrice": 175,
  "positionType": "long"
}

Updatable Fields

Field	Type	Description
`companyName`	string	Company name
`symbol`	string	Ticker symbol
`country`	string	Country name
`status`	string	One of: `researching`, `active`, `monitoring`, `closed`
`positionType`	string	Position direction: `long` or `short`
`description`	string	Deal description or notes
`investmentThesis`	string	Investment thesis
`targetPrice`	number	Target price
`currentPrice`	number	Current market price
`notes`	string	Free-form notes
`riskAssessment`	string	Risk assessment
`relatedFilingIds`	array	Linked filing IDs

Response

Returns the updated deal object.

Errors

404 — Deal not found or you don't own it

Example

curl -s -X PUT \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals/abc-123 | jq

Email a Deal

POST /deals/{dealId}/email

Sends an HTML-formatted deal summary email to the specified recipient via Mailgun. You can only email deals you own.

Request Body

{
  "to": "recipient@example.com",
  "subject": "Deal Summary: Acme Corp",
  "message": "Take a look at this deal"
}

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`subject`	string	No	Email subject (defaults to `"Deal Summary: {companyName}"`)
`message`	string	No	Optional message included above the deal summary (max 5000 chars)

Response

{
  "success": true,
  "message": "Email sent to recipient@example.com"
}

Errors

400 — Missing or invalid to email address
403 — Deal exists but you don't own it
404 — Deal not found
502 — Email delivery failed

Example

curl -s -X POST \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"to": "colleague@example.com", "message": "Check out this opportunity"}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals/abc-123/email | jq

Deal Activities

Log chronological events and to-do reminders on deals.

List Activities

GET /deals/{dealId}/activities

Returns activities for a deal, ordered newest first.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Number of activities to return (max 100)
`nextToken`	string	—	Pagination token from a previous response

Response

{
  "items": [
    {
      "activityId": "a1b2c3d4-...",
      "dealId": "deal-123",
      "userId": "user-456",
      "type": "task",
      "content": "Follow up with management team",
      "dueDate": "2026-03-01",
      "completed": false,
      "completedAt": null,
      "createdAt": "2026-02-25T10:00:00.000Z",
      "updatedAt": "2026-02-25T10:00:00.000Z"
    }
  ],
  "nextToken": null
}

Create Activity

POST /deals/{dealId}/activities

Request Body

Field	Type	Required	Description
`type`	string	Yes	`"note"` or `"task"`
`content`	string	Yes	Activity description (max 5000 chars)
`dueDate`	string	No	ISO date for tasks (e.g., `"2026-03-01"`)

Example

curl -X POST \
  -H "x-api-key: sa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "task", "content": "Review Q4 earnings", "dueDate": "2026-03-15"}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals/deal-123/activities | jq

Returns 201 with the created activity object.

Update Activity

PUT /deals/{dealId}/activities/{activityId}

Request Body

Field	Type	Description
`content`	string	Updated description
`dueDate`	string	Updated due date
`completed`	boolean	Mark as complete/incomplete

When completed is set to true, completedAt is automatically set to the current timestamp.

Example — Mark as Complete

curl -X PUT \
  -H "x-api-key: sa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"completed": true}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/deals/deal-123/activities/act-456 | jq

Delete Activity

DELETE /deals/{dealId}/activities/{activityId}

Returns 204 on success.

Filings

Access to SEC 8-K filings, Form 4 insider purchases, and Japan filings. Supports read operations (list, get) and write operations (archive, favorite).

Common Query Parameters

All filing list endpoints support these query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Number of filings to return (max 500)
`nextToken`	string	—	Pagination token from a previous response
`searchTerm`	string	—	Text search (fields vary by filing type — see below)
`filingDate`	string	—	Return filings for a single date (`YYYY-MM-DD`). Overrides `startDate`/`endDate`.
`startDate`	string	30 days ago	Start of date range (`YYYY-MM-DD`). Alias for `createdAfter`.
`endDate`	string	today	End of date range (`YYYY-MM-DD`). Alias for `createdBefore`.
`createdAfter`	string	30 days ago	Start date filter (`YYYY-MM-DD`). Same as `startDate`.
`createdBefore`	string	today	End date filter (`YYYY-MM-DD`). Same as `endDate`.
`category`	string	—	Filter by monitor group category (see below)
`groupId`	string	—	Filter by monitor group ID (resolves to category)

Search Fields by Filing Type

Filing Type	Fields Searched
SEC	`companyName`, `analysis`, `description`, `title`
Form 4	`issuerName`, `ownerName`, `issuerTicker`
Japan	`companyName`, `companyNameEnglish`, `documentTitle`, `documentTitleEnglish`, `aiSummary`

Date Filtering

Use filingDate to pull filings for a single day — ideal for daily reviews. Use startDate/endDate for a range (e.g., a weekly review of Monday through Friday). If no date params are provided, defaults to the last 30 days.

Category Filtering

Use the category or groupId parameter to filter filings by monitor group. This combines form type and AI tag filtering automatically — ideal for agents monitoring specific event types.

When category is set on SEC filings, it overrides the standalone formType parameter. On Form 4 filings, categories without includeForm4 return an empty result.

Supported Categories

Category	SEC Form Types	AI Tags	Form 4
`spinoffs`	10-12B, 10-12B/A	Spin-off, Distribution	No
`insider_activity`	—	—	Yes
`buybacks`	SC 14D-1	Share Buyback	No
`corporate_events`	—	Leadership Change, Stock Split, Reverse Stock Split, Listing Change	No
`ipos`	S-1, S-1/A, 424B4	IPO	No
`distressed`	—	Bankruptcy	No
`spacs`	S-4, S-4/A	SPAC	No
`activism`	SC 13D, SC 13D/A, DFAN14A	—	No
`ma`	DEFM14A, PREM14A, SC 14D9	Merger Announcement, Acquisition Announcement	No
`privatizations`	SC 13E-3, SC 13E-3/A	Take Private	No
`oddlot_tenders`	SC TO-I, SC TO-I/A	Odd-Lot Tender	No
`other`	—	CVR	No

Example Group IDs

You can also use groupId instead of category. Common group IDs: announced-spinoffs, cluster-insider-buying, share-buybacks, corporate-restructuring, upcoming-ipos, activist-positions, pending-mergers, going-private, odd-lot-tenders.

List SEC Filings

GET /filings/sec

Returns SEC filings in reverse chronological order. Supports multiple form types including 8-K, 10-12B, S-1, SC 13D, DEFM14A, and more.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of filings to return (max 500)
`nextToken`	string	—	Pagination token from a previous response
`searchTerm`	string	—	Search across company name, title, description, and analysis
`formType`	string	—	Filter by SEC form type (e.g. `8-K`, `10-12B`, `SC 13D`, `S-1`, `DEFM14A`)
`createdAfter`	string	30 days ago	Start date filter (YYYY-MM-DD)
`createdBefore`	string	today	End date filter (YYYY-MM-DD)

Supported Form Types: 8-K, 10-12B, 10-12B/A, S-1, S-1/A, 424B4, SC 13D, SC 13D/A, DEFM14A, DFAN14A, SC 13E-3, SC 13E-3/A, PREM14A, SC 14D9, SC 14D-1, SC 14D-1/A, SC TO-I, SC TO-I/A, S-4, S-4/A

Response

{
  "items": [
    {
      "filingId": "abc-123",
      "companyName": "Acme Corp",
      "formType": "8-K",
      "filedDate": "2026-02-20",
      "description": "Entry into a Material Agreement",
      "txtUrl": "https://www.sec.gov/Archives/...",
      "htmlUrl": "https://www.sec.gov/Archives/...",
      "analysis": "AI-generated analysis of the filing...",
      "analysisDate": "2026-02-20T12:00:00Z",
      "status": "analyzed",
      "createdAt": "2026-02-20T10:00:00Z",
      "aiTags": [{ "name": "M&A", "color": "blue-500" }]
    }
  ],
  "nextToken": null
}

Example

# List recent SEC filings
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?limit=10" | jq

# Get filings for a single date
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?filingDate=2026-02-24" | jq

# Get filings for a date range (e.g., weekly review)
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?startDate=2026-02-20&endDate=2026-02-25" | jq

# Search for a company
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?searchTerm=Apple" | jq

# Filter by form type (e.g. spin-off registration statements)
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?formType=10-12B" | jq

# Get all spin-off filings from the past week
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?category=spinoffs&startDate=2026-02-18" | jq

# Get activist filings using groupId
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec?groupId=activist-positions" | jq

Get a SEC Filing

GET /filings/sec/{filingId}

Returns a single SEC filing by ID.

Example

curl -s -H "x-api-key: sa_your_key" \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec/abc-123 | jq

List Form 4 Filings (Insider Purchases)

GET /filings/form4

Returns Form 4 insider purchase filings in reverse chronological order.

Response

{
  "items": [
    {
      "filingId": "f4-123",
      "issuerName": "Acme Corp",
      "issuerTicker": "ACME",
      "ownerName": "Jane Smith",
      "ownerTitle": "CEO",
      "isOfficer": true,
      "isDirector": false,
      "transactionType": "Purchase",
      "transactionDate": "2026-02-19",
      "sharesTransacted": 10000,
      "pricePerShare": 25.50,
      "totalValue": 255000,
      "sharesOwnedAfter": 50000,
      "filingDate": "2026-02-20",
      "htmlUrl": "https://www.sec.gov/cgi-bin/...",
      "analysis": "Significant insider purchase...",
      "analysisDate": "2026-02-20T12:00:00Z",
      "priceAtDiscovery": 24.80,
      "priceAtDiscoveryDate": "2026-02-20T10:00:00Z",
      "status": "analyzed",
      "createdAt": "2026-02-20T10:00:00Z"
    }
  ],
  "nextToken": null
}

Example

# List insider purchases
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4?limit=20" | jq

# Get insider purchases for a specific date
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4?filingDate=2026-02-24" | jq

# Search by issuer name, owner name, or ticker
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4?searchTerm=CEO" | jq

# Get insider purchases via category filter
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4?category=insider_activity&limit=10" | jq

Get a Form 4 Filing

GET /filings/form4/{filingId}

Returns a single Form 4 filing by ID.

Example

curl -s -H "x-api-key: sa_your_key" \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4/f4-123 | jq

List Japan Filings

GET /filings/japan

Returns Japanese company filings from TDNET in reverse chronological order.

Response

{
  "items": [
    {
      "filingId": "jp-123",
      "companyCode": "7203",
      "companyName": "トヨタ自動車",
      "companyNameEnglish": "Toyota Motor",
      "filingDate": "2026-02-20",
      "filingTime": "15:30:00",
      "documentTitle": "決算短信",
      "documentTitleEnglish": "Earnings Report",
      "pdfUrl": "https://...",
      "summary": "AI-generated summary...",
      "stockExchange": "Tokyo Stock Exchange",
      "tdnetDocumentId": "TD12345",
      "status": "analyzed",
      "tags": ["earnings"],
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T12:00:00Z"
    }
  ],
  "nextToken": null
}

Example

# List Japan filings
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan?limit=20" | jq

# Get Japan filings for a specific date
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan?filingDate=2026-02-24" | jq

# Get Japan filings for a date range
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan?startDate=2026-02-20&endDate=2026-02-25" | jq

# Search by company name, document title, or AI summary
curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan?searchTerm=Toyota" | jq

Get a Japan Filing

GET /filings/japan/{filingId}

Returns a single Japan filing by ID.

Example

curl -s -H "x-api-key: sa_your_key" \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan/jp-123 | jq

Filing Preferences

Archive or favorite filings across all three filing types.

Set Filing Preferences

POST /filings/sec/{filingId}/preferences
POST /filings/form4/{filingId}/preferences
POST /filings/japan/{filingId}/preferences

Sets archive and/or favorite status on a filing. At least one of archived or favorited must be provided.

Request Body

{
  "archived": true,
  "favorited": false
}

Field	Type	Description
`archived`	boolean	Set archive status (optional)
`favorited`	boolean	Set favorite status (optional)

Response

{
  "userId": "your-user-id",
  "filingId": "abc-123",
  "archived": true,
  "favorited": false,
  "createdAt": "2026-02-25T10:00:00Z",
  "updatedAt": "2026-02-25T10:00:00Z"
}

Errors

400 — Missing body or neither archived nor favorited provided
401 — Invalid or missing API key

Examples

# Archive a SEC filing
curl -s -X POST \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/sec/abc-123/preferences | jq

# Favorite a Form 4 filing
curl -s -X POST \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"favorited": true}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/form4/f4-123/preferences | jq

# Archive and favorite a Japan filing
curl -s -X POST \
  -H "x-api-key: sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"archived": true, "favorited": true}' \
  https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/filings/japan/jp-123/preferences | jq

Monitor Groups

Returns all predefined monitor groups organized by category, with filing filter configurations. This is a read-only endpoint — see Monitor Groups for details on each group.

List Monitor Groups

GET /monitor-groups

Returns all predefined monitor groups grouped by category, including the filing filter configuration (form types, AI tags, Form 4 inclusion) for each category.

Response

{
  "categories": [
    {
      "category": "spinoffs",
      "label": "Spin-offs",
      "groups": [
        {
          "groupId": "announced-spinoffs",
          "name": "Announced Spin-offs",
          "description": "Companies that have announced a planned spin-off"
        },
        {
          "groupId": "completed-spinoffs-domestic",
          "name": "Completed Spin-offs (Domestic)",
          "description": "Recently completed domestic spin-off transactions"
        }
      ],
      "filingConfig": {
        "formTypes": ["10-12B", "10-12B/A"],
        "secTags": ["Spin-off", "Distribution"],
        "includeForm4": false
      }
    },
    {
      "category": "insider_activity",
      "label": "Insider Activity",
      "groups": [
        {
          "groupId": "cluster-insider-buying",
          "name": "Cluster Insider Buying",
          "description": "Multiple insiders buying shares in a short period"
        }
      ],
      "filingConfig": {
        "formTypes": [],
        "secTags": [],
        "includeForm4": true
      }
    }
  ]
}

Use the category value or groupId with the filing endpoints to filter filings for a specific group.

Example

curl -s -H "x-api-key: sa_your_key" \
  "https://kc9zu8cyjf.execute-api.us-east-1.amazonaws.com/v1/monitor-groups" | jq

Deals​

List Deals​

Query Parameters​

Response​

Deal Object Fields​

Example​

Get a Deal​

Response​

Errors​

Example​

Create a Deal​

Request Body​

Required Fields​

Optional Fields​

Response (201 Created)​

Example​

Update a Deal​

Request Body​

Updatable Fields​

Response​

Errors​

Example​

Email a Deal​

Request Body​

Response​

Errors​

Example​

Deal Activities​

List Activities​

Query Parameters​

Response​

Create Activity​

Request Body​

Example​

Update Activity​

Request Body​

Example — Mark as Complete​

Delete Activity​

Filings​

Common Query Parameters​

Search Fields by Filing Type​

Category Filtering​

Supported Categories​

Example Group IDs​

List SEC Filings​

Query Parameters​

Response​

Example​

Get a SEC Filing​

Example​

List Form 4 Filings (Insider Purchases)​

Response​

Example​

Get a Form 4 Filing​

Example​

List Japan Filings​

Response​

Example​

Get a Japan Filing​

Example​

Filing Preferences​

Set Filing Preferences​

Request Body​

Response​

Errors​

Examples​

Monitor Groups​

List Monitor Groups​

Response​

Example​

Deals

List Deals

Query Parameters

Response

Deal Object Fields

Example

Get a Deal

Response

Errors

Example

Create a Deal

Request Body

Required Fields

Optional Fields

Response (201 Created)

Example

Update a Deal

Request Body

Updatable Fields

Response

Errors

Example

Email a Deal

Request Body

Response

Errors

Example

Deal Activities

List Activities

Query Parameters

Response

Create Activity

Request Body

Example

Update Activity

Request Body

Example — Mark as Complete

Delete Activity

Filings

Common Query Parameters

Search Fields by Filing Type

Category Filtering

Supported Categories

Example Group IDs

List SEC Filings

Query Parameters

Response

Example

Get a SEC Filing

Example

List Form 4 Filings (Insider Purchases)

Response

Example

Get a Form 4 Filing

Example

List Japan Filings

Response

Example

Get a Japan Filing

Example

Filing Preferences

Set Filing Preferences

Request Body

Response

Errors

Examples

Monitor Groups

List Monitor Groups

Response

Example