# Alertstore service integration

Alertstore can create an Investibook diagnostic workspace through the
route-scoped alert-ingest service identity. The credential is accepted only by
`POST /api/workspaces/from-alert`, `POST /api/workspaces/from-entry`, and
`POST /api/integrations/jira-alerts`; normal user and admin APIs continue to
require an Investibook session or user API key.

Configure the backend with:

```text
INVESTIBOOK_ALERT_INGEST_SERVICE_TOKEN=<random secret>
INVESTIBOOK_ALERT_INGEST_SERVICE_EMAIL=alertstore-service@pingcap.com
```

The service user is created on the first valid request and owns the generated
workspaces. Store both values in the deployment secret; do not put the token in
a ConfigMap or in source control.

Example request:

```bash
curl -X POST https://investibook.example.com/api/workspaces/from-alert \
  -H "X-API-Key: $ALERT_INGEST_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "alert_id": "ALT-2608-1742",
    "alert_type": "alertstore",
    "idempotency_key": "alertstore:ALT-2608-1742",
    "auto_questions": ["Diagnose this alert and summarize the evidence."]
  }'
```

Use a stable idempotency key so retries return the existing workspace instead
of creating duplicates. The Alertstore adapter is read-only: it may retrieve
alert detail, timeline, and events, but it must not acknowledge, resolve,
assign, comment, subscribe, or mute alerts.

## Jira alert integration

An external service can create a diagnostic workspace for an O11Y Jira alert
on behalf of an Investibook user. The endpoint imports Jira through the normal
workspace source preparation flow and starts analysis after the source is
ready.

```bash
curl -X POST https://investibook.example.com/api/integrations/jira-alerts \
  -H "X-API-Key: $ALERT_INGEST_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "jira_id": "O11Y-12345",
    "user_email": "oncaller@pingcap.com"
  }'
```

The endpoint responds immediately with `202 Accepted` while Jira preparation
and diagnosis continue asynchronously:

```json
{
  "workspace_id": "ws-...",
  "workspace_url": "https://investibook.com/workspace/ws-...",
  "jira_id": "O11Y-12345",
  "user_email": "oncaller@pingcap.com",
  "status": "accepted"
}
```

`prompt` may be supplied to override the default diagnosis request. Requests
with the same normalized `user_email` and `jira_id` return the same workspace;
this endpoint does not create a second workspace for that pair.