# Data Reaktor — Product Context

> This file is intended for LLM coding assistants, AI agents, and agent orchestrators that need to understand what Data Reaktor is, what it can do, and how to integrate with it. It follows the convention established by tools like Cursor, Claude, and similar AI-native development environments.

## Product Summary

**Data Reaktor** is an agentic B2B intelligence factory. It converts a lead (name + company + context) into structured, production-ready B2B sales intelligence: personalized LinkedIn messages, cold emails, outreach sequences, lead scores, call scripts, and thought leadership content.

It is designed as an agent-first platform. Every capability is a typed REST endpoint callable by any HTTP-capable agent, workflow engine, or LLM tool. A human-facing dashboard UI provides identical capabilities for non-technical users.

## Core Value Proposition

1. **For AI agents**: A reliable, production-grade tool endpoint that removes the need for agents to scrape the web, hallucinate prospect details, or hand-craft outreach copy. Submit a lead JSON, receive structured B2B intelligence JSON.

2. **For humans (fractional consultants, B2B sellers)**: A dashboard that takes the same actions manually — upload a CSV, research a single prospect, generate thought leadership content.

3. **For builders (n8n, LangChain, Make.com users)**: Webhook-in, webhook-out architecture with A2A discovery support, making it easy to drop into any automation stack.

## Capabilities

All tasks cost **5 credits** (flat pricing).

| Capability | Task Type | Credits | Mode |
|------------|-----------|---------|------|
| Lead Scoring | `lead_scoring` | 5 | Sync |
| LinkedIn Message | `linkedin_message` | 5 | Sync |
| Personalized Email | `personalized_email` | 5 | Sync |
| Cold Call Script | `cold_call_script` | 5 | Sync |
| Thought Leadership | `thought_leadership` | 5 | Sync |
| 4-Step Outreach Sequence | `outreach_sequence` | 5 | Sync |
| ABM Content Brief | `abm_content_brief` | 5 | Sync |
| Domain to Company | `domain_to_company` | 5 | Sync |
| Contact Lookup | `contact_lookup` | 5 | Sync |
| Prospect Research | `research` | 5 | Async |
| Batch Outreach | `outreach_generation` | 5/contact | Async |
| Knowledge Graph Lookup | — | 1 | Sync |
| Industry Signals | — | 0 | Sync |

## Authentication

- API key via `X-API-Key` header or `Authorization: Bearer <key>`
- Keys are scoped to an agent identity (created in the `/agents` dashboard)
- Keys expire after 365 days and can be rotated
- Free tier available — no credit card required to start

## Full API Surface

```
POST   /api/v1/tasks                        — Submit a single task
GET    /api/v1/tasks                        — List recent tasks (limit, offset)
GET    /api/v1/tasks/{taskId}               — Poll task status / get result
PATCH  /api/v1/tasks/{taskId}/star          — Star or unstar a task
DELETE /api/v1/tasks/{taskId}               — Cancel a queued task (credits refunded)

POST   /api/v1/batch                        — Submit up to 100 contacts as JSON (one task per contact)

GET    /api/v1/outputs                      — Paginated output history (taskType, search, starred filters)
GET    /api/v1/outputs/{taskId}             — Full output detail for a single task
POST   /api/v1/outputs/{taskId}/star        — Star or unstar an output

GET    /api/v1/campaigns                    — List user's campaigns (read-only)
GET    /api/v1/campaigns/{id}               — Get campaign detail including linked ICP id
GET    /api/v1/icps                         — List user's ICPs (read-only)
GET    /api/v1/icps/{id}                    — Full ICP detail

GET    /api/v1/analytics/performance        — Aggregate performance snapshot
GET    /api/v1/analytics/agents/{agentId}   — Per-agent performance breakdown

GET    /api/v1/knowledge/company/{domain}   — Company knowledge graph lookup (1 credit)
GET    /api/v1/knowledge/signals/{industry} — Aggregated industry signals (free)

GET    /api/v1/workflows                    — List available multi-step workflows
POST   /api/v1/workflows                    — Submit a multi-step workflow

GET    /api/v1/skills                       — Full skill registry with schemas and credit costs
GET    /api/v1/openapi.json                 — OpenAPI 3.1 specification
GET    /.well-known/agent.json              — A2A capability manifest
GET    /AGENTS.md                           — Full agent reference
GET    /CONTEXT.md                          — This file

POST   /trigger/{userId}                     — Inbound trigger (A2A, no agent setup needed)
```

## Minimal Working Example (Lead Scoring)

```bash
curl -X POST https://www.datareaktor.ai/api/v1/tasks \
  -H "X-API-Key: drk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "lead_scoring",
    "inputPayload": {
      "contactName": "Jane Smith",
      "contactRole": "VP of Sales",
      "company": "Acme Corp",
      "signals": ["Series B funded", "Hiring 12 SDRs"]
    }
  }'
```

Response:
```json
{
  "taskId": "task_abc123",
  "status": "completed",
  "output": {
    "score": 87,
    "tier": "A",
    "reasoning": "Strong ICP fit: VP-level, SaaS, active growth signals"
  },
  "creditsCharged": 5
}
```

## Batch Input Example (JSON, no CSV required)

```bash
curl -X POST https://www.datareaktor.ai/api/v1/batch \
  -H "X-API-Key: drk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "name": "Jane Smith", "company": "Acme Corp", "title": "VP of Sales", "taskType": "linkedin_message" },
      { "name": "Bob Jones", "company": "Beta Inc", "taskType": "lead_scoring" }
    ]
  }'
```

Response:
```json
{
  "taskIds": ["task_abc123", "task_def456"],
  "count": 2,
  "totalCreditsCharged": 10
}
```

## Webhook / Callback Pattern

For async tasks or when you want to avoid polling:

```json
{
  "taskType": "research",
  "inputPayload": { "name": "Jane Smith", "context": "VP Sales, acmecorp.com" },
  "callbackUrl": "https://your-server.com/handle-result"
}
```

Data Reaktor POSTs the result to `callbackUrl` with an `X-DR-Signature` HMAC header for verification.

## Inbound Trigger (Push Model)

For workflows where another system pushes a lead to Data Reaktor:

```
POST /trigger/{userId}
Authorization: Bearer drk_trigger_YOUR_KEY
Content-Type: application/json

{ "name": "Jane Smith", "company": "Acme Corp", "title": "VP of Sales" }
```

Returns a complete outreach sequence in the response body.

## How Outputs Are Personalized

Every AI output is shaped by two layers of context:
1. **User account persona** — industry focus, target persona, value proposition, preferred tone (set in account settings)
2. **Per-request payload** — the specific lead's name, role, company, and any signals passed in `inputPayload`

Agents can pass the user persona context inline in the payload to override the account defaults.

## Campaign & ICP Context

Agents can reference existing campaigns and ICPs (set up by the account owner) when submitting tasks:

- Use `GET /api/v1/campaigns` to list campaigns and find the ID
- Use `GET /api/v1/icps` to list ICPs
- Pass `campaignId` in task or batch requests to link output to a campaign

Campaign and ICP *creation* is a human setup step (via the dashboard). Read-only API access lets agents reference the configured context without human intervention per-task.

## Credit System

Credits are consumed per task completion. They do not expire. Agents can have their own credit balance funded independently of the account owner.

All task types cost 5 credits each (flat pricing). Knowledge graph lookups cost 1 credit. Industry signals are free.

Credit packs available (no subscription required):
- Trial: 100 credits, $0 (one-time, new users only)
- Basic: 1,000 credits, $10
- Plus: 6,000 credits, $49
- Max: 20,000 credits, $149

Subscription plans include a monthly allocation: Starter ($12/mo), Growth ($39/mo), Scale ($99/mo).

## Technical Architecture Notes

- Backend: Node.js / Express, TypeScript
- Database: PostgreSQL (Drizzle ORM)
- AI: LLM-based generation (all outputs are AI-generated)
- Async tasks: routed through n8n automation backend
- Webhooks: HMAC-SHA256 signed
- API spec: OpenAPI 3.1, available at `/api/v1/openapi.json`
- A2A: agent.json manifest at `/.well-known/agent.json`

## Intended Agent Integrations

- **n8n**: Use the HTTP Request node to call `/api/v1/tasks` or `/api/v1/batch`. Set `X-API-Key` header in credentials.
- **LangChain**: Wrap `/api/v1/tasks` as a Tool. Use the skills endpoint to auto-generate tool descriptions.
- **Make.com**: HTTP module → POST to task endpoint → parse JSON response.
- **AutoGen / CrewAI**: Register as a custom function tool using the OpenAPI spec.
- **Zapier**: Use the Webhook action to POST leads, receive structured output.

## Limitations

- Async tasks (`research`, `outreach_generation`) require polling or a callback URL — they do not return inline
- Rate limits apply per tier (10–500 tasks/hour, unlimited on Scale)
- All outputs are AI-generated; factual accuracy depends on publicly available signals
- Batch endpoint (`/api/v1/batch`) accepts up to 100 contacts per request
- Campaign and ICP creation is UI-only; agents have read-only access

## Links

- Dashboard: https://www.datareaktor.ai
- Full agent reference: https://www.datareaktor.ai/AGENTS.md
- OpenAPI spec: https://www.datareaktor.ai/api/v1/openapi.json
- A2A manifest: https://www.datareaktor.ai/.well-known/agent.json
- Human help docs: https://www.datareaktor.ai/help
- Pricing: https://www.datareaktor.ai/pricing