# DealGraph quickstart

> First API call in 30 seconds. No account needed for the demo dataset.

## 1. Read the demo portfolio

```bash
curl -s https://dealgraph.vc/api/v1/dashboard \
  -H "Authorization: Bearer dg_demo"
```

The `dg_demo` key serves a fictional read-only portfolio (Aurora Ventures). Every read
endpoint works with it; writes are simulated only (`?dryRun=true`).

## 2. Explore

```bash
# All companies in the demo org
curl -s https://dealgraph.vc/api/v1/companies -H "Authorization: Bearer dg_demo"

# Latest metrics for a company
curl -s "https://dealgraph.vc/api/v1/companies/d3m0c0de-0001-4000-8000-000000000001/metrics?latest=true" \
  -H "Authorization: Bearer dg_demo"

# Validate a write without persisting anything (works on the demo key)
curl -s -X POST "https://dealgraph.vc/api/v1/companies/d3m0c0de-0001-4000-8000-000000000001/metrics?dryRun=true" \
  -H "Authorization: Bearer dg_demo" -H "Content-Type: application/json" \
  -d '{"metricKey":"arr_eur","metricDate":"2026-08-01","valueNumeric":"1200000"}'
```

## 3. Use your own data

1. Sign up at https://dealgraph.vc/login?signup=true and create your organization.
2. An org admin creates an API key under Settings → API Keys (scope: read-only or read & write).
3. Swap `dg_demo` for your `dg_live_...` key. All data is scoped to your organization.

## 4. Go agent-native

- Hosted MCP server: `https://dealgraph.vc/api/mcp` — see the [agent integration guide](https://dealgraph.vc/docs/agents.md)
- Full API reference in one file: [https://dealgraph.vc/llms-full.txt](https://dealgraph.vc/llms-full.txt)
- OpenAPI contract: [https://dealgraph.vc/api/v1/openapi.json](https://dealgraph.vc/api/v1/openapi.json)

## Conventions you should know

- **Money:** every monetary value is absolute EUR (e.g. `"12500000.00"` = €12.5M). No €M units.
- **Envelopes:** success `{ "data": ... }`, error `{ "error": { "code", "message", "field"?, "details"? } }`.
- **Write safety:** `?dryRun=true` validates and returns the would-be result inside a rolled-back
  transaction. Send an `Idempotency-Key` header on every POST create. DELETE is soft by default
  and reversible via `POST /<entity>/{id}/restore`.
- **Sync:** `?updatedSince=<ISO>` on list endpoints, `GET /changes?since=<ISO>` as a guaranteed
  change feed, webhooks (HMAC-signed, best-effort) for push.
- **Rate limits:** 120 requests/minute per key, best effort. Responses carry
  `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; 429s carry `Retry-After`.