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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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 28 form types including 8-K, 10-12B, 10-12G (liquidation/litigation trust registrations), 8-A12B/8-A12G, 15-12B/15-12G/15-15D (deregistrations — the analysis states whether the company going dark was profitable in its last reported period), S-1, 424B3 (conversion prospectuses with pro-forma book-value extraction), 424B4, SC 13D, DEFM14A, and more. Detection tags flag high-signal situations: Going Dark, Equity Committee (official equity-holders committee appointed in a Chapter 11), Structurally Forced Spin (Form 10 separations from closed-end funds/BDCs), and Transformative Acquisition (deal value at least half the acquirer's market cap, with consideration mix, NOL disclosures, and stated synergies extracted).

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://api.situationatlas.com/v1/filings/sec?limit=10" | jq

# Get filings for a single date
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.com/v1/filings/form4?limit=20" | jq

# Get insider purchases for a specific date
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.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://api.situationatlas.com/v1/filings/form4?searchTerm=CEO" | jq

# Get insider purchases via category filter
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.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://api.situationatlas.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://api.situationatlas.com/v1/filings/japan?limit=20" | jq

# Get Japan filings for a specific date
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.com/v1/filings/japan/jp-123 | jq

---

List ASX Announcements (Australia)

GET /filings/asx

ASX announcements through a special-situations filter: substantial holder notices (the Schedule 13D analog), takeover/scheme announcements, director's interest notices (the Form 4 analog), buybacks, and everything the exchange flags price sensitive.

Response

{
  "items": [
    {
      "filingId": "2924-03110237-2A1684021",
      "symbol": "OML",
      "companyName": "OOH!MEDIA LIMITED",
      "headline": "Update on Change of Control Proposals",
      "announcementTypes": ["Takeover Announcements/Scheme Announcements"],
      "isPriceSensitive": true,
      "sector": "Communication Services",
      "industry": "Media",
      "filedDate": "2026-07-12",
      "announcedAt": "2026-07-12T22:39:16.000Z",
      "pdfUrl": "https://...",
      "analysis": "AI-generated special-situations summary...",
      "status": "analyzed",
      "aiTags": [{ "name": "M&A / Takeover", "color": "blue-100" }],
      "createdAt": "2026-07-12T22:45:00Z"
    }
  ],
  "nextToken": null
}

Example

# List ASX announcements
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.com/v1/filings/asx?limit=20" | jq

# Search by company, symbol, or headline
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.com/v1/filings/asx?searchTerm=OOH" | jq

# Poll the resumable cursor (same contract as /filings/sec/updates)
curl -s -H "x-api-key: sa_your_key" \
  "https://api.situationatlas.com/v1/filings/asx/updates?since=2026-07-23" | jq

---

Get an ASX Announcement

GET /filings/asx/{filingId}

Returns a single ASX announcement by ID.

---

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://api.situationatlas.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://api.situationatlas.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://api.situationatlas.com/v1/filings/japan/jp-123/preferences | jq

---

Monitor Groups

Returns all predefined monitor groups organized by category, with filing filter configurations. Groups and tickers are fully readable and writable — see Data Coverage.

---

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://api.situationatlas.com/v1/monitor-groups" | jq