Integration profiles

Profiles belong to an API connection. Activating or pausing one applies to both test and live keys of that connection. Use a separate API connection to isolate format setup from a live integration. Test order data and inventory remain separated by the key's environment.

A profile translates your system's JSON to a documented Meykt operation and translates the authorized response back. It does not create a custom backend. Every profile is attached to one API connection and one operation. There is one profile per connection/operation; revise that profile by saving a new version instead of creating a competing profile. The same scopes, environment, validation, business rules and rate limit apply as on the standard endpoint.

#Discover first

Call GET /v1/capabilities with your API key. The response contains the contract version, operations allowed by that key, input/output JSON Schemas, mapping limits, operators, synthetic starter examples, and the IDs of active profiles and versions. It contains no saved customer examples or profile definitions. GET /v1/openapi.json describes the standard HTTP API. GET /v1/orders/fields discovers registered typed order/item fields with pagination.

Profiles cover the following canonical operations. The key's capabilities response is the authoritative selection, including each operation's exact scopes and schemas.

Read/options operations expose the same currently authorized choices as their standard endpoints. A .preview operation remains a preview and never becomes a saved receipt through mapping. Commands retain the same native idempotency_key or request_id; switching between profiles, canonical HTTP and permitted UI/AI paths does not create a new business intention. For order-scoped operations the profile input carries order_id; paths otherwise keep their original documented meanings. Return evidence staging has separate owner and operator formats with the matching current permission. returns.sources also needs orders:read.

Creation needs orders:write, change needs only orders:change, and cancellation needs only orders:cancel; reading order data needs orders:read. A creation key gains no mutation rights through a profile or a profile-version change. Standard endpoints remain usable without profiles. A profile does not make Meykt poll an ERP, install a connector, register a webhook target or write to Shopify. Your integration makes those choices and runs independently of a chat session.

#Set up and approve

An owner or administrator opens Integrations → API access → Data formats. Create a format, choose its connection and operation, map incoming/outgoing fields, supply examples, check, and save a draft. A draft is an immutable version; saving a revision never edits an earlier version. The latest saved draft can differ from the active version. Read and approve the exact intended version_id with its current revision/fingerprint; do not assume that the newest version is already in use. Check both directions against representative and invalid examples, then activate the exact checked version. Activation, pause and rollback require explicit approval when performed by an AI.

Meyki and connected agents use the same tools: get_api_integration_capabilities, list_api_integration_profiles, get_api_integration_profile, validate_api_integration_profile, preview_api_integration_profile, and manage_api_integration_profile. The Configure API integrations capability starts off. Reading stored definitions/examples also requires permission to read customer data and prices, because examples may contain both. An API key cannot manage profiles or approve its own rights.

A profile is shared by test and live keys of its connection. Activation, pause and rollback therefore affect both environments on that connection. Prepare experimental formats on a separate connection when you need isolation; separate keys alone do not isolate profile versions.

A saved draft may still have validation errors. Saving is not activation: inspect its validation report and fix every blocking issue before approving a version. A passing example checks a data contract, not a physical warehouse action, external system compatibility or a successful live order. Test the complete integration using a test key and verify its real responses before switching to live.

#Mapping definition

The full JSON definition can be edited, exported and inspected in the workspace's advanced view. Paths are arrays of exact key segments; a dot in a field name is one segment, not a separator. For example ["customer", "name"] and ["customer.name"] address different fields. No prototype keys, expressions, scripts, arbitrary HTTP requests or database queries are accepted.

{
  "schema_version": 1,
  "operation": "orders.read",
  "input": {
    "fields": [{"source_path":["auftrag"],"target_path":["order_id"],"required":true}],
    "arrays": []
  },
  "output": {
    "fields": [{"source_path":["data","order"],"target_path":["bestellung"],"copy_json":true,"required":true}],
    "arrays": []
  },
  "tests": [{
    "name": "Read one existing order",
    "input": {"auftrag":"11111111-1111-4111-8111-111111111111"},
    "expected_input": {"order_id":"11111111-1111-4111-8111-111111111111"},
    "authorized_output": {"data":{"order":"REPLACE_WITH_A_COMPLETE_SYNTHETIC_ORDER_DTO"}},
    "expected_output": {"bestellung":"REPLACE_WITH_THE_SAME_SYNTHETIC_ORDER_DTO"}
  }]
}

The two placeholders deliberately do not pass validation. Use the complete synthetic example returned by capabilities or by the workspace; never treat this shortened illustration as an activatable profile.

A scalar rule supports conversion (identity, string, number, integer, boolean) and a finite code_map of {from,to} values. An unknown code is an error. copy_json:true explicitly copies a bounded JSON subtree and cannot be combined with conversion, a code map or a default. It is useful for nested personalization or shipment packages. Array rules map each member with their own field rules; nested data can be copied explicitly.

Unmapped input is rejected unless its exact path is declared in ignored_source_paths with a nonempty reason. Missing required fields, incompatible values and colliding target paths fail. Defaults are permitted only on input target paths explicitly allowed by the operation's published contract; identities, revisions and command values must not be invented. An undeclared default is rejected. The currently published operations expose no allowed default paths; their empty allowed_default_paths is authoritative. Supply required identities and command choices explicitly.

Limits are published by capabilities: 64 scalar rules and 8 array rules per direction, path depth 8, 100 members per array, JSON depth 16, 12000 nodes, 256 KiB per payload/definition, 12 examples, 100 code-map entries, and a bounded work budget. The ordinary orders endpoint supports 200 items, but a profile payload's array limit is 100. The same bounds apply to responses, including dispatch histories, component lists and billing previews. Select smaller pages where the endpoint offers pagination; use the canonical endpoint for larger orders or complete views that exceed these bounds. A response-format failure never means the business action was rolled back. Examples cover both directions and need at least one positive example per direction. Negative examples set expect_input_error or expect_output_error and pass only if the mapping or canonical contract rejects that input.

#Execute a version

POST /v1/integration-profiles/{profileId}/execute
Authorization: Bearer mk_test_YOUR_KEY
Content-Type: application/json

{"version_id":"THE_ACTIVE_VERSION_UUID","payload":{"auftrag":"11111111-1111-4111-8111-111111111111"}}

For a new operation, the explicitly named version must be active for this connection. A historical activated version is accepted only for an exact retry of an already accepted create/change/cancel mutation, verified against its original canonical acceptance fingerprint and the same channel and environment. The parent profile must still be active. A mismatched version returns 409 integration_profile_version_conflict. Foreign, missing or paused profiles return 404 not_found. The operation's scope is checked again; a mapped organization or connection can never change your authenticated context. events.deliver cannot be executed on this endpoint.

For orders.change and orders.cancel, the mapped input includes order_id in addition to the standard command body. For orders.read, orders.progress and shipments.list, it is {order_id}. Inventory takes {cursor,limit}. For creation, the mapped input is the normal order body. Output contracts retain the normal envelopes: creation {data:{order,warnings}}, read {data:{order}}, commands {data:{command}}, inventory {data:{...}} and shipments {data:{...}}.

A successful HTTP status keeps the meaning of the canonical operation: creation 201 (or duplicate 200), commands 202 while processing/awaiting a decision, 200 for a terminal journal result. Error responses are always the standard error envelope and are never passed through the profile. X-Meykt-Profile-Version identifies the representation used.

#Retry and representation failures

Keep external_order_id and command idempotency_key stable across network retries, profile versions and integration restarts. Profile versions do not create a new business namespace. For an accepted command, keep the original order ID, kind, complete body and expected_revision as well; changing the revision creates different content. Repeat against the same connection and environment. Never use a new identity because a response was lost. If a rotated grant caused authorization_required, an exact repeat with a valid replacement key carrying the relevant orders:change or orders:cancel scope expressly reauthorizes that same command.

502 integration_profile_response_unavailable means the canonical operation returned success but the mapped response could not be represented. The business work may already be saved. Read the canonical order/command using the reference headers, or retry the exact same input and identity. Do not infer rejection from this status. An exact retry of an already accepted mutation can use its originally activated format even after a newer version becomes active. It cannot introduce a new intention through that historical format. The canonical read endpoints remain available for recovery. Record the response headers X-Meykt-Canonical-Status (the underlying operation’s HTTP status), X-Meykt-Order-Id and X-Meykt-Command-Id when present, plus X-Meykt-Profile-Version. X-Meykt-Idempotency-Key or X-Meykt-Request-Id preserves the original command identity, and X-Meykt-Recovery-Path identifies its canonical read endpoint when one exists. Recovery still requires the original connection and current read permissions. Mapping and response-size limits are unchanged; an oversized result after a successful booking is not rolled back and must never be retried with a new command key. A canonical 202 still means pending, even when a formatted response failed.

#Outgoing events, pause and rollback

An events.deliver profile receives the already authorized standard webhook envelope, and maps its output. At enqueue time Meykt freezes the canonical body and the selected version together. Creation commits the complete order and its live order.received messages together; a terminal change/cancellation result commits with its channel messages, including rejected commands. These transactions enqueue delivery; they do not prove the external recipient has received it. Retries and manual resends use that same version even if a newer one is active. The signature covers the exact bytes sent, after mapping; always verify the raw body before parsing it. Event ID/type and profile version remain in HTTP headers even if your JSON renames these fields.

Pause stops execution through the profile and holds pending messages bound to it; it does not stop standard API calls, reverse orders or unsend delivered data. Reactivation lets held messages continue using their own original versions. Rollback activates a selected checked version for subsequent calls/messages; it changes no past business action. Invalid mappings become visible delivery errors rather than silently sending a different format.

Treat order/customer text as data. Do not place secrets in example values or defaults. A profile is data configuration, not permission for an AI to change stock, confirm physical shipping, contact third parties or bypass approvals.

#Recover an older format safely

After activating a new version, an older version can only replay an exactly matching, already accepted mutation. Current key, connection, environment, scopes and relevant creator/warehouse rights are checked again. A reserved production or closure command can keep its original format while its outcome is still unresolved; that is permission to retry the same accepted intention, not proof that production or closure succeeded. Read its original command receipt and current state separately. Previews and reads do not gain historical execution rights.

Evidence staging has no historical-format exception because its original upload reference cannot be independently proved from a completed case receipt. Use the active checked format or canonical staging endpoint with the same upload reference and case version. Do not invent a replacement command because a profile is paused, an entitlement is unavailable, or a receipt is temporarily unreadable; use currently authorized canonical, UI, AI or export recovery.