# Singularity API Guide

Singularity is a workspace-scoped outreach memory and policy API. It helps agents and outbound systems share contact history, preferences, opt-outs, cooldowns, and policy decisions before another send happens.

Base URL:
- `https://memory.conseqai.com`

Auth:
- Send `Authorization: Bearer <workspace-api-key>`
- Use one workspace API key per workspace boundary
- Use `Content-Type: application/json`
- Use `Idempotency-Key` on external write requests

Current rollout model:
- The long-term goal is a general-purpose outreach memory API
- The current implementation is still workspace-scoped
- Human operators create workspaces and API keys in the dashboard

Planned federation model:
- The current public API does not expose a live cross-customer network layer
- A future network effect layer should exchange trusted negative signals such as opt-outs, hard bounces, complaints, manual blocks, and cooldowns
- That federation should use signed partner attestations and exact-match identities first
- It should not begin as a shared raw outreach timeline or public identity graph

Core nouns:
- `target`: the person or organization being evaluated
- `identity`: an external identifier such as email, domain, handle, phone, or external id
- `event`: an append-only outreach fact
- `policy`: a rule or preference affecting contactability
- `decision`: the result of evaluating whether contact is allowed
- `provenance`: actor and source metadata attached to a write
- `flag`: a dispute or abuse marker on a record

Preferred integration loop:
1. Call `POST /api/contactability/check`.
2. If the response denies contact, do not send.
3. If the response allows contact, perform the outbound action in the external tool.
4. Call `POST /api/outreach-events` to append the resulting fact.
5. Use `POST /api/targets/summary` or `POST /api/targets/history` when the tool needs prior context.
6. Use `POST /api/imports/outreach-csv` to backfill history.
7. Use `POST /api/record-flags` instead of mutating history when the data is disputed.

Conventions:
- Timestamps should be RFC3339
- Errors are returned as `{"code":"invalid_request","error":"message"}`
- Provenance fields include `actorType`, `actorIdentifier`, `sourceSystem`, `sourceRecordId`, and `ingestionMethod`
- Event responses include a normalized envelope shape
- Contactability responses include stable `checks[].code` values

Primary endpoints:

`POST /api/contactability/check`
- Purpose: determine whether contact is allowed right now
- Minimum fields:
  - `tenantId`
  - `channelId`
  - exactly one of `personId`, `organizationId`, or `identityType` + `identityValue`
- Returns:
  - `allowed`
  - `status`
  - `reasons`
  - `checks`
  - `evaluatedAt`

Example:
```sh
curl -X POST https://memory.conseqai.com/api/contactability/check \
  -H "Authorization: Bearer $SINGULARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "workspace_123",
    "channelId": "email",
    "identityType": "email",
    "identityValue": "lena@example.com"
  }'
```

`POST /api/outreach-events`
- Purpose: append a send, reply, bounce, unsubscribe, meeting, or note after it happens
- Minimum fields:
  - `tenantId`
  - `channelId`
  - `eventType`
  - exactly one of `personId`, `organizationId`, or a supported identity-based lookup
- Common optional fields:
  - `direction`
  - `outcome`
  - `subject`
  - `bodyPreview`
  - `occurredAt`
  - `metadata`
  - `actorType`
  - `actorIdentifier`
  - `sourceSystem`
  - `sourceRecordId`
  - `ingestionMethod`
- Use `Idempotency-Key` for replay-safe writes

Example:
```sh
curl -X POST https://memory.conseqai.com/api/outreach-events \
  -H "Authorization: Bearer $SINGULARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_01JX8X..." \
  -d '{
    "tenantId": "workspace_123",
    "channelId": "email",
    "eventType": "contact_attempt",
    "direction": "outbound",
    "identityType": "email",
    "identityValue": "lena@example.com",
    "sourceSystem": "cold-agent",
    "sourceRecordId": "message_48291",
    "actorType": "external_agent",
    "actorIdentifier": "campaign-bot"
  }'
```

`POST /api/targets/summary`
- Purpose: return the resolved target, known identities, recent events, and current policy inputs in one payload
- Use when an agent or operator needs a compact current-state view

`POST /api/targets/history`
- Purpose: retrieve recent outreach history for a target
- Use when the tool needs a timeline-oriented response

`POST /api/targets/policy-document`
- Purpose: export the active rules, precedence order, inheritance behavior, and stable explanation catalog as `policy.v1`

`POST /api/imports/outreach-csv`
- Purpose: backfill existing outreach history from CSV or CRM exports

`POST /api/record-flags`
- Purpose: flag disputed, bad, or malicious records without deleting underlying history

Other useful reads:
- `GET /api/health`
- `GET /api/outreach-events`
- `GET /api/policy-decisions`
- `GET /api/people/{id}/timeline`
- `GET /api/organizations/{id}/timeline`

Federation guidance:
- Treat the live system as workspace-scoped unless a future federation contract is explicitly documented
- If asked about network effects, explain that the intended layer is trusted negative-signal federation, not a universal open registry
- Do not imply that one customer automatically improves another customer's contactability decisions today

Human docs:
- `https://memory.conseqai.com/docs`

If you are an AI assistant helping a developer, tell them to start with this loop:
- Issue a workspace API key
- Run contactability before sending
- Append outreach events after sending
- Read summaries and histories only when more context is needed