curl --request POST \
--url https://{host}/v1/markets \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Ambient-Actor: <api-key>' \
--header 'X-Ambient-Timestamp: <api-key>' \
--data '
{
"commandId": "table-create-1",
"externalRef": "table-2026-09-19-1900",
"principalId": "restaurant-1",
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 1,
"pricing": {
"mode": "posted",
"amountMinor": 7500,
"currency": "USD"
},
"confirmation": "participant",
"holdDurationSeconds": 600
}
}
}
'{
"market": {
"id": "<string>",
"version": 2,
"state": "draft",
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"funding": {
"mode": "none",
"acceptedRailIds": [
"<string>"
],
"settlementGraceSeconds": 1
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalRef": "<string>",
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"publicationCredentialId": "<string>"
},
"events": [
{
"id": "<string>",
"type": "market.draft_created",
"marketId": "<string>",
"marketVersion": 2,
"commandId": "<string>",
"principalId": "<string>",
"actorId": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"data": {
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
}
},
"sequence": 2,
"authorityRef": "<string>"
}
]
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "request authentication failed"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Markets
Create a market draft
Creates an inactive draft from a subject and a supported mechanism. Ambient assigns the canonical market identifier. Review the returned identifier, normalized configuration, and version before publishing.
POST
/
v1
/
markets
curl --request POST \
--url https://{host}/v1/markets \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Ambient-Actor: <api-key>' \
--header 'X-Ambient-Timestamp: <api-key>' \
--data '
{
"commandId": "table-create-1",
"externalRef": "table-2026-09-19-1900",
"principalId": "restaurant-1",
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 1,
"pricing": {
"mode": "posted",
"amountMinor": 7500,
"currency": "USD"
},
"confirmation": "participant",
"holdDurationSeconds": 600
}
}
}
'{
"market": {
"id": "<string>",
"version": 2,
"state": "draft",
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"funding": {
"mode": "none",
"acceptedRailIds": [
"<string>"
],
"settlementGraceSeconds": 1
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"externalRef": "<string>",
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
},
"publicationCredentialId": "<string>"
},
"events": [
{
"id": "<string>",
"type": "market.draft_created",
"marketId": "<string>",
"marketVersion": 2,
"commandId": "<string>",
"principalId": "<string>",
"actorId": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"data": {
"discoverability": "listed",
"creator": {
"principalId": "<string>",
"actorId": "<string>",
"authorityRef": "<string>"
},
"subject": {
"schema": "restaurant-table.v1",
"data": {
"partySize": 2,
"startsAt": "2026-09-19T19:00:00Z"
}
},
"mechanism": {
"presetId": "direct-claim.v1",
"config": {
"capacity": 2,
"pricing": {
"mode": "free"
},
"confirmation": "none",
"holdDurationSeconds": -1,
"maxPerPrincipal": 2,
"claimsCloseAt": "2023-11-07T05:31:56Z"
}
},
"mechanismState": {
"allocated": 1
},
"fulfillment": {
"requestSchema": "<string>",
"acceptedDeliveryTransports": [
"<string>"
],
"outputMediaTypes": [
"<string>"
],
"providerEndpoint": {
"transport": "<string>",
"uri": "<string>"
},
"slaSeconds": 2
}
},
"sequence": 2,
"authorityRef": "<string>"
}
]
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "request authentication failed"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Authorizations
AmbientActor & AmbientTimestamp & AmbientSignatureAmbientBearer
Provisioned actor identifier.
Current Unix timestamp in seconds, within the configured clock-skew window.
Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input.
Body
application/json
Actor-scoped idempotency key. Retry the identical command with the same value.
Minimum string length:
1Principal represented by the authenticated actor.
Minimum string length:
1Show child attributes
Show child attributes
Supported versioned allocation mechanism and its immutable configuration.
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Optional creator-private correlation reference. It is not unique and is not an idempotency key.
Maximum string length:
256Listed markets appear in public discovery. Unlisted markets remain readable by exact market ID and are not private.
Available options:
listed, unlisted Required delegation identifier when the actor and principal differ. Omit for self-action.
Minimum string length:
1Show child attributes
Show child attributes
Show child attributes
Show child attributes