API Reference · v2026-04-24

The Archie Connect API

A REST surface over everything Archie does, generated from the live registry. When a capability ships, this spec regenerates and the docs follow. Every call takes a bearer token.

https://api.dev.arch.ieDownload OpenAPI

The spec is OpenAPI 3.1. Import it straight into Postman or Insomnia by pasting https://api.dev.arch.ie/openapi.json into the import dialog, no separate collection to maintain.

188

operations

resource groups

169

schemas

Conventions

Authentication

Every request carries an API key in the Authorization header. Test keys are isolated from live data and carry their own credit cap. Mint a key, or read the full Authentication guide.

Errors

Errors return a consistent envelope. Branch on code, and quote correlation_id when you contact support. The full table lives in Error handling.

400Bad requestMalformed body or missing field.

401UnauthorizedMissing or invalid key.

403ForbiddenValid key, insufficient scope.

404Not foundDoes not exist, or no access.

422UnprocessableUnderstood but failed validation.

429Rate limitedHonour Retry-After.

5xxServer errorRetry with backoff.

Rate limiting

Limits are per key, per minute. The REST surface allows 60 req/min; the MCP connector allows 300. Every response carries the headers below.

X-RateLimit-LimitMaximum requests in the current window.

X-RateLimit-RemainingRequests left in the window.

X-RateLimit-ResetUnix timestamp when the window resets.

Retry-AfterSeconds to wait after a 429.

Versioning

Pin a version with the Archie-Version header; omit it for the latest. Breaking changes are dated and announced under Versioning.

first call

curl https://api.dev.arch.ie/api/v1/skills/messages.create/invoke \
  -H "Authorization: Bearer $ARCHIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Reconcile the bank for Growthwise to 31 March."}'

The reply carries content, citations, and a correlation_id linking the full audit trail.

Resource

WorkStreams

guide

WorkStream templates, Workplans (a template bound to a client), Cycles (executions), and Tasks. Inline and containerized execution modes share this surface. Replaces the retired playbooks API.

Resource

WorkStreams Cycles

Launch, track, and resolve WorkStream cycle executions.

post/api/v1/workstreams/cycles/{cycle_id}/abandonAbandon a paused cycleWrite post/api/v1/workstreams/cycles/{cycle_id}/tasks/{task_id}/guideProvide guidance to unblock a taskWrite

Resource

WorkStreams Drafts

Draft a WorkStream conversationally before you commit it.

get/api/v1/workstream-draftsList DraftsRead-only get/api/v1/workstream-drafts/{draft_id}Get DraftRead-only post/api/v1/workstream-draftsCreate DraftWrite post/api/v1/workstream-drafts/{draft_id}/commitCommit DraftWrite patch/api/v1/workstream-drafts/{draft_id}Update DraftWrite delete/api/v1/workstream-drafts/{draft_id}Abandon DraftWrite

Resource

WorkStreams Studio

Author and refine WorkStream blueprints in Studio.

get/api/v1/studio/capabilitiesGet Studio capabilities for current userRead-only

Resource

Connect Keys

Create, list, and revoke the API keys that authenticate Connect requests.

get/api/v1/connect-keysList API keys for the caller's organizationRead-only get/api/v1/connect-keys/_helpers/permission-catalogPermission catalog for key creation (derived from the skills registry)Read-only get/api/v1/connect-keys/_helpers/workspacesList workspaces in the caller's organization (for portal key-pin dropdown)Read-only get/api/v1/connect-keys/{key_id}Get a single API key (merged WorkOS + mirror shape)Read-only post/api/v1/connect-keysCreate a new API keyWrite post/api/v1/connect-keys/{key_id}/flush-cacheFlush the in-process WorkOS validator cache for a keyWrite post/api/v1/connect-keys/{key_id}/rotateRotate an API key (new sk_*, old expires after grace period)Write patch/api/v1/connect-keys/{key_id}Update API key metadata (name/permissions in WorkOS, the rest in mirror)Write delete/api/v1/connect-keys/{key_id}Revoke an API keyWrite

Skill

Conversations

Chat with Archie. Single or multi-turn.

post/v1/conversationsSend one turn of a conversation. Returns Archie's reply.Write

Skill

Catalogue

Discover available skills.

get/v1/skillsList skills available to the caller's workspaceRead-only

Skill

Advisory

Skill

Analysis

post/api/v1/skills/documents.analyse/invokeAnalyse an uploaded document — summarise, extract figures, classify, risk-assess.Write post/api/v1/skills/financials.analyse/invokeAnalyse client financials — variance, trend, ratio, cashflow, profitability, or working capital.Write post/api/v1/skills/portfolios.analyse/invokeAnalyse an investment portfolio — opening/closing reconciliation, FX and fair-value movements, capital gains/losses, and journal generation. Used by Family Investment Company (FIC) analysis (UK), trust accounts, personal SIPP/ISA reviews, and other wealth workstreams across UK, AU, US, CA jurisdictions. Currency-agnostic; the workstream step supplies jurisdiction-specific parameters such as the annual exempt amount.Write post/api/v1/skills/propose.qbo.tax.group.mapping/invokePropose CCH-Axcess-style tax-line mappings for the rows of a prepared QBO trial balance. Conversational — uses consult_accounting_expert + search_knowledge_base + the firm's tax-group catalog to assign each TB row a tax_code / engagement_tax_code / line_description with confidence + reasoning. Inputs: tb_rows (alpha-canonical from enrich_tb_rows) + tax_group_catalog + entity_type (1065/1120/1120S/1040). Output: 1:1 mapping list + counts + unmapped account_numbers. Does NOT render a CCH file — the deliverable is the source Caseware TB Excel with TaxCodeCode populated, rendered by the existing TB Excel generator downstream.Write

Skill

Audit

post/api/v1/skills/audit.workpaper.review/invokeAdvisory — LLM-driven; verify against authoritative sources before relying. Review an audit workpaper — completeness, methodology, evidence sufficiency, and standards compliance. Pairs with prepare_audit_workpaper; supports self-check, senior review, partner review, and concurring-partner review tiers.Write post/api/v1/skills/controls.test/invokeTest internal controls — design or operating effectiveness, sample selection, exceptions.Write post/api/v1/skills/reports.audit-workpaper.prepare/invokePrepare an audit working paper — lead schedules, substantive testing, planning memos, going-concern, debt confirmations, related-party.Write

Skill

Authoring

post/api/v1/skills/playbook.creator/invokeDraft a new workstream conversationally — describe a workflow and Archie produces a structured, reviewable workstream draft with typed steps, dependencies, and validation. Legacy slug retained for back-compat; prefer `workstream.draft` for new integrations.Write post/api/v1/skills/workstream.commit/invokePromote a workstream draft to an active, executable workstream definition. The draft must validate cleanly; the resulting workstream gets a new permakey and becomes runnable via workstream_run.Write post/api/v1/skills/workstream.draft/invokeDraft a new workstream conversationally — describe what you want and Archie produces a structured, reviewable workstream definition with typed steps, dependencies, and validation. Produces unified drafts targeting either inline or containerized execution mode. The canonical drafting entry; the legacy `playbook.creator` slug is retained only for API back-compat.Write

Skill

Communication

post/api/v1/skills/communications.draft/invokeDraft a client communication — email, letter, memo, or report.Write post/api/v1/skills/meeting.followup/invokeExtract action items, decisions, and a follow-up email draft from a meeting transcript or uploaded recording. Read-only — the user reviews and sends the draft. Pairs with meeting.prep.Write post/api/v1/skills/meeting.prep/invokeProduce a pre-meeting briefing for a client meeting — recent topics, open action items, talking points, suggested questions. Read-only; pairs with meeting.followup for the post-meeting half.Write

Skill

Compliance

post/api/v1/skills/compliance.deadline.calendar/invokeProduce a structured calendar of upcoming filing/compliance deadlines for a client over a window. Covers tax returns, BAS/VAT/GST, payroll/STP/RTI, annual returns, audit requirements, super/pension, and board meetings. Read-only — the user or a workstream cycle acts on each entry separately.Write

Skill

Data

post/api/v1/skills/clients.financials.get/invokeGet client financial data (raw, summary, variance, cashflow, or profitability view).Write post/api/v1/skills/payroll.data.get/invokeGet payroll data — summary, by employee, by period, tax/super obligations.Write

Skill

Forensic

post/api/v1/skills/anomalies.investigate/invokeForensic investigation — Benford's Law, ACFE classification, chain-of-custody output.Write post/api/v1/skills/assets.trace/invokeForensic asset tracing — funds flow, related-party mapping, ownership trails.Write

Skill

General

post/api/v1/skills/messages.create/invokeGeneral accounting question — fallback for anything that doesn't fit a specific skill.Write

Skill

Integrations

post/api/v1/skills/list.connections/invokeList the caller's connected accounting systems (Xero today) and their data-sync health — answers 'what am I connected to', 'is my Xero connected', 'did the sync finish'. Returns each connection's tenant name, type, status, last sync time, and per-entity sync_state (written/failed per entity). No parameters.Write

Skill

Memo

post/api/v1/skills/memos.expert.prepare/invokePrepare a litigation expert report — damages, loss quantification, opinion.Write post/api/v1/skills/prepare.asc606.memo/invokePrepare an ASC 606 revenue-recognition workpaper + memo. Supply either an uploaded contract (file_ids) OR the full contract text as scenario — the engine extracts payment streams, parties, term, and royalty tiers from the text inline. No file upload needed when scenario contains the contract text.Write

Skill

Reports

Skill

Research

post/api/v1/skills/standards.research/invokeResearch accounting standards or compare two standards on a topic.Write

Skill

Review

post/api/v1/skills/compliance.review/invokeReview a document for regulatory compliance gaps.Write post/api/v1/skills/estate.review/invokeReview wills, trusts, beneficiaries, control, and tax exposure of an estate plan.Write

Skill

Topics

Skill

Transactions

post/api/v1/skills/accounts.reconcile/invokeReconcile bank, AR, AP, intercompany, or other accounts.Write post/api/v1/skills/accruals.suggest/invokeAdvisory — LLM-driven; verify against authoritative sources before relying. Suggest month-end accruals for a client by scanning the trial balance, variance against prior periods, and recurring patterns. Read-only — produces structured suggestions for review; the user posts via record_journal_entry.Write post/api/v1/skills/journal.record/invokeRecord an accounting journal entry to Xero/QBO.Write post/api/v1/skills/transactions.classify/invokeClassify a financial transaction to chart-of-accounts code.Write

Skill

Utility

post/api/v1/skills/clients.list/invoke(Utility) List accessible clients.Write post/api/v1/skills/derive.period/invoke(Utility) Derive canonical period bounds + matching prior-period bounds from a kind discriminator + anchor date. Pure compute — same input always produces identical output. Supports BAS-AU monthly/quarterly/annual today; additional jurisdictions are new ``kind`` values.Write post/api/v1/skills/detect.tb.duplicates/invoke(Utility) Surface trial-balance rows that share an ``account_number`` (``code``) with another non-zero-balance row. Zero-balance rows are excluded from the duplicate check — a stale inactive account sharing a code with a real one does NOT poison the real one. Output is the conflict subset with ``conflict_codes`` + ``conflict_count`` added per row.Write post/api/v1/skills/enrich.tb.rows/invoke(Utility) Enrich a trial balance with auto-renumber + classification. Operates on alpha's canonical TB-row dict shape (``{code, name, section, debit, credit}``) and CoA-row dict shape (``{account_id, code, name, type, balance}``). Adds ``classification`` ∈ ``ok|auto_renumbered|dropped|needs_manual_review``, assigns Maginot-style numbers (1xxx Assets / 2xxx Liabilities / ...) to rows missing a code, flags duplicate-code collisions for manual review, drops zero-balance rows. Pure compute — same input always produces identical output. Does NOT re-implement the balance check; that remains inline at the 5 existing sites.Write post/api/v1/skills/search.query/invoke(Utility) Search the knowledge base directly.Write post/api/v1/skills/workflows.decide/invoke(Utility) Approve or reject a workflow item.Write