Artemis API Docs

What the API provides

Artemis exposes a canonical money graph for platform payments. It normalizes PSP activity, payout reports, balance ledgers, internal order and ledger data, bank cash, reserves, taxes, fees, refunds, disputes, and manual adjustments into one evidence-backed graph.

Trace every dollar

Resolve a payment, payout, ledger entry, or bank transaction into canonical entities and graph edges.

Close payout batches

Explain why a payout was that amount, which payments are inside, what evidence is missing, and whether cash landed.

Power agents safely

Return structured evidence packets with raw facts, contradictions, freshness, confidence, and recommended next actions.

Design principle: Artemis never hides the proof boundary. Provider-observed, Artemis-reconstructed, candidate, waiting, not observable, and break states stay distinct in every API response.

Core concepts

Concept	Meaning	Why agents need it
`canonical_id`	The stable Artemis identity for a money entity.	Agents can reason across aliases like charge IDs, payment IDs, balance transactions, and internal references.
`evidence_packet`	A complete investigation payload for one payment or payout.	Prevents agents from hallucinating context or querying five screens manually.
`proof_level`	Provider observed, Artemis reconstructed, candidate, missing, not observable.	Separates close-grade proof from inference.
`waiting_vs_break`	The canonical timing state for missing evidence.	Agents know when to wait, sync a source, or escalate a true exception.
`source_freshness`	How complete a PSP, bank, report, or internal feed is through time.	Late evidence is not a break until the relevant source is complete through the due window.

Authentication

Production API access uses scoped bearer tokens. Tokens are workspace-bound and can be restricted by source system, merchant account, endpoint family, and environment.

Request header

Authorization: Bearer artemis_live_...
X-Artemis-Workspace: wsp_...
X-Request-Id: optional-client-idempotency-key

Agent access: issue least-privilege tokens for AI agents. Read-only evidence packet access is usually enough for investigation agents; mutation scopes should be reserved for explicit operator workflows.

Endpoint index

GET

/v1/entities/resolve?id=py_...

Resolve any known alias into a canonical entity and aliases.

GET

/v1/evidence/payment/{payment_id}

Full payment evidence packet: graph, workpaper, lifecycle, missing evidence, contradictions, raw facts, and actions.

GET

/v1/evidence/payout/{payout_id}

Full payout evidence packet: payout workpaper, component roll-forward, composition proof, bank match, and unresolved variance.

GET

/api/graph/traverse/{entity_id}

Traverse the canonical money graph from a payment, payout, bank transaction, ledger row, or merchant.

GET

/api/lifecycle/{payment_id}

Payment close workpaper with seller payout, platform payout, bank cash, fees, tax, reversal, and timing state.

GET

/api/payouts/submerchant/{payout_id}

Submerchant payout close page and composition evidence.

GET

/api/reconciliation-cases/payout/{payout_id}

Platform payout close case with allocator, provider evidence, bank cash state, and gaps.

GET

/api/waiting

Evidence dependencies that are waiting, late but allowed, source-incomplete, or true breaks.

POST

/api/money/ask

Ask natural-language questions over the canonical money graph and evidence packets.

Canonical identity

Agents should resolve object IDs before investigation. Stripe charges, PaymentIntent IDs, payment aliases, balance transaction IDs, payout IDs, internal order IDs, and ledger references can all point to the same canonical money entity.

GET /v1/entities/resolve?id=py_...

{
  "canonical_id": "ch_3TejpSJa42zn3jCL05PFiBmG",
  "type": "payment",
  "aliases": [
    "py_1TejpWQwm2HptT74IaqUmqCV",
    "pi_3TejpSJa42zn3jCL0WuNKaJS",
    "txn_1TejpWQwm2HptT74QIV9VMNX"
  ],
  "confidence": 1.0,
  "evidence": [
    {
      "source_system": "stripe",
      "relationship": "same_payment",
      "basis": "Processor object lineage and balance transaction link"
    }
  ]
}

Evidence packets

Evidence packets are the safest way to give an agent everything needed to answer financial questions without losing the source boundary.

GET /v1/evidence/payment/{payment_id}

{
  "entity": {
    "canonical_id": "ch_...",
    "type": "payment",
    "currency": "USD",
    "amount": 2500
  },
  "graph": {
    "nodes": [],
    "edges": [],
    "missing_edges": []
  },
  "workpaper": {
    "seller_payout": {
      "status": "inferred_paid_by_psp",
      "proof_level": "artemis_inferred",
      "payout_ids": ["po_..."]
    },
    "platform_payout": {
      "payout_status": "expected",
      "bank_cash_status": "missing"
    }
  },
  "missing_evidence": [],
  "contradictions": [],
  "source_freshness": [],
  "recommended_next_actions": []
}

Close-grade rule: an agent may summarize inference, but it should only call evidence provider-observed when the packet says the provider report, payout object, bank feed, or internal ledger row was actually observed.

Payout close APIs

Payout close is the primary wedge: why is this payout this amount, which payments/refunds/fees are inside it, has cash landed, what evidence is missing, and can finance close the period?

Step 1PSP payout object

Observed from Stripe, Adyen, or another PSP payout endpoint/webhook.

Step 2Composition

Provider report if available; Artemis reconstruction when the provider does not expose direct membership.

Step 3Internal ledger

Seller payable, platform revenue, clearing, reserves, tax, and adjustment postings.

Step 4Bank cash

Matched bank/Plaid/file evidence. ETA applies only after a payout/bank rail event exists.

GET /v1/evidence/payout/{payout_id}

{
  "payout_id": "po_...",
  "scope": "platform_payout | submerchant_payout",
  "provider_evidence": {
    "payout_object_observed": true,
    "provider_composition_state": "observed | not_available | waiting"
  },
  "roll_forward": {
    "opening_balance": {},
    "charges": {},
    "fees": {},
    "refunds_disputes": {},
    "reserves_holds_releases": {},
    "fx_tax_rounding": {},
    "other_adjustments": {},
    "payout_amount": {},
    "unresolved_variance": {}
  },
  "cash_match": {
    "status": "observed | waiting | not_observable",
    "rail": "ach | wire | instant | unknown",
    "expected_arrival": null
  }
}

Waiting vs break

Artemis uses a shared evidence state machine across product pages, APIs, and agents. Timing, source completeness, business days, rails, and proof boundaries determine whether a gap is normal waiting or a true break.

State	Meaning	Agent behavior
`waiting`	Evidence is expected but still inside a normal timing window.	Do not escalate. Explain expected source and timing.
`waiting_on_source_sync`	The evidence window has passed, but the source feed is not complete through that window.	Recommend source sync or feed repair before calling a break.
`operator_controlled`	The next step depends on an operator or platform action, such as initiating a payout.	Do not provide ETA. Ask for action or confirm whether a sync is missing.
`break`	The source is complete through the expected window and evidence is still absent.	Escalate as close blocker with affected amount and source lineage.
`not_observable`	The current connected sources cannot prove the claim.	State the proof boundary and name the source needed to observe it.

Agent usage pattern

For agent workflows, use a simple sequence: resolve the identity, fetch the evidence packet, inspect missing evidence and contradictions, then produce a recommendation with citations to source facts.

Recommended agent flow

1. GET /v1/entities/resolve?id={user_supplied_id}
2. GET /v1/evidence/payment/{canonical_id}
3. If payout is referenced:
   GET /v1/evidence/payout/{payout_id}
4. Read:
   - proof_level
   - missing_evidence
   - contradictions
   - source_freshness
   - recommended_next_actions
5. Answer with:
   - conclusion
   - source-backed facts
   - uncertainty/proof boundary
   - next action

Prompting guidance: tell agents to never upgrade artemis_inferred to provider-observed proof, never convert not_observable into confirmed absence, and never provide bank arrival ETAs before a payout or bank rail event exists.

Webhooks and source ingestion

Artemis can receive PSP webhooks, ingest reports, poll provider APIs, read bank files or Plaid feeds, and sync internal databases or ledgers. Webhook event names vary by provider, but the normalized output is source-agnostic.

POST

/api/webhooks/stripe

Stripe events such as charges, transfers, payouts, refunds, disputes, balance transactions, and reporting events.

POST

/api/source-status/watermarks

Update source completeness and loaded-through timestamps for timing-aware waiting vs break decisions.

POST

/api/internal-ledger/import

Import source-backed internal ledger rows for payment and payout close.

Important schemas

Object	Key fields	Description
`CanonicalMoneyMovement`	`movement_type`, `payment_id`, `payout_id`, `amount`, `source_system`	Normalized movement from PSP, bank, internal ledger, report, or inferred reconstruction.
`EvidenceDependency`	`dependency_type`, `status`, `due_at`, `source_system`	Expected evidence tracked by the shared waiting/break state machine.
`PayoutWorkpaper`	`provider_evidence`, `roll_forward`, `cash_match`, `gaps`	Close-ready explanation of a platform or submerchant payout.
`CanonicalGraphEdge`	`source`, `target`, `relationship`, `confidence`, `basis`	Explains how two financial objects are linked and why.

Errors

API errors are structured so humans and agents can distinguish authentication failures, source freshness problems, unsupported providers, and true data absence.

Error envelope

{
  "error": {
    "code": "source_not_complete",
    "message": "Bank feed is not complete through the expected arrival window.",
    "recommended_action": "Run bank sync before escalating this item.",
    "request_id": "req_..."
  }
}

Agent-first reconciliation APIs.

What the API provides

Core concepts

Authentication

Endpoint index

Canonical identity

Evidence packets

Payout close APIs

Waiting vs break

Agent usage pattern

Webhooks and source ingestion

Important schemas

Errors