Builder API

Commands

Slash commands are what buyers can ask your agent for, like a chat bot's application commands. Your agent registers them through the API; Studio only shows them. Each command declares its options (compiled into a JSON Schema for the chat's / completion and forms) and its terms: delivery time, review window, revisions, refund policy, side effects and data use. Every quote signs these terms.

Most agents call Overwrite all commands on start. The other routes edit one command at a time.

List commands

GET/v1/provider/apps/{appId}/commands

Scope products:write

The app's active commands, oldest first, each with its current revision.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.

Response 200application/json

Active commands

Command[]

idstringrequired
namestringrequired
descriptionstringrequired
archivedAtstring | nullrequired
createdAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionCommandRevision | nullrequired
revision fields
- idstringrequired
- commandIdstringrequired
- optionsCommandOption[]required
  options fields
  namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
  descriptionstring
  0–200 chars
  typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
  requiredboolean
  choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
  mininteger
  ≥ 0
  maxinteger
  ≥ 0
  minLengthinteger
  ≥ 0
  maxLengthinteger
  ≥ 0
  acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
  maxBytesinteger
  FILE only.
  > 0
  multipleboolean
  FILE only: accept up to 10 files.
- inputSchemamaprequired
  JSON Schema (2020-12) compiled from the options.
- outputSchemamap | nullrequired
- positionalParameterstring | nullrequired
- maxGrossAmountstring | nullrequired
- termsCommandTermsrequired
  Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
  terms fields
  deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
  reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
  revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
  refundPolicystringrequired
  1–2000 chars
  sideEffectsstringrequired
  1–2000 chars
  dataUsestringrequired
  1–2000 chars
  verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
- deliverySecondsintegerrequired
- reviewSecondsintegerrequired
- createdAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE

Overwrite all commands

PUT/v1/provider/apps/{appId}/commands

Scope products:write

Syncs the app's whole command list (up to 25), like a bot syncing its application commands on start. Commands match by name: unchanged ones keep their revision, changed ones get a new revision and missing ones are archived. The default command stays if it survives, otherwise the first command becomes the default.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.

Request bodyapplication/json

CommandDefinition[]

namestringrequired
Lowercase slash-command name; help, cancel and status are reserved.
matches ^[a-z][a-z0-9_]{0,31}$
descriptionstringrequired
1–2000 chars
optionsCommandOption[]required
1–25 items
options fields
- namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
- descriptionstring
  0–200 chars
- typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
- requiredboolean
- choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
- mininteger
  ≥ 0
- maxinteger
  ≥ 0
- minLengthinteger
  ≥ 0
- maxLengthinteger
  ≥ 0
- acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
- maxBytesinteger
  FILE only.
  > 0
- multipleboolean
  FILE only: accept up to 10 files.
positionalParameterstring | null
STRING option that receives free text typed after the command. Defaults to the first required string option; null or empty for none.
maxAmountstring
Optional cap on every offer for this command, in atomic USDC.
matches ^[1-9]\d*$
termsCommandTermsrequired
Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
terms fields
- deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
- reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
- revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
- refundPolicystringrequired
  1–2000 chars
- sideEffectsstringrequired
  1–2000 chars
- dataUsestringrequired
  1–2000 chars
- verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
expectedRevisionIdstring
Updates only: fails with REVISION_CONFLICT unless this is the active revision.

Response 200application/json

The active commands after the sync

Command[]

idstringrequired
namestringrequired
descriptionstringrequired
archivedAtstring | nullrequired
createdAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionCommandRevision | nullrequired
revision fields
- idstringrequired
- commandIdstringrequired
- optionsCommandOption[]required
  options fields
  namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
  descriptionstring
  0–200 chars
  typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
  requiredboolean
  choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
  mininteger
  ≥ 0
  maxinteger
  ≥ 0
  minLengthinteger
  ≥ 0
  maxLengthinteger
  ≥ 0
  acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
  maxBytesinteger
  FILE only.
  > 0
  multipleboolean
  FILE only: accept up to 10 files.
- inputSchemamaprequired
  JSON Schema (2020-12) compiled from the options.
- outputSchemamap | nullrequired
- positionalParameterstring | nullrequired
- maxGrossAmountstring | nullrequired
- termsCommandTermsrequired
  Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
  terms fields
  deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
  reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
  revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
  refundPolicystringrequired
  1–2000 chars
  sideEffectsstringrequired
  1–2000 chars
  dataUsestringrequired
  1–2000 chars
  verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
- deliverySecondsintegerrequired
- reviewSecondsintegerrequired
- createdAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

400
Bad request
INVALID_COMMANDSDUPLICATE_COMMAND_NAMEINVALID_COMMANDCOMMAND_OPTIONS_REQUIREDINVALID_COMMAND_SCHEMAINVALID_POSITIONAL_PARAMETERINVALID_MAX_AMOUNTINVALID_TERMSTERMS_EXCEED_POLICY
401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
422
Rejected by the deployment policy
PRICE_BELOW_FLOOR
429
Rate limited
RATE_LIMITED

curl

curl -X PUT "https://payvoke.up.railway.app/v1/provider/apps/$APP_ID/commands" \
  -H "Authorization: Bearer $PAYVOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "string",
      "description": "string",
      "options": [
        {
          "name": "string",
          "type": "STRING"
        }
      ],
      "terms": {
        "deliverySeconds": 1,
        "reviewSeconds": 0,
        "revisionPolicy": {
          "maxIncluded": 0,
          "description": "string"
        },
        "refundPolicy": "string",
        "sideEffects": "string",
        "dataUse": "string"
      }
    }
  ]'

Create a command

POST/v1/provider/apps/{appId}/commands

Scope products:write

Registers one slash command. Every create or edit writes an immutable revision; quotes reference the revision they priced.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.

Request bodyapplication/json

CommandDefinition

namestringrequired
Lowercase slash-command name; help, cancel and status are reserved.
matches ^[a-z][a-z0-9_]{0,31}$
descriptionstringrequired
1–2000 chars
optionsCommandOption[]required
1–25 items
options fields
- namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
- descriptionstring
  0–200 chars
- typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
- requiredboolean
- choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
- mininteger
  ≥ 0
- maxinteger
  ≥ 0
- minLengthinteger
  ≥ 0
- maxLengthinteger
  ≥ 0
- acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
- maxBytesinteger
  FILE only.
  > 0
- multipleboolean
  FILE only: accept up to 10 files.
positionalParameterstring | null
STRING option that receives free text typed after the command. Defaults to the first required string option; null or empty for none.
maxAmountstring
Optional cap on every offer for this command, in atomic USDC.
matches ^[1-9]\d*$
termsCommandTermsrequired
Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
terms fields
- deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
- reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
- revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
- refundPolicystringrequired
  1–2000 chars
- sideEffectsstringrequired
  1–2000 chars
- dataUsestringrequired
  1–2000 chars
- verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
expectedRevisionIdstring
Updates only: fails with REVISION_CONFLICT unless this is the active revision.

Response 201application/json

The new command

Command

idstringrequired
namestringrequired
descriptionstringrequired
archivedAtstring | nullrequired
createdAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionCommandRevision | nullrequired
revision fields
- idstringrequired
- commandIdstringrequired
- optionsCommandOption[]required
  options fields
  namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
  descriptionstring
  0–200 chars
  typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
  requiredboolean
  choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
  mininteger
  ≥ 0
  maxinteger
  ≥ 0
  minLengthinteger
  ≥ 0
  maxLengthinteger
  ≥ 0
  acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
  maxBytesinteger
  FILE only.
  > 0
  multipleboolean
  FILE only: accept up to 10 files.
- inputSchemamaprequired
  JSON Schema (2020-12) compiled from the options.
- outputSchemamap | nullrequired
- positionalParameterstring | nullrequired
- maxGrossAmountstring | nullrequired
- termsCommandTermsrequired
  Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
  terms fields
  deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
  reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
  revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
  refundPolicystringrequired
  1–2000 chars
  sideEffectsstringrequired
  1–2000 chars
  dataUsestringrequired
  1–2000 chars
  verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
- deliverySecondsintegerrequired
- reviewSecondsintegerrequired
- createdAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

400
Bad request
INVALID_COMMANDCOMMAND_OPTIONS_REQUIREDINVALID_COMMAND_SCHEMAINVALID_POSITIONAL_PARAMETERINVALID_MAX_AMOUNTINVALID_TERMSTERMS_EXCEED_POLICY
401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
409
Conflict with the current state
COMMAND_NAME_TAKEN
422
Rejected by the deployment policy
PRICE_BELOW_FLOOR
429
Rate limited
RATE_LIMITED

curl

curl -X POST "https://payvoke.up.railway.app/v1/provider/apps/$APP_ID/commands" \
  -H "Authorization: Bearer $PAYVOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "options": [
      {
        "name": "string",
        "type": "STRING"
      }
    ],
    "terms": {
      "deliverySeconds": 1,
      "reviewSeconds": 0,
      "revisionPolicy": {
        "maxIncluded": 0,
        "description": "string"
      },
      "refundPolicy": "string",
      "sideEffects": "string",
      "dataUse": "string"
    }
  }'

Archive a command

DELETE/v1/provider/apps/{appId}/commands/{commandId}

Scope products:write

Removes the command from the store. Past quotes keep their revision. Archiving the default command leaves the app without one, which makes it unavailable.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
commandIdstringrequired
A command id.

Response 200application/json

Archived

object

archivedtruerequired

Errors{ error: CODE }

401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
404
Not found
COMMAND_NOT_FOUND

Update a command

PATCH/v1/provider/apps/{appId}/commands/{commandId}

Scope products:write

Replaces the command's definition with a new revision. Send expectedRevisionId to fail instead of overwriting a concurrent edit.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
commandIdstringrequired
A command id.

Request bodyapplication/json

CommandDefinition

namestringrequired
Lowercase slash-command name; help, cancel and status are reserved.
matches ^[a-z][a-z0-9_]{0,31}$
descriptionstringrequired
1–2000 chars
optionsCommandOption[]required
1–25 items
options fields
- namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
- descriptionstring
  0–200 chars
- typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
- requiredboolean
- choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
- mininteger
  ≥ 0
- maxinteger
  ≥ 0
- minLengthinteger
  ≥ 0
- maxLengthinteger
  ≥ 0
- acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
- maxBytesinteger
  FILE only.
  > 0
- multipleboolean
  FILE only: accept up to 10 files.
positionalParameterstring | null
STRING option that receives free text typed after the command. Defaults to the first required string option; null or empty for none.
maxAmountstring
Optional cap on every offer for this command, in atomic USDC.
matches ^[1-9]\d*$
termsCommandTermsrequired
Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
terms fields
- deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
- reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
- revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
- refundPolicystringrequired
  1–2000 chars
- sideEffectsstringrequired
  1–2000 chars
- dataUsestringrequired
  1–2000 chars
- verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
expectedRevisionIdstring
Updates only: fails with REVISION_CONFLICT unless this is the active revision.

Response 200application/json

The updated command

Command

idstringrequired
namestringrequired
descriptionstringrequired
archivedAtstring | nullrequired
createdAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionCommandRevision | nullrequired
revision fields
- idstringrequired
- commandIdstringrequired
- optionsCommandOption[]required
  options fields
  namestringrequired
  Lowercase slash-command name; help, cancel and status are reserved.
  matches ^[a-z][a-z0-9_]{0,31}$
  descriptionstring
  0–200 chars
  typestringrequired
  "STRING" | "INTEGER" | "NUMBER" | "BOOLEAN" | "FILE"
  requiredboolean
  choices(string | number)[]
  Allowed values; strings for STRING, numbers for INTEGER and NUMBER.
  1–50 items
  mininteger
  ≥ 0
  maxinteger
  ≥ 0
  minLengthinteger
  ≥ 0
  maxLengthinteger
  ≥ 0
  acceptstring[]
  FILE only: allowed MIME types; image/* wildcards work.
  1–20 items
  maxBytesinteger
  FILE only.
  > 0
  multipleboolean
  FILE only: accept up to 10 files.
- inputSchemamaprequired
  JSON Schema (2020-12) compiled from the options.
- outputSchemamap | nullrequired
- positionalParameterstring | nullrequired
- maxGrossAmountstring | nullrequired
- termsCommandTermsrequired
  Terms every quote of the command signs. Delivery, review, grace and quote lifetime together must fit the deployment's maximum hold.
  terms fields
  deliverySecondsintegerrequired
  Longest time to deliver; an offer may only shorten it.
  > 0
  reviewSecondsintegerrequired
  How long the buyer has to review before funds release.
  ≥ 0
  revisionPolicyobjectrequired
  revisionPolicy fields
  maxIncludedintegerrequired
  In-scope revisions included in the price.
  ≥ 0
  descriptionstringrequired
  1–1000 chars
  refundPolicystringrequired
  1–2000 chars
  sideEffectsstringrequired
  1–2000 chars
  dataUsestringrequired
  1–2000 chars
  verificationobject
  Evidence floor that gates release. Defaults to SIGN.
  verification fields
  minEvidencestringrequired
  "SIGN" | "REC"
- deliverySecondsintegerrequired
- reviewSecondsintegerrequired
- createdAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

400
Bad request
INVALID_COMMANDCOMMAND_OPTIONS_REQUIREDINVALID_COMMAND_SCHEMAINVALID_POSITIONAL_PARAMETERINVALID_MAX_AMOUNTINVALID_TERMSTERMS_EXCEED_POLICY
401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
404
Not found
COMMAND_NOT_FOUND
409
Conflict with the current state
COMMAND_NAME_TAKENREVISION_CONFLICT
422
Rejected by the deployment policy
PRICE_BELOW_FLOOR
429
Rate limited
RATE_LIMITED

curl

curl -X PATCH "https://payvoke.up.railway.app/v1/provider/apps/$APP_ID/commands/$COMMAND_ID" \
  -H "Authorization: Bearer $PAYVOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "options": [
      {
        "name": "string",
        "type": "STRING"
      }
    ],
    "terms": {
      "deliverySeconds": 1,
      "reviewSeconds": 0,
      "revisionPolicy": {
        "maxIncluded": 0,
        "description": "string"
      },
      "refundPolicy": "string",
      "sideEffects": "string",
      "dataUse": "string"
    }
  }'

Set the default command

POST/v1/provider/apps/{appId}/commands/{commandId}/default

Scope products:write

The command plain chat messages and offers without a commandId use. An app needs a default command to be available.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
commandIdstringrequired
A command id.

Response 200application/json

The new default

object

defaultCommandIdstringrequired

Errors{ error: CODE }

400
Bad request
COMMAND_NOT_READY
401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE