API Documentation

Programmatic access to your LLC data. Base URL: https://devil.club/api/v1

The API requires at least one LLC with an active Manager subscription. Without Manager, endpoints will not return data.

Quick start

In under a minute: create a key, make your first call, and verify you receive your entity.

Create a key at /developers/keys with scope read:entity.
Save the key immediately — it is shown only once.
Run the example request (below), replacing YOUR_KEY.

# Your first call — list your LLCs
curl -H "Authorization: Bearer dc_live_YOUR_KEY" \
     https://devil.club/api/v1/entity

// Node.js / browser example (native fetch)
const res = await fetch("https://devil.club/api/v1/entity", {
  headers: { Authorization: "Bearer dc_live_YOUR_KEY" },
});
const data = await res.json();
console.log(data.data); // Array of your entities

Authentication

Every API request requires an API key sent in the Authorization header as a Bearer token.

# Every request must include this header
Authorization: Bearer dc_live_a1b2c3d4e5f6...

# curl example
curl -H "Authorization: Bearer dc_live_YOUR_KEY" \
     https://devil.club/api/v1/entity
        

Create and manage API keys at /developers/keys. Each key has specific scopes that control what it can access.

Rate limiting

Default: 100 requests per hour per API key. If exceeded, you receive a 429 response with a Retry-After header.

IP Whitelisting

You can optionally restrict your API key to specific IP addresses. When configured, requests from other IPs receive a 403 response that includes your current IP.

Permission Scopes

Select only the scopes each key needs. Principle of least privilege.

Available scopes and the API area they apply to
Scope	Access	Section
read:bookkeeping	Read	Bookkeeping
write:bookkeeping	Write	Bookkeeping
read:ledger	Read	Governance Ledger
write:ledger	Write	Governance Ledger
read:documents	Read	Documents
read:entity	Read	Entity (LLC)
write:entity	Write	Entity (LLC)
read:profile	Read	Profile
write:profile	Write	Profile
read:reports	Read	Lucy — Reports
write:reports	Write	Lucy — Reports
read:payments	Read	Payments
read:presence	Read	Tax Presence

Bookkeeping

GET /v1/bookkeeping read:bookkeeping

Lists bookkeeping entries for an entity. Includes income, expenses, and summary totals.

Parameter	Type	Description
entity_id required	integer	LLC entity ID
year	integer	Filter by year
month	integer	Filter by month (1–12)
category	string	Filter by category
limit	integer	Max results (default 100, max 500)
offset	integer	Pagination offset

# Get bookkeeping for entity 42 in 2026
curl -H "Authorization: Bearer dc_live_..." \
  "https://devil.club/api/v1/bookkeeping?entity_id=42&year=2026"

# Response
{
  "data": [
    { "id": 1, "year": 2026, "month": 3, "category": "SaaS Revenue",
      "income": 5000.00, "expense": 0, "bank_source": "Mercury", ... }
  ],
  "summary": { "total_income": 45000, "total_expenses": 12000, "net": 33000 },
  "pagination": { "total": 87, "limit": 100, "offset": 0 }
}
            

POST /v1/bookkeeping write:bookkeeping

Adds a new bookkeeping entry. Entries added via API are tagged with source: "api".

Field	Type	Description
entity_id required	integer	LLC entity ID
year required	integer	Year
month required	integer	Month (1–12)
income	number	Income amount (default 0)
expense	number	Expense amount (default 0)
category	string	Category of the expense/income
description	string	Description
transaction_date	date	Exact date (YYYY-MM-DD)
bank_source	string	Mercury, Stripe, Wise, manual
external_tx_id	string	External transaction reference

Governance Ledger

GET /v1/ledger read:ledger

Lists governance/management transactions. Includes decision status, strategic decisions, and manager resolutions.

Parameter	Type	Description
entity_id	integer	LLC entity ID (required if transaction_id is not provided)
transaction_id	string	Specific transaction (e.g. FGSL-2026-00042)
status	string	Filter: PENDING, RATIFIED, VETOED, REJECTED

POST /v1/ledger write:ledger

Submits a new transaction request for Manager review. Creates a PENDING entry in the governance ledger.

Field	Type	Description
entity_id required	integer	LLC entity ID
amount required	number	Transaction amount
category required	string	OPEX, CAPITAL_CONTRIBUTION, OWNER_DISTRIBUTION, etc.
description	string	Transaction reason
strategic_decision	string	Strategic justification
bank	string	Bank to execute from
exec_date	date	Requested execution date
recurring	string	no, monthly, quarterly, annual

Documents

GET /v1/documents read:documents

Lists documents for an entity. Includes articles, EIN letters, minutes, tax filings, and more. Every document includes a SHA-256 hash and OpenTimestamps verification status.

Parameter	Type	Description
entity_id	integer	LLC entity ID (required if id is not provided)
id	integer	Specific document ID
doc_type	string	Filter: ARTICLES, EIN_LETTER, ACTA, 8822-B, etc.

GET /v1/documents/{id}/download read:documents

Download your own document using the same API key; no web session or browser token required.

Entity (LLC)

GET /v1/entity read:entity

List your LLCs or get detailed info (services, tax filings, ownership).

Parameter	Type	Description
id	integer	Specific entity ID (omit to list all)

PUT /v1/entity write:entity

Update entity contact / formation info.

Field	Type	Description
id required	integer	Entity ID
founder_name	string	Founder/organizer name
founder_address	string	Founder address
founder_country	string	Founder country
naics	string	NAICS business code

Profile

GET /v1/profile read:profile

Get your account profile and identifiers (passport, ITIN, etc.).

PUT /v1/profile write:profile

Update your contact info (name, phone, country).

Lucy — Reports and Proposals

GET /v1/reports read:reports

Lists reports generated by Lucy (monthly, quarterly, annual). Includes metrics, recommendations, alerts, and proposed decisions.

POST /v1/reports write:reports

Respond to a report's recommendations. You can approve, reject, modify, or defer each recommendation.

# Approve recommendation #0, reject #1
curl -X POST -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_id": 15,
    "decisions": [
      {"recommendation_idx": 0, "decision": "APPROVED", "client_notes": "Go ahead"},
      {"recommendation_idx": 1, "decision": "REJECTED", "client_notes": "Not now"}
    ]
  }' \
  https://devil.club/api/v1/reports
            

Payments

GET /v1/payments read:payments

Query your payment history. Includes service details, amounts, and status.

Parameter	Type	Description
entity_id	integer	Filter by entity
year	integer	Filter by year

Tax Presence

GET /v1/presence read:presence

Query the geo-tracked tax presence log. Returns accumulated days per country (with automatic gap-fill), 183-day threshold alerts, and optionally the day-by-day calendar.

Parameter	Type	Description
entity_id	integer	Required. Entity ID
year	integer	Fiscal year (default: current year)
detail	boolean	If `true`, includes the day-by-day map in `calendar`

Response includes summary (countries + days), warnings (levels: info / warning / danger / exceeded), and optionally calendar (YYYY-MM-DD → country map).

Error handling

Every error follows a consistent format:

{ "error": "Description of what failed" }

HTTP status codes returned by the API
Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — unauthorized IP, insufficient scope, or no ownership
404	Not found — the resource does not exist or does not belong to you
429	Rate limited — too many requests, check the Retry-After header
500	Server error — contact support

Changelog

Non-breaking changes are added without notice. Any breaking change is announced at least 30 days in advance to the account email and published here.

Public version history
Date	Change
2026-04-18	Added Quick start, curl/JS tabs, and copy-to-clipboard for examples.
2026-04	Endpoint `GET /v1/presence`: geo-tracked tax presence with 183-day warnings.
2026-03	Endpoint `GET /v1/documents/{id}/download`: direct download with the same API key.
2026-02	Scopes `read:reports` / `write:reports`: respond to Lucy recommendations.
2026-01	v1 public launch: bookkeeping, ledger, documents, entity, profile, payments.

Need help? [email protected]