Grant templates

List grant templates

get/api/v1/grant-templates

What this account’s agents may ask a person for: a scope (`name`, and the `label` the consent screen says), where (`audience`), for what (`subject_type`), a ceiling and a longest term. Any key reads them.

Responses

• 200The templates.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

curl https://pidgeon.ai/api/v1/grant-templates \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Define a grant template

post/api/v1/grant-templates

Needs a key with admin on the whole account: a template is the account speaking to everybody its agents ask. A grant copies its template’s words when it is asked for, so a template is never edited, only retired.

Parameters

• Idempotency-Keystring

  Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Body

• namestringrequired

  The scope’s stable name, for software: `bookings.change`.

• labelstringrequired

  What the agent may do, as the consent screen says it after "wants to": `manage your bookings`.

• audiencestring

  The domain the agent will act with. A grant reaching anywhere else does not hold.

• audience_namestring

  How people call it: `Delta`.

• subject_typeenumrequired

  What a grant is for: a customer, an account or an order.

  customer · account · order

• limitobject

  A ceiling the grant states, such as "refunds up to $100".

• max_daysnumber

  The longest a grant from this template may last. 90 when omitted.

Responses

• 201The template.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409Nothing was done by this call. `error.code` says which: `idempotency_in_progress` when the first request with this `Idempotency-Key` has not answered yet (wait `Retry-After` seconds and send it again), `idempotency_mismatch` when the key was used with a different request (use a new key).
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.
• 504Test mode only: `Pidgeon-Test-Fail: drop` dropped the answer (`test_dropped`). The request was done; retry it with the same `Idempotency-Key` to get the first answer.

curl https://pidgeon.ai/api/v1/grant-templates \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Retire a grant template

delete/api/v1/grant-templates/{id}

No new grant can be asked for from it. Every grant already given is unchanged.

Parameters

• idstringrequired
• Idempotency-Keystring

  Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Responses

• 200Retired.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409Nothing was done by this call. `error.code` says which: `idempotency_in_progress` when the first request with this `Idempotency-Key` has not answered yet (wait `Retry-After` seconds and send it again), `idempotency_mismatch` when the key was used with a different request (use a new key).
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.
• 504Test mode only: `Pidgeon-Test-Fail: drop` dropped the answer (`test_dropped`). The request was done; retry it with the same `Idempotency-Key` to get the first answer.

curl https://pidgeon.ai/api/v1/grant-templates/{id} \
  -X DELETE \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json