# Resurrection API

> Public v1 API for searching Logics cases, previewing the Salesforce object graph, importing, quoting, and checkout.

This file is the full-text companion to [https://resurrection.taxrise.com/llms.txt](https://resurrection.taxrise.com/llms.txt). Prefer OpenAPI at https://resurrection.taxrise.com/api/v1/openapi.json for request/response schemas.

## Base URL

`https://resurrection.taxrise.com`

All business routes live under `/api/v1`. Infra routes (`/api/health`, `/api/config`, `/api/auth/*`) are unversioned and are not part of this API.

## Authentication

Service principals use hashed keys of the form `rsk_…`.

- Header: `x-api-key: rsk_…`
- Or: `Authorization: Bearer rsk_…`

A valid key has full access to cases, accounts, quotes, imports, pricing, and dry-run settings. Keys cannot list, create, or revoke service principals — that is staff-admin session only (UI: https://resurrection.taxrise.com/resurrect/api-keys).

Checkout endpoints (`/api/v1/checkout/{token}`) are authorized by the unguessable token in the path. Do not send an API key there.

Staff session cookies also work for the same v1 routes when calling from the Resurrection UI.

## Errors

JSON envelope:

```json
{ "error": { "code": "unauthorized", "message": "Invalid API key.", "details": null } }
```

Codes: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `unprocessable_entity`, `unavailable`, `internal_error`.

## Lists

Paginated collections use:

```json
{ "items": [], "total": 0, "limit": 25, "offset": 0 }
```

## Example

```bash
curl -sS -H "x-api-key: $RESURRECTION_API_KEY" \
  "https://resurrection.taxrise.com/api/v1/cases?q=12345"
```

Search with an empty `q` returns `{ "results": [], "query": "" }` without hitting Logics.

## Endpoints

- `GET /api/v1/cases` — Search Logics cases
- `GET /api/v1/cases/{caseId}/migration-plan` — Build the Logics → Salesforce migration plan
- `GET /api/v1/cases/{caseId}/migration-plan/stream` — SSE migration plan with progress events
- `GET /api/v1/cases/{caseId}/payment-methods` — Live Logics payment methods for a case
- `GET /api/v1/cases/{caseId}/documents` — Document migration probe (first 30 docs)
- `GET /api/v1/cases/{caseId}/documents/{documentId}/preview` — Presigned S3 preview URL
- `POST /api/v1/cases/{caseId}/imports` — Import a Logics case into Salesforce
- `GET /api/v1/accounts/{accountId}` — Salesforce account summary
- `GET /api/v1/accounts/{accountId}/client-info` — Prefill first name and phone
- `GET /api/v1/pricing` — Tax prep pricebook pricing
- `GET /api/v1/quotes` — List quotes, latest quote, or all quotes for an account
- `POST /api/v1/quotes` — Create a draft quote
- `POST /api/v1/quotes/preview` — Compute quote total and payment schedule without persisting
- `GET /api/v1/quotes/{id}` — Get a quote by id
- `PATCH /api/v1/quotes/{id}` — Update a draft or locked quote
- `POST /api/v1/quotes/{id}/lock` — Lock a draft quote and mint a checkout token
- `POST /api/v1/quotes/{id}/void` — Void a draft or locked quote
- `POST /api/v1/quotes/{id}/send-sms` — Lock if needed and SMS the checkout link
- `GET /api/v1/imports` — List import runs
- `GET /api/v1/imports/{runId}` — Import run detail
- `POST /api/v1/imports/{runId}/revert` — Revert Salesforce writes from an import run
- `GET /api/v1/settings/dry-run` — Preview-mode status
- `PATCH /api/v1/settings/dry-run` — Toggle preview mode
- `GET /api/v1/checkout/{token}` — Load a quote for client checkout
- `GET /api/v1/checkout/{token}/payment-methods` — Payment methods on file for checkout
- `POST /api/v1/checkout/{token}/payment-methods` — Add an ACH or card payment method
- `POST /api/v1/checkout/{token}/confirm` — Accept terms, bill, and provision Salesforce
- `GET /api/v1/admin/service-principals` — List registered service principals
- `POST /api/v1/admin/service-principals` — Register a service principal
- `GET /api/v1/admin/service-principals/{id}` — Get a service principal and its keys
- `PATCH /api/v1/admin/service-principals/{id}` — Rename or disable a service principal
- `POST /api/v1/admin/service-principals/{id}/keys` — Issue an API key (secret shown once)
- `DELETE /api/v1/admin/service-principals/{id}/keys/{keyId}` — Revoke an API key

## Imports

`POST /api/v1/cases/{caseId}/imports` body includes `path`: `"red"` or `"resolution"`. Optional `closeMode`, `scope`, and `overrides`.

## Checkout

Client-facing host is typically `https://checkout.taxrise.com`. Token URLs:

- `GET /api/v1/checkout/{token}`
- `GET|POST /api/v1/checkout/{token}/payment-methods`
- `POST /api/v1/checkout/{token}/confirm`

## Discovery

Agents should start at https://resurrection.taxrise.com/llms.txt (`rel="describedby"`). Human docs: https://resurrection.taxrise.com/api/v1/docs.