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

# Agentic Installation

> Choose a Ground integration by balance ownership and signer, then validate a complete sandbox round trip with your coding agent.

This is the complete implementation handoff for a coding agent: application requirements, product procedures, recovery rules, and acceptance checks. Give your agent access to your codebase and the prompt below. Before running it, obtain a sandbox organization API key from [Ground Portal](https://portal.groundtech.co), confirm the products enabled for your organization, and prepare a test wallet with the selected network's test assets and gas. Keep API keys in server-side secrets.

## Choose the product

| Your balance and signing model | Procedure |
| - | - |
| An offchain account balance managed through Ground's API, with organization or customer signing under the configured custody model | [Portfolio Wallets](#portfolio-wallets) |
| A pooled onchain portfolio whose shareholders sign subscriptions and redemptions and hold ERC-20 shares | [MicroVaults](#microvaults) |
| A wallet holds a single source's yield token and signs transactions into its backing vault | [gTokens](#gtokens) |

MicroVaults are in private preview for enabled sandbox organizations on Ethereum Sepolia. Confirm access before choosing that procedure.

## Copy the prompt

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Implement a complete Ground sandbox integration in this codebase.
Read https://docs.groundtech.co/docs/agentic-installation in full, including
its implementation checklist, selected product procedure, and acceptance checks.
Read the linked operation guides and current OpenAPI request/response schemas
before coding their endpoints. Follow their links when an operation is conditional.

1. Inspect the application framework, existing account model, authentication,
   backend routes, database, wallet provider, signing, UI, and tests.
   Choose Portfolio Wallets, MicroVaults, or gTokens from balance ownership and
   signer responsibility. Explain the choice. Ask only for missing choices that
   change ownership, permission, fees, receiver, or fund movement. Inspect existing
   configuration before asking. Never guess credentials, enabled access, or assets.
2. Use https://sandbox.groundtech.co and its current product catalog. Verify access,
   networks, deployed interfaces, test funding, and the authorized signer.
   Never substitute production funds or networks when a sandbox flow is blocked.
3. Implement the application integration, not just discovery calls: backend API
   client and authorization, durable account/resource mapping, stable identities
   for logical writes, signer and approval flows, funding/subscription, balance
   and yield display, withdrawal/redemption, and any request/claim step.
   Reuse this repository's conventions, wallet provider, storage, and test tools.
4. Build pending/error/completed states and recovery. Persist operation identity
   before submission; restore tracking after refresh or restart. Reconcile webhooks
   and receipts with current API/onchain reads. Treat decimal amounts precisely.
   Keep API keys server-side. Do not guess contract methods or duplicate an
   uncertain operation with a new request ID or wallet transaction.
5. Run the project's relevant checks, meaningful mocked recovery tests, and a
   real sandbox funding-to-withdrawal round trip when access/funding/signing permit.
   Confirm actual assets or shares and final receiver delivery. An accepted API
   response, submitted transaction, or queued settlement is not completion.
6. Deliver changed files, setup instructions, checks run, redacted environment
   details, resource IDs, transaction hashes, initial/final balances, and evidence
   for every acceptance check. Separate mocked, simulated, confirmed, and pending
   evidence. If blocked, finish independent work, preserve resumable state, and
   state the exact prerequisite and next action. Do not claim an untested flow works.
   Optional: submit one concise redacted finding using this page's feedback section.
Do not use production funds or deploy the integration without explicit authorization.
```

## Establish the integration contract

Before coding, record these decisions in the application's integration notes. Reuse existing choices where they are explicit; surface consequential missing decisions to the developer.

| Decision | What the agent must establish |
| - | - |
| Product and ownership | Who owns the balance or shares, who can move funds, and which application account owns each resource. |
| Signing | Which organization, customer, or shareholder signs each action; how the application obtains authorization and approval. |
| Environment and access | Sandbox organization, enabled product/source, API key scopes, chain, asset, test funding, and native gas. |
| Strategy and economics | Sources, allocations, liquidity needs, fees and recipient, receiver, and allowed minimum output. Use current catalog/quotes. |
| User journey | Existing screens or backend workflow for funding, balance/yield, exit, pending settlement, approval, and failure recovery. |
| Operation storage | Where resource IDs, logical request IDs, transaction hashes/nonces, task/request IDs, and progress survive a restart. |

Use the current request and response schemas through the product's API reference tab. Resolve IDs, addresses, supported lanes, decimals, limits, and lifecycle states from the selected environment. Examples illustrate payloads; they do not establish current availability or permission. Read contract ABIs from verified deployed implementations, including the implementation behind a proxy.

## Implement the application

Build each of the following using the project's existing architecture. A script that lists sources is only the discovery check.

1. **Server API boundary.** Load the organization key from server secrets. Authorize the application's user and verify their ownership before acting on a Ground resource; the organization key alone does not establish end-user ownership. Validate inputs, return useful safe errors, and keep credentials and signing material out of client bundles and logs.
2. **Account mapping and operation persistence.** Persist the application account's Ground resource identity. Before a write, save one stable logical operation ID and payload. Track its Ground resource/task ID or onchain request and transaction evidence. Make concurrent submissions and retries resolve to that operation. API idempotency and chain transaction nonces are separate mechanisms.
3. **Funding and exit actions.** Implement the selected product's full procedure below, including access activation, approvals, address readiness, quotes, signing, and asynchronous claims. Check the chosen chain, asset, receiver, and amount immediately before signing. Decode integer units with the asset's decimals; preserve API decimal strings without floating-point rounding.
4. **Balance and progress reads.** Show confirmed balances/shares and distinguish principal, yield, and APY. Expose awaiting access, provisioning, awaiting signature/approval, submitted, pending settlement, claimable, completed, and failed states when the product actually uses them. Use the API's enums rather than inventing a common remote status enum. Prevent repeated clicks from creating another logical operation.
5. **Reconciliation.** Use the product's documented webhook verification where available; deduplicate delivery and refresh current resource state. Add bounded polling and recovery on application restart, missed events, delayed indexing, and RPC interruption. Keep a queued redemption resumable until proceeds arrive. Stop polling on terminal states; use appropriate backoff and a visible pending state instead of promising a completion time.
6. **Setup and checks.** Document required secret names, enabled access, networks, test asset/gas preparation, and how to run the integration. Add tests for authorization/ownership, precise amounts, repeat submission, uncertain responses, pending/failed operations, and restart recovery using the repository's test tools. Run existing affected checks and the sandbox acceptance flow below.

## Product procedures

Use this reading order to obtain exact executable payloads and transaction calls. Complete all steps in the chosen row, including its exit path.

| Product | Required operation guides, in order |
| - | - |
| Portfolio Wallets | [Create](/docs/portfolio-wallets/create-wallet) → [fund](/docs/portfolio-wallets/deposits) → [allocate](/docs/portfolio-wallets/auto-rebalancing) → [read balances/yield](/docs/portfolio-wallets/balances-and-yield) → [preview and withdraw](/docs/portfolio-wallets/withdraw-funds) → [approve](/docs/portfolio-wallets/transaction-approvals) → [reconcile](/docs/portfolio-wallets/polling). |
| MicroVaults | [Create](/docs/microvaults/create-vault) → [strategy](/docs/microvaults/strategy) and [fees](/docs/microvaults/fees) → [shareholder access](/docs/microvaults/shareholders) → [subscribe](/docs/microvaults/subscribe) → [redeem and claim](/docs/microvaults/redeem) → [reconcile](/docs/microvaults/status-and-performance). |
| gTokens | [Discover](/docs/gtokens/discover-yield-sources) → [direct access](/docs/gtokens/manage-gtoken-access) or [wrapper creation](/docs/gtokens/manage-fee-wrappers) and [wrapper access](/docs/gtokens/manage-fee-wrapper-access) → [deposit and redeem](/docs/gtokens/deposit-and-redeem) → [asynchronous claims](/docs/gtokens/async-operations) where required. |

Follow the complete procedure for the selected product. Read each linked operation guide before constructing that operation; it contains the exact payload, authorization, and contract call for that lifecycle.

## Portfolio Wallets

Use this procedure when your application owns the account mapping and operates offchain balances through Ground's API.

### Prerequisites

* A sandbox organization API key with the required read and write permissions
* A chosen mapping from your accounts to Portfolio Wallet IDs
* The configured organization or customer signing and approval flow, with an authorized signer or approver available
* A test funding wallet and withdrawal receiver on a [supported sandbox network](/docs/portfolio-wallets/supported-chains#sandbox)

### 1. Discover and plan the wallet

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export BASE_URL="https://sandbox.groundtech.co"
curl -sS "$BASE_URL/v2/wallets/yield-sources" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Select allocations from that response. Validate token, network, minimum amounts, and liquidity against the application's withdrawal needs. Document the account mapping and approval policy using the [custody model](/docs/security/custody-model) and [transaction approvals](/docs/portfolio-wallets/transaction-approvals).

### 2. Create and wait for the funding address

Choose the allocation mode before [wallet creation](/docs/portfolio-wallets/create-wallet): send `autoRebalance: true` with a strategy for automatic allocation, or `autoRebalance: false` without a strategy for manual allocation. For an automatic strategy, key each allocation array by the source catalogue's `allocationGroup` (`usdc`, `usdt`, or `usdt:tron`), and make each included group total 100%. Omitted groups start in cash. Save the returned wallet ID. Follow [address readiness](/docs/portfolio-wallets/deposits#address-readiness): fund only the returned address for your network. Wallet activity status and address provisioning are separate; an `idle` wallet can still have addresses provisioning.

Wallet creation and withdrawal creation require a body `requestId` (UUID v4) per logical operation. Persist it and the payload before submission. Initial success and identical replay return `200` with the resource; a divergent replay returns `409 request_id_conflict`. Recover an uncertain result with the same ID and payload. See [API conventions](/docs/portfolio-wallets/api-conventions#idempotency); apply endpoint-specific semantics to other writes rather than adding request IDs to every POST.

### 3. Fund and verify the balance

Follow [deposits](/docs/portfolio-wallets/deposits) to send the supported test asset and track the deposit until `completed`. Confirm the credited amount in `balance.totalUsd` and positions. A `processing` deposit is not spendable balance.

If automatic rebalancing is enabled, track the allocation to the chosen yield sources. Otherwise follow [manual allocation](/docs/portfolio-wallets/auto-rebalancing) to preview and allocate available cash. Confirm actual positions using [balances and yield](/docs/portfolio-wallets/balances-and-yield). Refresh `GET /v2/wallets/{id}` periodically as well as after lifecycle events: balances and yield can change without a new deposit, rebalance, or withdrawal event. Use `GET /v2/wallets/{id}/yield` for the detailed yield breakdown and `GET /v2/accounting/yield/earned-series?walletId=...` for earned-value and blended APY history; preserve decimal strings and distinguish APY from lifetime `earnedUsd`.

### 4. Withdraw and complete approvals

Follow [withdraw funds](/docs/portfolio-wallets/withdraw-funds): preview immediately before submission, verify the receiver, token, chain, available amount, fees, and current timing estimate, then create the withdrawal with its own persisted UUID v4.

Use [transaction approvals](/docs/portfolio-wallets/transaction-approvals) when a payout leg or external payout step is `pending_customer_approval`. Complete the configured signer's approval flow and continue tracking the same withdrawal. A withdrawal response is not proof of delivery.

Implement [verified webhook ingestion](/docs/portfolio-wallets/webhook-signature-verification) with deduplication and [polling](/docs/portfolio-wallets/polling) recovery. Refresh resource state after events. Respect `Retry-After` and retain the original operation identity across retries.

### Confirm the round trip

Record the wallet and deposit IDs, source transfer hash, completed deposit, allocation results, withdrawal ID, approval evidence where required, payout hashes, and final receiver balance. A `completed` withdrawal and confirmed receiver delivery finish the round trip. Report `partially_completed`, failed, cancelled, and pending operations with their leg states and next action; do not label them successful.

If an outcome is uncertain, read the resource before submitting again. If address provisioning or a workflow fails, retain its ID and reported reason and follow the linked guide's recovery steps. Include the result in the [shared evidence report](/docs/agentic-installation#verify-the-result).

## MicroVaults

MicroVaults are in private preview for enabled sandbox organizations on Ethereum Sepolia. Use this procedure when shareholders hold ERC-20 portfolio shares and sign their own subscriptions and redemptions.

### Prerequisites

* A sandbox organization with MicroVaults enabled and an API key with the required permissions
* An external shareholder wallet on Ethereum Sepolia (`chainId: 11155111`), funded with the selected base asset and native gas
* A server API client and a wallet transaction client
* An agreed fee recipient, fee rates, strategy, and minimum-output policy

### 1. Check access and discover sources

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GROUND_API="https://sandbox.groundtech.co"
curl -sS "$GROUND_API/v2/microvaults/vaults" \
  -H "Authorization: Bearer $GROUND_API_KEY"
curl -sS "$GROUND_API/v2/microvaults/yield-sources?chainId=11155111" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Continue when `creation.status` is `accepted`. Choose the base asset and sources from the current catalogue using [supported chains and sources](/docs/microvaults/supported-chains-and-sources). If access is unavailable, obtain organization enablement before provisioning.

### 2. Provision and configure the vault

Follow [create a vault](/docs/microvaults/create-vault), save `task.id`, and track provisioning until the vault is `active`. Save `id` for API requests and `address` for the onchain vault and share token. Match the creation attempt rather than selecting an arbitrary vault with the same name.

For API mutations that require `Idempotency-Key`, persist one nonempty key of at most 200 characters per logical action; a UUID is a convenient choice. Identical action and payload replay returns the existing task. Reusing a key for a different action or payload returns `409`. Preview and read calls do not create mutation tasks. After a timeout, inspect the original task or resource before issuing another change.

Configure [strategy and source modes](/docs/microvaults/strategy) and [fees](/docs/microvaults/fees), then confirm their effective state. Inspect the deployed vault ABI through [contracts](/docs/microvaults/contracts) before constructing transactions.

### 3. Admit shareholders and subscribe

Follow [shareholder access](/docs/microvaults/shareholders). Fetch a current proof for both transaction caller and share receiver; use one proof twice only when they are the same wallet. An accepted add task is not yet active membership.

Implement [subscription](/docs/microvaults/subscribe): verify the base asset and decimals, approve the exact required allowance, obtain a current share quote, and have the shareholder sign `depositWithProof` with minimum shares. Wait for successful receipts and the required chain confirmations. Compare the deposited asset, minted shares, and latest [activity and performance](/docs/microvaults/status-and-performance).

### 4. Preview, redeem, and claim

Follow [redemption](/docs/microvaults/redeem) to preview immediately before signing and verify `owner`, fixed receiver, share amount, and minimum output. The owner signs the returned transaction.

For `instant` mode, confirm asset delivery in that transaction. For `requested` mode, persist the onchain request ID from the confirmed transaction, poll the redemption endpoint until `claimable`, then submit `claimRedeemRequest`. The receiver fixed at request creation receives the actual proceeds. A request receipt is not settlement, and an estimated date is not proof of claimability.

### Confirm the round trip

Run the [sandbox test plan](/docs/microvaults/sandbox-testing) for the supported source lifecycles. Record provisioning/task IDs, vault ID and address, proof readiness, approval and subscription hashes, actual shares, redemption mode and request ID, claim hash where required, and final shareholder asset/share balances. Requested redemption completes after a successful claim receipt and API status `claimed`.

If activity lags a successful receipt, retain its hash and refresh reads before repeating a write. If a task fails, retain its ID and error and correct the cause before beginning a new logical action. Report unavailable source flows or still-pending liquidation as blockers in the [shared evidence report](/docs/agentic-installation#verify-the-result).

## gTokens

Use this procedure when the user or application wallet holds a single source's yield token and signs its backing-vault transactions.

### Prerequisites

* A sandbox organization API key with access to the selected source and required permissions
* A wallet able to sign the address-ownership authorization and onchain transactions
* The listed sandbox asset and native gas on the selected chain
* A choice between direct access and an organization fee wrapper

### 1. Discover the deployed interface

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS https://sandbox.groundtech.co/v2/gvaults/yield-sources \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Follow [discovery](/docs/gtokens/discover-yield-sources) and persist the source `id` as `gVaultId`, chain, contract, asset, and `interface`. Verify the chain and `asset()` against the catalogue and obtain the current ABI from the verified [deployed contracts](/docs/gtokens/contracts). Select the operation flow from the returned interface.

For fully direct deposits, select a source with a synchronous backing vault. Centrifuge-style deposit methods require the configured Ground router; confirm that supported integration with Ground before implementing it. Treat unavailable access or interface support as a blocker.

### 2. Establish effective access

For direct access, follow [manage gtoken access](/docs/gtokens/manage-gtoken-access): fetch the authorization from your backend, have the intended address sign the returned typed data, then submit its unexpired `ownershipProof`. New direct admission requires a matching completed LOW-risk assessment; follow the access guide for its prerequisite and report unavailable screening as a blocker. Enable deposits only after `allowed` is `true` and processing has completed. Address admission uses desired-state PUT semantics, not a new UUID on every attempt. A `202`, `submitted`, or transaction hash remains pending.

For revenue sharing, follow [fee-wrapper provisioning](/docs/gtokens/manage-fee-wrappers) and [wrapper access](/docs/gtokens/manage-fee-wrapper-access). Wrapper creation uses a body UUID v4 `requestId`: persist one per logical wrapper, replay the same payload and ID after uncertainty, and expect `409 request_id_conflict` for changed settings. Recover by `GET /v2/fee-wrappers?requestId=...`, wait for `ready`, and confirm the wrapper's own allowlist before use. Use its deployed interface and address for customer transactions.

### 3. Deposit and confirm shares

Implement [deposit and redeem](/docs/gtokens/deposit-and-redeem) for the chosen interface. Resolve asset decimals, verify the spender, approve the exact required asset amount, and simulate the supported deposit. Have the correct wallet sign and wait for successful receipts and required chain confirmations.

A synchronous deposit completes when gtokens reach the intended authorized receiver. A supported asynchronous deposit requires both the confirmed request and the later successful share claim. Persist request IDs and actual resulting balances, not only estimates.

### 4. Redeem and settle

Read current synchronous withdrawal capacity before selecting an immediate exit. For queued redemption, persist the onchain request ID, owner, contract, chain, requested shares, transaction hash, and minimum-output parameters required by the interface.

Follow [asynchronous operations](/docs/gtokens/async-operations) to determine claimability from current onchain state or simulation. Submit the claim with the authorized signer and verify the actual asset transfer. Ground API request IDs, onchain settlement request IDs, and transaction nonces have different roles; an API idempotency key does not deduplicate a wallet transaction.

### Confirm the round trip

Record source and optional wrapper IDs, effective access, approval and deposit hashes, actual gtoken amounts, redemption/request hashes, claim evidence where applicable, and final receiver asset and share balances. A queued request remains incomplete until the claim succeeds and the proceeds arrive.

After an uncertain transaction submission, inspect its receipt, nonce, and onchain request before sending another operation. Refresh effective access before retrying an administrative change. Report missing source access, unsupported router integration, reverted transactions, and pending settlement in the [shared evidence report](/docs/agentic-installation#verify-the-result).

## Recover safely

| Situation | Required behavior |
| - | - |
| API timeout after a write | Read the original resource/task where supported or replay the original payload and idempotency identity. Do not create another identity to bypass uncertainty. |
| `409` idempotency conflict | Compare the saved payload with the submitted payload. Treat a changed request as a new logical action only after resolving the original. |
| `401` / `403` | Resolve credentials, scope, or product/source access. Do not silently change organization or environment. |
| `429` / temporary `503` | Respect `Retry-After`, use bounded backoff, and preserve the operation identity. |
| Transaction submission uncertainty | Check the transaction receipt, signer nonce, and relevant contract request/state before retrying. A fresh API ID does not protect against a duplicate transfer. |
| Reverted receipt | Record the revert and state. Resolve its cause and obtain a fresh quote/proof where required before an authorized retry. |
| Delayed task, indexing, or settlement | Keep the operation pending and resumable. Refresh authoritative state; a date estimate or webhook alone is not proof of completion. |
| Missing access, test assets, or signer | Finish code and mocked checks that do not depend on that prerequisite, then report the exact blocker. Do not claim sandbox validation. |

## Verify the result

Run a real sandbox round trip when the developer has supplied access, test assets, and signing authorization. Capture starting balances, fund or subscribe, wait for confirmed credit/shares, exit, and confirm assets at the intended receiver. Exercise a restart while an operation is pending and recover the same operation. For a queued source, include successful claim and receiver delivery; if settlement is still pending, retain the request and report it as incomplete.

| Product | Required confirmed evidence |
| - | - |
| Portfolio Wallets | Correct provisioned address; completed deposit and credited amount; actual allocation/positions; withdrawal preview and accepted withdrawal; required signer approvals; completed withdrawal and receiver payout. |
| MicroVaults | Creation task correlated with the active vault; effective strategy/fees; active shareholder proofs; successful approval/subscription receipts and minted shares; instant delivery or requested redemption followed by successful claim and `claimed` state. |
| gTokens | Correct source or ready wrapper and effective allowlist; correct asset/spender; successful deposit and actual yield tokens; immediate exit or queued request followed by successful claim and delivered asset. |

The final handoff must include changed files, setup/run instructions, check results, resource and operation IDs, chain and transaction hashes, and starting/final asset and share balances. State whether each check used a mock, simulation, or confirmed sandbox transaction. List unresolved approvals, access, signing, failed tasks, and queued settlement with the exact next action. A guide can support a complete implementation pass; it cannot remove organization enablement, human signatures, test funding, or settlement delays.

## Integration feedback

Developers and coding agents can report bugs, documentation mismatches, integration friction, feature requests, or a successful test through `POST /v2/integration-feedback`. Submit one report per distinct finding. Include what you observed and references that help Ground reproduce it; distinguish your explanation from confirmed behavior.

### Prerequisites

Use an organization API key with `write` permission from your backend or development environment. Keep the key out of frontend code, logs, and report content. Dashboard login tokens and read-only keys do not authorize this endpoint. Send to the same sandbox or production base URL used by the integration; Ground derives organization and environment from authentication and its server configuration.

If authentication prevents submission, retain the redacted report and [contact Ground](https://www.groundtech.co/contact). Reporting is optional and should not block your integration.

### Submit a report

Save a UUID v4 `submissionId` and the report before sending it. The minimal required fields are `submissionId`, `product`, `category`, `title`, and `observed`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://sandbox.groundtech.co/v2/integration-feedback" \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "submissionId": "57dc48f3-2163-4f92-888a-3fa1b03bbcc7",
    "product": "gtokens",
    "category": "docs_mismatch",
    "stage": "source_discovery",
    "title": "The example asset does not match the selected network",
    "expected": "The example uses the sandbox network asset",
    "observed": "The address in the example differs from the returned sandbox catalog",
    "docsUrl": "https://docs.groundtech.co/docs/gtokens/discover-yield-sources",
    "agent": { "name": "codex" },
    "evidence": {
      "reproductionSteps": ["Read the example and compare it with the sandbox catalog"]
    }
  }'
```

Product values: `portfolio_wallets`, `microvaults`, `gtokens`. Category values: `bug`, `docs_mismatch`, `friction`, `feature_request`, `success`.

Optional evidence includes an API request ID, transaction hash, and up to five reproduction steps. These references help investigation; they do not automatically verify the report. Do not include API keys, authorization headers, signing material, environment files, raw request/response dumps, personal data, or proprietary application code. Review free text before submitting it. Report content is retained in a private review inbox; URLs are references, not requests for Ground to fetch them.

Requests must be uncompressed `application/json`, at most 16 KiB. Unknown fields and attachments are rejected. `title` accepts up to 256 characters; `observed` and `expected` each accept 4096; steps each accept 512. `stage` and each agent field accept 80 characters; `docsUrl` accepts 1024 and must be HTTPS without credentials or query parameters; API request IDs and transaction hashes accept 128 each. `agent` accepts only `name` and `version`; `evidence` accepts only `apiRequestId`, `transactionHash`, and `reproductionSteps`.

### Keep the receipt and handle retries

A newly stored report returns `201`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "103f836d-2cac-4aa7-a830-c086321d139b",
  "submissionId": "57dc48f3-2163-4f92-888a-3fa1b03bbcc7",
  "status": "received",
  "createdAt": "2026-10-08T23:00:00.000Z"
}
```

`received` means durably stored, not investigated, verified, or resolved. There is no public report-reading endpoint. Keep the receipt for later support correspondence.

| Response | Next action |
| - | - |
| `200` | Identical content with the same organization-scoped submission ID already exists; keep the original receipt. |
| `400` | Correct the reported validation issue. |
| `401` / `403` | Check organization API-key authentication and write permissions. |
| `409 submission_id_conflict` | The ID already belongs to different content. Use a new ID for a distinct or revised report. |
| `413` / `415` | Reduce the body or use uncompressed JSON. |
| `429` | Respect `Retry-After`; retry the same ID and content after backoff. |
| `503` or an uncertain network result | Retry the same ID and content after `Retry-After` or bounded backoff; do not assume acceptance. |

New reports are limited to five per minute per key, ten per minute and 100 per UTC day per organization. Global intake is bounded, so `429` may also indicate service-wide capacity. An identical replay does not consume new-report quota, but still passes authentication, IP shedding, and general API request limits. Avoid retry loops; after bounded attempts, retain the local report and continue or report the blocker to your developer.


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