AI agent integration

Many teams building against Fictix now do most of the integration work through an AI coding agent — Claude Code, Cursor, Codex/OpenAI Codex, or something similar — rather than hand-writing every request. Agents work best when they have a short, explicit brief instead of having to infer conventions from a full doc site, so this page gives copy-paste starting points for pointing your agent at Fictix: a docs-ingestion trick, and ready-made project files for Claude Code and Cursor.

Machine-readable docs

Every page on this site is available as raw Markdown — useful for pasting into a prompt or letting an agent fetch it directly:

Append .md to any page URL to get that page as plain Markdown, e.g. https://fictix-docs.vercel.app/api-reference/demo-jobs.md.
/llms.txt is a curated index of the docs, meant to help an agent decide what to fetch next.
/llms-full.txt is the entire documentation set concatenated into one file, sized for one-shot ingestion into an agent's context window when you'd rather hand over everything up front than let the agent crawl page by page.

None of the snippets below should ever contain a real project API key. If you paste one of these files into a repo that's shared or public, read the key from an environment variable at runtime instead of hardcoding it — treat a committed AGENTS.md, SKILL.md, or .cursor/rules/*.mdc file exactly like any other source file a teammate (or the internet) can read.

AGENTS.md

Drop a condensed version of this into your own project's AGENTS.md (or append it to an existing one) so any agent that reads that file picks up the essentials before it writes a single request.

## Fictix API

Fictix is a synthetic-company data API (accounting, banking, CRM, payroll,
tasks). Get a project slug and API key from the Fictix Console
(`console.fictix.ai` → Company settings → Company API keys) — never invent
or construct these values.

Environment variables this project expects:

```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>"
```

Auth header for all runtime/data requests:

```http
X-API-Key: <FICTIX_PROJECT_API_KEY>
```

Runtime data lives under
`GET $FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/data/{entity}`.

Canonical entity names — use these, not the deprecated aliases in
parentheses:

accounts, bank_accounts, bank_transactions, bills, credit_memos, customers,
customer_payments (alias: payments), deals, employees, invoices, items,
journal_entries, payroll_runs, tasks, vendor_payments (alias: bill_payments),
vendors

Page with `limit`/`offset` and continue while `offset + data.length < count`.

If this project also creates/controls companies via
`POST /api/v1/demo-jobs` (approved control-plane access only, separate from
the project API key above), use the Fictix-supplied `FICTIX_ADMIN_API_KEY` as
`X-Admin-Key`. The signed-in Console uses a managed WorkOS bearer session for
its own actions; do not ask for or copy that session token. Every call must
carry an `Idempotency-Key` header. Reuse the same key only to retry the exact
same request body — a different body with a reused key returns `409`.
Never reuse a placeholder key like `demo` or `test` across unrelated calls.

Full reference: https://fictix-docs.vercel.app/llms-full.txt

Claude Code skill

Save this as .claude/skills/fictix-api/SKILL.md in your own repo to teach Claude Code these facts as a loadable skill instead of relying on it re-deriving them from context each time.

---
name: fictix-api
description: Facts and conventions for calling the Fictix synthetic-company API — base URL, auth header, and canonical entity names.
---

# Fictix API

Fictix serves synthetic-company data (accounting, banking, CRM, payroll,
tasks) for a company created or selected in the Fictix Console.

## Config

Read these from the environment — never hardcode a real key in this file
or in generated code:

```bash
FICTIX_API_ORIGIN        # e.g. https://api.fictix.ai or https://api-staging.fictix.ai
FICTIX_PROJECT_SLUG      # from Console > Connect to your builder
FICTIX_PROJECT_API_KEY   # from Console > Company settings > Company API keys
```

## Auth

Runtime/data requests use a project API key in this header:

```http
X-API-Key: <FICTIX_PROJECT_API_KEY>
```

Scope it to `/api/v1/orgs/{FICTIX_PROJECT_SLUG}/...` routes only. Don't send
this key to `/api/v1/demo-jobs` control-plane routes, and don't send a
control-plane credential to `/orgs/{slug}` routes. The external control-plane
credential (approved partners only) is `FICTIX_ADMIN_API_KEY` as `X-Admin-Key`;
never invent other credential variable names or solicit a Console session token.

## Canonical entities

Use these names (not the parenthetical legacy aliases) when reading or
generating code against entity data:

accounts, bank_accounts, bank_transactions, bills, credit_memos, customers,
customer_payments (alias: payments), deals, employees, invoices, items,
journal_entries, payroll_runs, tasks, vendor_payments (alias:
bill_payments), vendors

## Common request

```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"
```

Page with `limit`/`offset`; continue while `offset + data.length < count`.

## Idempotency (control-plane only)

`POST /api/v1/demo-jobs` requires a stable `Idempotency-Key` header. Reuse a
key only to retry the identical request body; a different body with a
reused key returns `409`.

## Further reading

Full docs as Markdown: https://fictix-docs.vercel.app/llms-full.txt (or fetch a
single page by appending `.md` to its URL).

Cursor rules

Save this as .cursor/rules/fictix.mdc so Cursor applies it automatically whenever you're editing files that touch the Fictix integration.

---
description: Fictix API conventions — base URL, auth header, canonical entities, and idempotency rules for demo-jobs.
globs: ["**/*fictix*", "**/lib/fictix/**"]
alwaysApply: false
---

# Fictix API conventions

- Base URL and credentials come from the environment, never hardcoded:
  `FICTIX_API_ORIGIN`, `FICTIX_PROJECT_SLUG`, `FICTIX_PROJECT_API_KEY`.
- Runtime/data requests authenticate with `X-API-Key: <FICTIX_PROJECT_API_KEY>`
  and are scoped to `/api/v1/orgs/{FICTIX_PROJECT_SLUG}/...`.
- Use canonical entity names in new code: accounts, bank_accounts,
  bank_transactions, bills, credit_memos, customers, customer_payments, deals,
  employees, invoices, items, journal_entries, payroll_runs, tasks, vendor_payments,
  vendors. Treat `payments` and `bill_payments` as deprecated aliases for
  `customer_payments` and `vendor_payments`.
- Page list endpoints with `limit`/`offset`; keep paging while
  `offset + data.length < count`.
- Any call to `POST /api/v1/demo-jobs` must include a stable
  `Idempotency-Key` header. Only retry with the same key if the request body
  is unchanged — a changed body with a reused key returns `409`.
- Error `detail` may be a plain string or a `{ code, message }` object;
  handle both shapes.
- Fictix ships an official MCP sidecar (`python -m fictix_mcp`) — prefer it
  over hand-wrapping these REST endpoints. It is a local process, not a
  hosted endpoint. Setup: https://fictix-docs.vercel.app/for-agents/mcp

Every other coding agent — same brief, different filename

The same three ingredients — the env vars, the X-API-Key header, and the canonical entity list — are the whole brief regardless of tool. The AGENTS.md snippet above is the content; the only thing that changes is which file your tool reads it from:

Tool	Where to put the brief
Codex, Amp, opencode, and most newer agents	`AGENTS.md` at the repo root — the emerging cross-tool standard
GitHub Copilot	`.github/copilot-instructions.md`; the Copilot coding agent also reads `AGENTS.md` directly
Windsurf	`.windsurf/rules/fictix.md` (legacy single-file: `.windsurfrules`)
Cline	`.clinerules` (single file or folder)
Gemini CLI	`GEMINI.md`
JetBrains Junie	`.junie/guidelines.md`
Replit Agent	`replit.md`

Or skip the copy-paste and pull the maintained version straight from the skill pack:

curl -sS https://fictix-docs.vercel.app/fictix-skill-pack/AGENTS.md -o AGENTS.md

Most of these tools also speak MCP (Copilot in VS Code, Windsurf, Cline, Gemini CLI). The MCP sidecar (python -m fictix_mcp) works with all of them — each client has its own config file shape, but the server env vars are always the same ones documented on that page (FICTIX_BASE_URL, FICTIX_DEFAULT_SLUG, FICTIX_PROJECT_API_KEY).

Browser-based app builders (Lovable, v0, Bolt, Replit)

Prompt-driven app builders generate frontend code, and a Fictix project API key must never ship in frontend code — see browser safety. The pattern that works is a thin server-side proxy: the builder's server leg (Lovable → Supabase Edge Function, v0 → Next.js route handler, Bolt/Replit → server endpoint) holds the key as a secret and relays requests; the browser only ever talks to your proxy.

Paste this into your builder's knowledge/system-prompt area:

This app reads business data from the Fictix API (synthetic-company data:
accounting, banking, CRM, payroll, tasks).

Rules:
- Never call api.fictix.ai from browser code, and never put
  FICTIX_PROJECT_API_KEY in client-side source or public env vars.
- Create a server-side proxy (edge function / route handler) that reads
  FICTIX_API_ORIGIN, FICTIX_PROJECT_SLUG, and FICTIX_PROJECT_API_KEY from
  server secrets.
- The proxy calls
  GET {FICTIX_API_ORIGIN}/api/v1/orgs/{FICTIX_PROJECT_SLUG}/data/{entity}
  with header "X-API-Key: {FICTIX_PROJECT_API_KEY}" and returns the JSON to
  the browser. Support limit/offset query params.
- Valid entities: accounts, bank_accounts, bank_transactions, bills,
  credit_memos, customers, customer_payments, deals, employees, invoices,
  items, journal_entries, payroll_runs, tasks, vendor_payments, vendors.
- Page with limit/offset; keep fetching while offset + data.length < count.
- Error "detail" may be a plain string or a { code, message } object —
  handle both shapes.

Full API docs: https://fictix-docs.vercel.app/llms-full.txt

These tools can't run a local MCP sidecar, and there's no hosted MCP endpoint yet — the proxy brief above is the supported path today.

Partner integration checklist

Changelog