Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Document Extraction Billing API
version: 1.0.0
description: 'Email sign-up at /app/api/auth/sign-up/email requires an x-turnstile-token
header in production. Failed or unavailable bot verification returns 403
with code BOT_CHECK_REQUIRED. Social sign-up is unaffected.
Documents in. Verified data out.
The public REST API (v1) turns documents (invoices, receipts, purchase
orders, bank statements, delivery notes, or custom schemas) into
structured, verified data. Every document reaches an explicit terminal
state. Every extracted table row is accounted for. Money fields are
cross-checked (crossfooting). Bank statements are balance-checked.
Every field links back to its source in the document.
Unsupported methods on registered API paths return an empty
405 Method Not Allowed response with an Allow header listing supported
methods. HEAD is supported wherever GET is registered; OPTIONS keeps its
existing preflight behavior. Unknown paths remain 404. Maintenance and
canonical-host redirects still take precedence.'
contact:
email: support@arkrel.com
servers:
- url: https://arkrel.com
description: Production, one Worker, one domain, same origin as the site itself (no separate api.<domain> host)
security:
- ApiKeyAuth: []
tags:
- name: Billing
paths:
/app/api/billing/subscription:
get:
tags:
- Billing
operationId: getBillingSubscription
summary: Read the current subscription and its actual Stripe pricing
description: Requires business membership and a signed-in session. Recurring price comes from the subscription's fixed licensed Stripe item, including its quantity and interval. Next charge comes from the open invoice with the earliest scheduled payment attempt, using its remaining balance. An open balance without a scheduled attempt has a null date. If no open balance exists, it comes from Stripe's upcoming invoice, including discounts, credits and usage. Amounts use Stripe currency minor units. Unavailable or ambiguous pricing is null and never falls back to catalog pricing. Canceling subscriptions have no upcoming renewal, but may still have an open invoice. Refund eligibility uses purchased payment evidence, independently of the current plan. Each eligible payment includes its settlement-based deadline and whether the request would be automatic or reviewed by hand. Autopilot is null when ineligible or unavailable. Catch-Up is an empty list when none are eligible, or null when payment evidence is unavailable. Fully refunded payments are omitted. Previously accepted automatic requests remain retryable after the deadline. This read does not reserve a refund; refund mutations recheck eligibility. This app session endpoint is not exposed through integrations or MCP.
security:
- SessionCookie: []
responses:
'200':
description: Subscription state with actual Stripe amounts or null when unavailable
content:
application/json:
example:
plan: autopilot
status: active
trial_end: null
current_period_end: '2026-11-01T00:00:00.000Z'
cancel_at_period_end: false
recurring_price:
amount: 4900
currency: usd
interval: month
interval_count: 1
next_charge:
amount: 3900
currency: usd
date: '2026-11-01T00:00:00.000Z'
refund_eligibility:
autopilot:
payment_intent_id: pi_first
until: '2026-10-20T00:00:00.000Z'
automatic: true
catchup: []
schema:
type: object
required:
- plan
- status
- trial_end
- current_period_end
- cancel_at_period_end
- recurring_price
- next_charge
- refund_eligibility
properties:
refund_eligibility:
type: object
required:
- autopilot
- catchup
properties:
autopilot:
type:
- object
- 'null'
required:
- payment_intent_id
- until
- automatic
properties:
payment_intent_id:
type: string
until:
type: string
format: date-time
automatic:
type: boolean
catchup:
type:
- array
- 'null'
items:
type: object
required:
- payment_intent_id
- until
- automatic
- tax_year
properties:
payment_intent_id:
type: string
until:
type: string
format: date-time
automatic:
type: boolean
tax_year:
type: integer
plan:
type:
- string
- 'null'
status:
type:
- string
- 'null'
trial_end:
type:
- string
- 'null'
format: date-time
current_period_end:
type:
- string
- 'null'
format: date-time
cancel_at_period_end:
type: boolean
recurring_price:
type:
- object
- 'null'
required:
- amount
- currency
- interval
- interval_count
properties:
amount:
type: integer
description: Fixed recurring amount in Stripe currency minor units including quantity.
currency:
type: string
interval:
type: string
enum:
- day
- week
- month
- year
interval_count:
type: integer
minimum: 1
next_charge:
type:
- object
- 'null'
required:
- amount
- currency
- date
properties:
amount:
type: integer
description: Open invoice remaining balance or upcoming invoice amount due in Stripe currency minor units.
currency:
type: string
date:
type:
- string
- 'null'
format: date-time
description: Scheduled payment attempt or upcoming renewal date. Null when an open invoice has no scheduled attempt.
'401':
description: Sign-in required
'403':
description: Business membership or account protection required
/app/api/billing/plans:
get:
tags:
- Billing
operationId: getBillingPlans
summary: List bookkeeping plans currently offered
description: Public sales catalog. No free trial. Business is omitted unless BUSINESS_PLAN_AVAILABLE is 1. Existing Business entitlements are unaffected.
security: []
responses:
'200':
description: Available subscription plans and the Catch-Up offer
content:
application/json:
example:
plans:
- id: free
name: Free
monthly_price_usd: 0
trial_days: null
- id: autopilot
name: Autopilot
monthly_price_usd: 59
trial_days: null
catchup:
price_usd: 599
refund_window_days: 30
schema:
type: object
required:
- plans
- catchup
properties:
plans:
type: array
items:
type: object
required:
- id
- name
- monthly_price_usd
- trial_days
properties:
id:
type: string
enum:
- free
- autopilot
- business
name:
type: string
monthly_price_usd:
type: number
trial_days:
type: integer
nullable: true
catchup:
type: object
required:
- price_usd
- refund_window_days
properties:
price_usd:
type: number
refund_window_days:
type: integer
/app/api/billing/checkout:
post:
tags:
- Billing
operationId: createBillingCheckout
security:
- SessionCookie: []
summary: Start a monthly subscription checkout
description: Requires an owner or admin session and recent step-up authentication. Autopilot checkout contains only the flat $59 monthly price with 1,500 included pages; extra capacity uses optional one-time page packs. Business checkout retains its overage meter. No free trial. The first charge has a 30-day money-back guarantee. Business returns 409 BUSINESS_PLAN_UNAVAILABLE unless BUSINESS_PLAN_AVAILABLE is 1, even when its Stripe price is configured. This app session endpoint is not exposed through integrations or MCP.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- plan
properties:
plan:
type: string
enum:
- autopilot
- business
responses:
'200':
description: Checkout session URL
content:
application/json:
example:
url: https://checkout.stripe.com/c/pay/example-session
schema:
type: object
properties:
url:
type: string
'400':
description: Invalid plan
'401':
description: Session or recent step-up authentication required
'403':
description: Owner or admin role required, or TWO_FACTOR_SETUP_REQUIRED for a password account without completed protection.
'409':
description: BUSINESS_PLAN_UNAVAILABLE, ALREADY_SUBSCRIBED, or conflicting billing state
'503':
description: PLAN_UNAVAILABLE because the Stripe price is not configured
/app/api/billing/refund-autopilot:
post:
tags:
- Billing
operationId: requestAutopilotRefund
summary: Request the Autopilot first-charge money-back guarantee
description: Requires an owner or admin session and recent step-up authentication. Within 30 days of settlement, the first eligible account or card request is refunded in full automatically before any paid deliverable of any year is released after settlement within the business or its account/card guarantee scope. Historical payments without complete delivery evidence require review. Requests after delivery or prior account/card requests go to support review under the same guarantee. Eligibility follows the settled Autopilot invoice, including after subscription cancellation or a current plan change. A successful full refund cancels that subscription immediately. A failed or canceled refund returns refunded false and auto false with a manual-check message, alerts support, and releases the pending download pause without marking the refund completed. This app session endpoint is not exposed through integrations or MCP.
security:
- SessionCookie: []
responses:
'200':
description: Refund processing result or support review
content:
application/json:
example:
refunded: false
auto: false
message: Your request has been sent to support for review.
schema:
type: object
required:
- refunded
- auto
- message
properties:
refunded:
type: boolean
auto:
type: boolean
message:
type: string
'400':
description: NO_AUTOPILOT_PAYMENT for this business
'401':
description: Session or recent step-up authentication required
'403':
description: Owner or admin role required, or business deletion in progress
'409':
description: REFUND_WINDOW_EXPIRED or PAYMENT_UNRESOLVED
/app/api/billing/checkout-pack:
post:
tags:
- Billing
operationId: createPagePackCheckout
security:
- SessionCookie: []
summary: Start or reuse a page pack checkout
description: Requires an owner or admin session and recent step-up authentication. Concurrent requests and retries for the same organization and pack reuse one reserved Stripe session until expiration or completed payment. Different pack sizes have separate reservations. This app session endpoint is not exposed through integrations or MCP.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- code
properties:
code:
type: string
enum:
- pack_100
- pack_500
- pack_2000
responses:
'200':
description: New or reused Checkout URL
content:
application/json:
example:
url: https://checkout.stripe.com/c/pay/cs_test_example
schema:
type: object
required:
- url
properties:
url:
type: string
'400':
description: INVALID_PACK or malformed JSON
'401':
description: Session or recent step-up authentication required
'403':
description: Owner or admin role required, or TWO_FACTOR_SETUP_REQUIRED
'404':
description: Organization not found
'503':
description: PACKS_UNAVAILABLE
/app/api/billing/webhook:
post:
tags:
- Billing
operationId: receiveStripeBillingEvent
summary: Receive signed Stripe billing events
description: An unfinished processing lease returns 503 so Stripe retries. Completed events return 200. Missing or invalid Stripe signatures return 400.
parameters:
- name: Stripe-Signature
in: header
required: true
description: Stripe timestamp and signature for the exact raw request body, signed with the endpoint secret.
schema:
type: string
minLength: 1
security: []
responses:
'200':
description: Event completed or already completed.
'503':
description: WEBHOOK_BUSY or MAINTENANCE_MODE. Retry after the indicated delay.
headers:
Retry-After:
schema:
type: integer
'400':
description: Invalid event, MISSING_SIGNATURE, or INVALID_SIGNATURE.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Processing failed. Retry delivery.
components:
schemas:
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
field:
type: string
securitySchemes:
BusinessSession:
type: apiKey
in: cookie
name: better-auth.session_token
description: Better Auth session cookie. Mutations also require a same-origin Origin header.
EngineToken:
type: apiKey
in: header
name: X-Engine-Token
description: Shared operator token for internal maintenance.
SessionCookie:
type: apiKey
in: cookie
name: __Host-arkrel_session
description: Signed-in app session. Mutations also require a same-origin request. Sensitive actions by accounts with a password without completed protection receive 403 TWO_FACTOR_SETUP_REQUIRED as described in x-app-account-protection. The free first look and account deletion remain available.
ApiKeyAuth:
type: http
scheme: bearer
description: 'API key shown once at creation, e.g. `sk_live_...` / `sk_test_...`.
Stored server-side as a salted hash; only the prefix is retrievable
afterward.
API keys and MCP credentials are checked against their creating user on every request. If that user has a password without enabled TOTP, requests return HTTP 403 TWO_FACTOR_SETUP_REQUIRED. Organization/service keys with no creating user keep their existing behavior.
'
x-webhook-delivery-payload:
$ref: '#/components/schemas/WebhookDeliveryPayload'
x-app-email-signup:
path: /app/api/auth/sign-up/email
method: POST
header: x-turnstile-token
status: 403
code: BOT_CHECK_REQUIRED
description: A fresh single-use Turnstile token with action signup and hostname matching APP_BASE_URL is required in production. Missing, invalid, expired, or unavailable verification fails closed. Reset the widget after each submission. Google sign-up is unaffected. Local development without a configured secret does not require a challenge. This route is served by the mounted Better Auth handler.
x-app-account-protection:
status: 403
code: TWO_FACTOR_SETUP_REQUIRED
response:
$ref: '#/components/responses/TwoFactorSetupRequired'
description: 'Password accounts require verified TOTP before checkout or billing changes, reports and exports (PDF, CSV, accountant CSV, QuickBooks, Xero, OFX, JSON downloads, statement exports and data ZIP), share creation and use, API keys and MCP, bank or ledger connections, team changes, email/password changes, inbound sender allowlist changes, callback secrets, and uploads with webhook_url. Uploads that would consume paid page credits or record billable overage also return TWO_FACTOR_SETUP_REQUIRED before storage. Included monthly and purchased Catch-Up allowances remain available. Admission reserves pending pages, and settlement rechecks live protection against actual processed pages. Chart-of-accounts sync and all chart writes require protection; stored chart and categorization-settings reads do not contact a ledger provider. Session uploads with a callback return TWO_FACTOR_SETUP_REQUIRED before storing or scheduling the document when the password account needs setup. The same refusal applies when the business has an active saved outbound webhook, even if webhook_url is omitted. Queued webhook dispatch checks live creator and document-uploader protection before sending, including retries. Existing role, entitlement and step-up requirements remain. Linked passkeys or providers do not exempt password accounts. Passwordless accounts keep existing rules. Email verification remains required. Sign-up and sign-in do not redirect to setup. The free first look stays open: one statement upload or email-in, processing, merchant review, rules, My year and locked report previews, billing/pricing views, profile and business name, sign-out, and account deletion with its existing step-up. Sensitive actions prompt inline and resume after setup. Direct /protect-account links remain supported. Other app routes default to protection. Exemptions use explicit methods and complete route patterns; business settings changes other than name-only renames, session revocation, provider linking and token access require protection. Implicit same-email provider linking is disabled: sign in with the password first, protect the account and pass step-up, then link explicitly. Explicit linking and passkey registration require fresh step-up and recheck at credential creation or verification. Already-linked provider sign-in and first-time provider signup remain available. Authentication, recovery and TOTP enrollment ceremonies remain available. Credential mutation routes require protection, including passkey registration options and verification. OAuth and passkey removal also require fresh step-up (401 STEP_UP_REQUIRED). Password credential unlinking is refused with 403 PASSWORD_REMOVAL_NOT_ALLOWED even after enrollment and step-up, preserving the password account protection requirement. The server reads live enrollment. API keys and MCP credentials retain their creator check; creatorless service keys retain existing behavior. Share links created by an unprotected password account remain unavailable.'
open_workflows:
- Free first look and locked report preview
- Billing and pricing views
- Profile name and sign-out
- Account deletion with existing step-up
- Authentication and protection enrollment
session_status:
path: /app/api/auth/me
rate_limits:
window_seconds: 60
per_session: 180
per_ip: 600
status: 429
retry_header: Retry-After
description: Independent read budgets. The IP budget precedes session resolution; the session budget uses the resolved session ID before membership and protection reads. These reads do not consume credential budgets.
field: two_factor_setup_required
schema:
type: boolean
description: Present on authenticated responses. True means sensitive actions require enrollment; it does not block the free first look or redirect sign-in. Absent when user is null.
x-app-account-deletion:
description: An account deletion intent (pending, processing, or failed) ends access immediately, including while financial obligations delay purge. All user sessions are revoked atomically with the intent, along with user-created API keys, share links, invitations, webhooks and inbound email addresses across every business. Better Auth lookups hide retained identities and their credentials. Validation, reset, verification and challenge errors follow the native unknown-user or unknown-token behavior, including validation order and password work. Anonymous sign-up uses the generic duplicate response without sending mail or creating credentials. OAuth cannot recreate a reserved identity. Credential inserts, updates and deletes are fenced against deletion at SQL execution time. Old session and two-factor challenge cookies are ignored on the request. Deletion never sends cookie expirations, so delayed responses cannot erase another login. Auth revocation expires sessions that anchor Plaid compensation operations and retains their rows until those operations are removed by their own lifecycle. Step-up and invite acceptance return the existing unauthenticated HTTP 401 response. Removed magic-link endpoints remain HTTP 404 for everyone. The email is reserved until purge completes. Business-only deletion retains the login and other businesses, but hides and blocks the deleting business immediately, including while billing leases drain. API keys for deleting businesses return unauthenticated HTTP 401.
x-app-step-up:
window_seconds: 600
description: 'Sensitive app actions require fresh identity verification. GET /app/api/auth/step-up returns password, code, email, passkey, google, microsoft and fresh booleans. POST /app/api/auth/step-up accepts exactly one of password, code (TOTP/backup), or emailCode. POST /app/api/auth/step-up/email sends a six-digit code to the verified email of a passwordless account, at most three times per ten minutes per user. Codes are hashed, single-use, expire after ten minutes, permit five attempts, and are bound to the initiating live session, user, email and step-up purpose. Resending invalidates the previous code. Verification is rate-limited. Passkey ceremonies require x-arkrel-step-up: 1 on both challenge issuance and verification, biometric/PIN user verification, and a server-side purpose, user and session binding that expires after five minutes. Consumption requires the exact initiating live session. Provider users call sign-in/social with a linked google provider and additionalData.stepUp=true. The server rejects idToken shortcuts and binds OAuth state to the original user/session for five minutes. Google cannot force reauthentication and is opportunistic only. It requires a back-channel auth_time between initiation and completion; token issuance time never counts. Missing, stale or future auth_time is rejected. Passwordless users can use an email code or a registered passkey when Google cannot verify freshness. Successful passkey/provider verification rotates and elevates only the returning bound session. Password, TOTP and email checks elevate the initiating session. These app-only auth surfaces are not exposed by integrations or MCP.'
x-consumer-statement-admission:
description: App uploads and inbound email share one Free statement allowance per account. Additional app uploads return 402 FREE_STATEMENT_USED. Inbound attachments wait for an upgrade. Retries recover the original admitted attachment. Developer API per-page pricing is unchanged.
x-maintenance-bridge:
description: 'During the production cutover, an isolated maintenance Worker returns HTTP 503 for every method and path, including reads and health checks, with Retry-After: 60 and Cache-Control: no-store. API, MCP, internal, and webhook paths return error.code MAINTENANCE and error.message "Arkrel is updating. Please try again in a few minutes." MCP receives this plain JSON error instead of JSON-RPC while the bridge is deployed. Other paths return HTML. HEAD returns headers without a body. Retry after the indicated delay.'
x-maintenance-mode:
description: 'MAINTENANCE_MODE=1 freezes mutations across app, REST, MCP and engine routes. Mutations and OAuth or verification callbacks return 503 with Retry-After: 60. REST errors use code MAINTENANCE_MODE. MCP tool mutations use JSON-RPC code -32004. Reads, health and status remain available. Read-time refresh, audit, counters and automatic categorization are suspended. Cron writes are skipped; inbound email invocations fail before ingestion so delivery can be retried.'
x-stripe-billing-webhook:
path: /app/api/billing/webhook
authentication: Stripe-Signature
refund_events:
- charge.refunded
- refund.updated
- refund.failed
dispute_events:
- charge.dispute.created
- charge.dispute.updated
- charge.dispute.closed
description: Refund IDs and provider statuses are persisted. Catch-Up access and unused page credits are revoked only after a succeeded refund. Pending or failed refunds retain access. The dashboard refund response has refunded=false while an automatic refund is pending or failed, with auto=true indicating that the automatic request was submitted. Disputes suspend the charged subscription, Catch-Up year, or unused page credits. A won dispute restores only the saved access and original credit expiration, unless the payment was refunded or another dispute still holds it. Lost disputes remain suspended. Subscription updates cannot bypass a hold. Independent AppSumo codes are unaffected. The owner receives an operational email alert.
x-app-catchup-payment-clock:
path: /app/api/usage
field: catchup_purchases
items:
type: object
required:
- tax_year
- purchased_at
- payment_settled_at
- expires_at
properties:
tax_year:
type: integer
purchased_at:
type: string
format: date-time
description: Purchase record time. Do not use as an unresolved payment clock fallback.
expires_at:
type: string
format: date-time
description: Access and unused pages end at this instant, 12 months after settlement. Older test rows use their purchase timestamp until settlement is reconciled.
payment_settled_at:
type: string
format: date-time
nullable: true
description: Confirmed payment charge time, or null while confirmation is unresolved. The 30-day guarantee starts at this time.