# Fictix API examples

Working `curl`/`jq` requests for the conventions in `SKILL.md`. Company-key examples
assume:

```bash
export FICTIX_API_ORIGIN="https://api.fictix.ai"       # or api-staging.fictix.ai
export FICTIX_PROJECT_SLUG="<from Console Connect panel>"
export FICTIX_PROJECT_API_KEY="<from Console > Company settings > Company API keys>"
```

## 1. Get company/org info

```bash
curl -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/info" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY" | jq
```

Confirms the project key and slug resolve to a generated company before you
read anything else. A `401`/`403` means the key is missing, revoked, or
belongs to a different project.

## 2. Read a page of customers

```bash
curl -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/data/customers?limit=100&offset=0" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY" | jq '.data'
```

## 3. Page through every customer

```bash
offset=0
limit=100
while :; do
  page=$(curl -sS \
    "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/data/customers?limit=$limit&offset=$offset" \
    -H "X-API-Key: $FICTIX_PROJECT_API_KEY")
  echo "$page" | jq -c '.data[]'
  count=$(echo "$page" | jq '.count')
  got=$(echo "$page" | jq '.data | length')
  offset=$((offset + got))
  [ "$offset" -ge "$count" ] && break
done
```

Keep paging while `offset + data.length < count`, exactly as documented in
`SKILL.md`.

## 4. Discover the catalog (no credential required)

```bash
curl -sS "$FICTIX_API_ORIGIN/api/v1/catalog/entities" | jq
curl -sS "$FICTIX_API_ORIGIN/api/v1/catalog/connector-capabilities" | jq
```

Catalog endpoints are public discovery routes — use them to check what
entities and connectors are available before assuming a shape exists,
without spending a project key on the request.

## 5. Export invoices as CSV

```bash
curl -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/export/invoices?format=csv" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY" \
  -o invoices.csv
```

For every canonical ledger at once, use the CSV bundle instead:

```bash
curl -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/export-pack/csv" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY" \
  -o fictix-export.zip
```

## 6. Create a demo job idempotently

`POST /api/v1/demo-jobs` is the control-plane surface for approved
server-to-server integrations — it's not the first integration path for a
normal Console customer, and it does not use the project `X-API-Key`. It
authenticates with the Fictix-supplied `FICTIX_ADMIN_API_KEY` in an
`X-Admin-Key` header and requires a stable `Idempotency-Key`:

The signed-in Console uses its own managed WorkOS bearer session for Console
actions. That session is not an external integration credential and must never
be copied from browser tools.

```bash
curl -sS -X POST "$FICTIX_API_ORIGIN/api/v1/demo-jobs" \
  -H "X-Admin-Key: $FICTIX_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-demo-2026-07-12" \
  -d '{
    "company": { "name": "Acme Logistics" },
    "generation": { "employees": 20, "months_of_history": 6, "quality_preset": "clean" }
  }' | jq
```

Reuse `acme-demo-2026-07-12` only to retry this exact same request body — a
different body with the same key returns `409`. The admin key is an
approved-management credential (approved partners only), not the project API
key from the earlier examples. Never use an email/password, copy a browser
session token, or put the management credential in frontend code.

## 7. Use one organization key across companies (staging only)

An organization admin creates the key in staging Organization settings.
Keep the key on your server:

```bash
export FICTIX_API_ORIGIN="https://api-staging.fictix.ai"
export FICTIX_ORGANIZATION_ID="<from staging Organization settings>"
export FICTIX_ORGANIZATION_API_KEY="<organization key shown once at creation>"

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/organizations/$FICTIX_ORGANIZATION_ID/companies?limit=100&offset=0" \
  -H "X-API-Key: $FICTIX_ORGANIZATION_API_KEY" | jq
```

Use any returned company's `slug` in `/api/v1/orgs/{slug}/data/customers`
and keep the same key. Directory pagination uses `offset + count < total`.
The key covers current and future companies in that organization; it does
not grant the management authority needed in example 6.