Claim an integration command.

Claim the oldest pending command for any of the given locations, and of one of ops when given.

The request is held open while no command is pending: up to 25 seconds, or hold_ms when given. It answers 200 with the command as soon as one is queued, or 204 with no body when the time passes. A claimed command is held by its claim_token until its lease ends, shortly after its deadline_at, and takes its result until then. A claim repeating a claim_key gets back the command that key holds, whatever ops says, while that command has no result, its lease has not ended and the claim names its location, so a claim whose answer was lost loses no command. Every location must be one the token can access, or the whole claim is refused with 403. A malformed field is refused with 400, and nothing is claimed.

Note: This route requires that your application gets allow-listed. See: KumeteWeb.Plugs.RateLimitV4 for reference. If you need to add a new application to the allow-list, please contact the team responsible for Kumete [marketplace-team].

Required scope: write_integration_commands.

Body Params

Claim params

string
^[A-Za-z0-9_-]{43}$

32 random bytes in base64url without padding. Send the same key again on every claim naming the same locations until a claim made with it is answered (a 204, or a 200 whose body could be read), then make a new one: a claim under the key may have taken a command whose answer was lost (a network failure, a timeout or a 5xx), and a refusal (a 4xx, from this API or a gateway) says nothing of that. It is as secret as a claim_token.

integer
0 to 25000

Hold the claim open at most this many milliseconds; 0 answers at once. Absent, the full 25 seconds.

location_uids
array of uuids
required
length between 1 and 100

The locations to claim a command for.

location_uids*

Podium unique identifier for location.

ops
array of strings
length between 1 and 20

Claim only commands with one of these ops. Absent, a command with any op is claimed.

ops
Responses

204

No command was queued within the hold: 25 seconds, or hold_ms.

Callback
Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json