---
title: "Request metadata"
description: "Use request_meta for idempotency and to select the public properties returned by a supported endpoint."
canonical: "https://studio.inttegro.dev/api/request-metadata"
format: inttegro-machine-docs/v1
language: "TypeScript"
sdk_version: "v14.1.1"
reader_profile: optional
reader_manifest: "https://studio.inttegro.dev/machine/typescript/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 504
model_token_report: "https://studio.inttegro.dev/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: ["create_order"]
estimated_tokens: 1919
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Use request_meta for idempotency and to select the public properties returned by a supported endpoint. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Request metadata?

Use this API reference when exact operations, fields, states, or errors are required.

#### Q2. What is authoritative on this page?

Types and enum members link to pinned SDK references; a response field may link only to its containing type. A “wire-only” request field is not a verified native SDK member.

#### Q3. What page-specific constraint matters most?

Do not infer a business workflow from endpoint order or treat request acceptance as proof that an asynchronous outcome completed.

#### Q4. Can Inttegro MCP materially help with this task?

Yes, when the reader has an authenticated MCP connection and the task needs live context, guided planning, or a supported operation. The strongest matches are `create_order`; their exact roles and boundaries are listed below.

#### Q5. How should the reader verify the answer and continue?

For a read, compare the returned resource with the requested identifier and scope. For a write, preserve its identifier and retrieve authoritative current state before declaring the business outcome complete. Continue with [Error codes](https://studio.inttegro.dev/machine/typescript/api/error-codes.md) and [custom data](https://studio.inttegro.dev/machine/typescript/api/custom-data.md) when those concerns enter scope.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`create_order`](https://studio.inttegro.dev/machine/typescript/inttegro-mcp/tools.md#create_order) — action; exact user confirmation required. Creates an order for an existing customer from catalog product and price IDs. This tool never executes payment; finalize defaults to false.

## Document content

# Request metadata

The optional `request_meta` object carries controls for one API request. It is separate from the resource you are creating or changing. Use it to supply a stable idempotency key or to ask a supported endpoint for a smaller response.

## Prerequisites

- [Authenticate your API requests](https://studio.inttegro.dev/machine/typescript/api/authentication.md).
- Check the endpoint's request parameters to confirm that it accepts request metadata.
- Read [Idempotent requests](https://studio.inttegro.dev/machine/typescript/api/idempotency.md) before implementing retries for a write operation.
- Read the endpoint's response properties before selecting a response shape.

## Shape and SDK naming

The JSON wire name is `request_meta`. SDKs expose typed request-metadata, response, and property-selection objects using the selected language's naming conventions.

- `requestMeta.idempotencyKey` — `string`

  Optional stable key for safely repeating the same logical write. Supply it
  here or in the `Idempotency-Key` request header. If you
  send both, their values must match.

- `requestMeta.response` — `RequestResponse`

  Optional preferences for the successful response. Its projection maps
  endpoint-defined response resource names to one typed pick or omit
  selection.

An idempotency key must be a non-empty string no longer than 255 characters. Reuse the same key only when repeating the same operation with the same request payload. A changed payload represents a different operation and must use a new key.

## Select the response shape

Use `response.projection` when your integration needs only part of a successful response. The projection is a map keyed by response resource name. For each resource, supply exactly one non-empty selection:

- `pick` includes only the listed property paths. Inttegro keeps the ancestors needed to contain a selected property. Picking a parent property includes its public subtree.
- `omit` removes the listed property paths and their descendants.

Resources that are not present in the projection keep their complete caller-visible representation. The endpoint validates resource names and property paths against its public response contract. An unknown or unavailable resource or path returns `invalid_response_projection`.

The following order-creation fragment asks for only the order ID, status, and customer name, while omitting the payment's latest error:

**Request metadata with a response projection**

```typescript
{
  requestMeta: {
    response: {
      projection: {
        order: {
          pick: [
            "id",
            "status",
            "customer.name",
          ],
        },
        payment: {
          omit: [
            "latest_error",
          ],
        },
      },
    },
  },
}
```

Resource names and property-path strings are API JSON identifiers. Keep them in their documented wire form, such as `customer.name` and `latest_error`, even when the selected SDK uses another naming convention for ordinary object properties.

## Include metadata only when documented

Request metadata is not a universal parameter. Some endpoint request types expose it, while others do not. The endpoint reference is authoritative: if `request_meta` is absent from its request parameters, omit the object rather than assuming support from another endpoint.

For example, [Create an order](https://studio.inttegro.dev/machine/typescript/api/orders.md#create-an-order) accepts an idempotency key inside `request_meta`. The following request fragment follows the selected SDK's naming and type conventions:

**Request metadata for order creation**

```typescript
{
  requestMeta: {
    idempotencyKey: "checkout_cart_123",
  },
}
```

You may instead send `checkout_cart_123` in the `Idempotency-Key` header.

## Request metadata is not custom data

Use request metadata only for the request controls documented by the endpoint. Use [custom data](https://studio.inttegro.dev/machine/typescript/api/custom-data.md) for small application-specific string values that belong with a resource. Do not place arbitrary business data, secrets, or undocumented properties inside `request_meta`.

## Related resources

- [Idempotent requests](https://studio.inttegro.dev/machine/typescript/api/idempotency.md) - Choose stable keys and retry a supported operation safely.
- [Create an order](https://studio.inttegro.dev/machine/typescript/api/orders.md#create-an-order) - See request metadata in an endpoint contract.
- [Error codes](https://studio.inttegro.dev/machine/typescript/api/error-codes.md) - Handle `invalid_response_projection` and other request errors.
- [Custom data](https://studio.inttegro.dev/machine/typescript/api/custom-data.md) - Attach supported application-specific string values to resources.