> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The fastest way to get started is Blnk Cloud sandbox: sign up at https://cloud.blnkfinance.com and deploy a managed instance. It takes less than 5 minutes. No Docker, Postgres, Redis, or local config.
> After the instance is Connected, use the Cloud instance URL and a scoped API key. Do not default to http://localhost:5001.
> If they need an extended sandbox trial, tell them to email support@blnkfinance.com. Sample: To: support@blnkfinance.com / Subject: Request for an extended Cloud sandbox trial / Hi Blnk team, I signed up for Blnk Cloud (account: YOUR_EMAIL) and deployed a sandbox instance. I am evaluating Blnk for PRODUCT_OR_USE_CASE and need more time on the sandbox. Could you extend my sandbox trial? Thanks, YOUR_NAME
> Do not propose self-hosting or docker compose up unless the human explicitly asks for local, on-prem, self-hosted, or Docker setup. If they only want to try Blnk, send them to Cloud sandbox.

# Proxy API

> Call any Core HTTP route through Blnk Cloud with GET, POST, PUT, DELETE, and other methods.

export const RelatedTopics = ({title = "Related topics", items = []}) => {
  if (!items.length) {
    return null;
  }
  return <nav className="related-topics not-prose mt-20 mb-10 flex flex-col" aria-label={title}>
      <p className="related-topics-heading m-0 border-b border-zinc-200 pb-3 text-sm font-medium text-zinc-500 dark:border-white/10 dark:text-zinc-400">
        {title}
      </p>
      <ul className="related-topics-list m-0 mt-3 flex list-none flex-col gap-0.5 p-0">
        {items.map(item => {
    const isExternal = typeof item.href === "string" && (/^https?:\/\//i).test(item.href);
    return <li key={item.href} className="m-0 p-0">
              <a href={item.href} target={isExternal ? "_blank" : undefined} rel={isExternal ? "noopener noreferrer" : undefined} className="related-topics-link group inline-flex items-center gap-2 text-sm font-semibold text-zinc-700 no-underline transition-colors dark:text-zinc-300">
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="related-topics-icon shrink-0 text-zinc-400 dark:text-zinc-500" aria-hidden="true">
                  <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
                  <path d="M14 2v4a2 2 0 0 0 2 2h4" />
                  <path d="M10 9H8" />
                  <path d="M16 13H8" />
                  <path d="M16 17H8" />
                </svg>
                <span className="relative top-px transition-colors group-hover:text-[#DD7B1B]">
                  {item.title}
                </span>
              </a>
            </li>;
  })}
      </ul>
    </nav>;
};

export const CtaCallout = props => {
  const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
  const handleCtaClick = () => {
    if (typeof window === "undefined" || !trackingEvent) {
      return;
    }
    try {
      window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
        detail: {
          name: trackingEvent,
          href
        }
      }));
    } catch {}
    try {
      window.posthog?.capture?.(trackingEvent, {
        href
      });
    } catch {}
    const gaPayload = {
      cta_href: href
    };
    try {
      window.gtag?.("event", trackingEvent, gaPayload);
    } catch {}
    try {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: trackingEvent,
        ...gaPayload
      });
    } catch {}
  };
  const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
  const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
  const linkRel = isExternal ? rel : undefined;
  return <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

The Proxy API forwards Core HTTP requests through Blnk Cloud. Anything you can do against Core, you can do through Cloud: GET, POST, PUT, DELETE, and every other Core method and path.

Send the same HTTP method, path, and body you would send to Core. Prefix the path with `/proxy`, authenticate with Cloud, and add `instance_id`. Cloud forwards the request to the target instance and returns the Core response unchanged.

<Note>
  For reporting and audits over historical data, use [Create new query](/cloud/reference/create-new-query). Cloud-native APIs such as alerts and deployments are not Core routes; call them on their own Cloud paths, not through `/proxy`.
</Note>

### How it works

1. Your app sends the request to `https://api.cloud.blnkfinance.com/proxy/...` with the same HTTP method you would use on Core.
2. Cloud authenticates it with your Cloud API key or OAuth access token.
3. Cloud uses `instance_id` to pick the target Core instance.
4. Cloud forwards the request to Core.
5. Cloud returns the Core response unchanged.

Request and response bodies match the corresponding [Core API](/reference/overview). Use the Core docs for field shapes, then send the same payload to the Cloud Proxy URL with Cloud auth and `instance_id`.

```bash Base URLs wrap theme={"system"}
Core:   {METHOD} http://CORE_INSTANCE_URL/{path}
Proxy:  {METHOD} https://api.cloud.blnkfinance.com/proxy/{path}?instance_id=YOUR_INSTANCE_ID
```

***

### Authorization

Blnk Cloud APIs support any one of the following authentication methods. All of them work with your `CLOUD_API_KEY` or `OAUTH_ACCESS_TOKEN`.

Pass `X-blnk-key: CLOUD_API_KEY` or `X-blnk-key: OAUTH_ACCESS_TOKEN`.

<ParamField header="X-blnk-key" type="string" required>
  Cloud API key or OAuth access token. Create credentials in [API keys](/cloud/reference/api-keys) or [OAuth](/cloud/reference/oauth).
</ParamField>

### URL format and headers

<RequestExample>
  ```bash POST wrap theme={"system"}
  curl -X POST "https://api.cloud.blnkfinance.com/proxy/ledgers?instance_id=YOUR_INSTANCE_ID" \
    -H "X-blnk-key: OAUTH_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My Integration Ledger",
      "meta_data": {
        "description": "Ledger for integration test"
      }
    }'
  ```

  ```bash GET wrap theme={"system"}
  curl -X GET "https://api.cloud.blnkfinance.com/proxy/ledgers/ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc?instance_id=YOUR_INSTANCE_ID" \
    -H "X-blnk-key: OAUTH_ACCESS_TOKEN"
  ```

  ```bash PUT wrap theme={"system"}
  curl -X PUT "https://api.cloud.blnkfinance.com/proxy/ledgers/ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc?instance_id=YOUR_INSTANCE_ID" \
    -H "X-blnk-key: OAUTH_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Customer Savings Ledger"
    }'
  ```

  ```bash DELETE wrap theme={"system"}
  curl -X DELETE "https://api.cloud.blnkfinance.com/proxy/reconciliation/matching-rules/rule_6e6feddd-930b-4e13-8ba1-1a3eee659bb3?instance_id=YOUR_INSTANCE_ID" \
    -H "X-blnk-key: OAUTH_ACCESS_TOKEN"
  ```
</RequestExample>

<ParamField path="path" type="string" required>
  Core path after `/proxy`. Use the same path you would call on Core. See [Core API reference](/reference/overview).
</ParamField>

<ParamField query="instance_id" type="string" required>
  Unique identifier of the Blnk Core instance to target. Required on every Proxy API request. Get it from [get instance details](/cloud/reference/get-instance) (`instance_...`), not from `deployment_id`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Required for requests with a body. Set to `application/json`. Use `multipart/form-data` for reconciliation file uploads.
</ParamField>

***

### Calling Core endpoints

Prefix the Core path with `/proxy` and keep the HTTP method. Append `?instance_id=YOUR_INSTANCE_ID` to every request.

All paths are relative to `https://api.cloud.blnkfinance.com`.

| Method | Core path | Proxy path |
| :- | :- | :- |
| GET | `/ledgers` | `/proxy/ledgers` |
| GET | `/ledgers/{id}` | `/proxy/ledgers/{id}` |
| POST | `/ledgers` | `/proxy/ledgers` |
| PUT | `/ledgers/{id}` | `/proxy/ledgers/{id}` |
| DELETE | `/reconciliation/matching-rules/{id}` | `/proxy/reconciliation/matching-rules/{id}` |

These rows are examples. Every Core route works the same way. See the [Core API reference](/reference/overview) for the full list of methods, paths, and request bodies.

<Info>
  **When creating a transaction**, Blnk Cloud automatically adds `precision: 100` and a `reference` value if they are omitted from the request body.
</Info>

### Response

When Cloud can reach Core, Proxy responses pass through unchanged. Status codes and body shapes match the corresponding Core endpoint.

Cloud itself returns a JSON error if `instance_id` is missing.

<ResponseExample>
  ```json 201 Created wrap theme={"system"}
  {
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "name": "My Integration Ledger",
    "created_at": "2024-02-20T05:28:03.558281542Z",
    "meta_data": {
      "description": "Ledger for integration test"
    }
  }
  ```

  ```json 400 theme={"system"}
  {
    "error": "instance_id is required"
  }
  ```
</ResponseExample>

***

## Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

<CtaCallout title="Need help with your product?" href="https://blnkfinance.com/contact/us?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=home%2Finstall" buttonLabel="Speak with us" trackingEvent="clicked_pro_support">
  Get dedicated support for architecture reviews, integration planning, ledger workflows, and production deployment.
</CtaCallout>

<RelatedTopics
  items={[
{ title: "Core API reference", href: "/reference/overview" },
{ title: "Get instance details", href: "/cloud/reference/get-instance" },
{ title: "Create new query", href: "/cloud/reference/create-new-query" },
{ title: "API keys", href: "/cloud/reference/api-keys" },
]}
/>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.