# API Reference

HTTP endpoints exposed by the Shiwake multi-tenant ledger engine.

URL: https://docs.shiwake.app/docs/api



Shiwake exposes a versioned REST API over HTTPS. Every endpoint accepts
and returns JSON, is authenticated per tenant, and wraps its payload in a
standard envelope so clients can parse successes and failures the same way.

Base URL [#base-url]

```
https://api.shiwake.example.com/api/v1
```

The API is split into two top-level namespaces:

| Namespace              | Purpose                                                                   | Auth                                                     |
| ---------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- |
| `/api/v1/ledger/...`   | Tenant-scoped ledger operations: accounts, entries, holds, reconciliation | API key ([TenantAccess](/docs/api/authentication))       |
| `/api/v1/platform/...` | Platform-admin operations: tenant CRUD, API key rotation                  | Bearer token ([PlatformAdmin](/docs/api/authentication)) |

The version segment (`v1`) is part of the URL. There is only one version
today; future breaking changes will be published under `v2` and both will
coexist during the deprecation window.

Content type [#content-type]

All request bodies must be `application/json`. Responses are always
`application/json`, even for errors.

Response envelope [#response-envelope]

Every response (success or failure) is an `ApiResponse<T>` with three
fields:

```json
{
  "code": 200,
  "message": "Retrieved successfully",
  "data": { /* resource payload */ }
}
```

<TypeTable
  type="{
  code: { type: &#x22;int&#x22;, required: true, description: &#x22;HTTP status code, duplicated in the body for convenience&#x22; },
  message: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable summary; on errors, describes what went wrong&#x22; },
  data: { type: &#x22;T | null&#x22;, required: true, description: &#x22;Resource payload on success, or the error detail object on some error codes (e.g. 422)&#x22; },
}"
/>

<Callout type="info">
  The `code` field always matches the HTTP status of the response. Clients
  can rely on either; the SDK uses it to decide whether to throw.
</Callout>

Resources [#resources]

<Cards>
  <Card title="Authentication" href="/docs/api/authentication" description="API keys, tenant resolution, and authorization policies." />

  <Card title="Idempotency" href="/docs/api/idempotency" description="Safely retry mutating requests with Idempotency-Key." />

  <Card title="Pagination" href="/docs/api/pagination" description="Cursor-based pagination across all list endpoints." />

  <Card title="Rate limiting" href="/docs/api/rate-limiting" description="Per-tenant limits and 429 responses." />

  <Card title="Errors" href="/docs/api/errors" description="Error shapes and common status codes." />

  <Card title="Accounts" href="/docs/api/accounts" description="Create accounts, read balances, and list transactions." />

  <Card title="Journal Entries" href="/docs/api/journal-entries" description="Post, read, list, and reverse double-entry journal entries." />

  <Card title="Holds" href="/docs/api/holds" description="Place, capture, and release authorization holds." />

  <Card title="Reconciliation" href="/docs/api/reconciliation" description="Trial balance and stored-vs-computed balance verification." />

  <Card title="Tenants" href="/docs/api/tenants" description="Platform-level tenant management." />
</Cards>
