f.findocs
Start building
API reference / Automations

Rotate webhook secret

POST/v1/users/{userId}/automations/{automationId}/rotate-webhook-secret

Mints a new inbound webhook secret for the automation; the previous one stops working at once. Only works on an enabled automation whose rule has an event wake: anything else is refused as automation_changed, the same reason a stale revision gets, even when the revision sent is perfectly current. revision must match the automation's current one.

Authentication

Both headers are required.

  • Header: X-Api-Key: YOUR_API_KEY
  • Header: Authorization: Bearer YOUR_USER_TOKEN

Path parameters

userIdstring · uuidrequired

The user in the path; must equal the token's own account.

Validation rules
Format
"uuid"
Pattern
"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
automationIdstring · uuidrequired

The automation's id.

Validation rules
Format
"uuid"
Pattern
"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

Request body required

application/json · object

Additional properties are not allowed.

revisionstringrequired

The automation's concurrency token, <definitionVersion>.<activationEpoch>, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as automation_changed.

Validation rules
Pattern
"^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

Request example

Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it.

curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/rotate-webhook-secret' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-binary '@request.json'

Responses

200 The new webhook secret and where it is received.

The new webhook secret and where it is received.

application/json · object

secretstringrequired

The new webhook secret. Shown once; it cannot be read back later.

Validation rules
Pattern
"^[A-Za-z0-9_-]{43}$"
keyIdstring · uuidrequired

The new secret's id.

Validation rules
Format
"uuid"
Pattern
"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
pathstringrequired

The path this automation's webhook receives requests on.

definitionVersionintegerrequired

The definition version this secret was minted for.

Validation rules
Greater than
0
Maximum
9007199254740991
400 The request could not be read as this operation expects.

The request could not be read as this operation expects.

  • invalid_input — the body or query failed validation; issues names each field
  • invalid_cursor — the cursor is not one this list minted

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

401 A credential is missing, invalid or expired.

A credential is missing, invalid or expired.

  • partner_key_required — no X-Api-Key header was sent
  • partner_key_invalid — the X-Api-Key is unknown or revoked
  • credential_expired — the user token has expired; obtain a fresh one

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

403 The credentials are valid but may not do this.

The credentials are valid but may not do this.

  • subject_mismatch — the {userId} in the path is not the token's user
  • account_disabled — an operator disabled the account
  • origin_rejected — a browser Origin other than the configured web origin

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.

The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

409 The operation lost to the current state.

The operation lost to the current state.

  • automation_changed — the revision sent is stale; reload the automation

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

412 The identity is verified but has no account yet.

The identity is verified but has no account yet.

  • account_not_provisioned — the identity is verified but has no account yet; call users.ensure first

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

413 The body exceeds the size this deployment accepts.

The body exceeds the size this deployment accepts.

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

429 A limiter refused the request; honour `Retry-After`.

A limiter refused the request; honour Retry-After.

  • rate_limited — the per-key or per-user limit is spent; honour Retry-After

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

500 A fault on our side; quote `requestId` when reporting it.

A fault on our side; quote requestId when reporting it.

  • internal — a fault on our side; quote requestId when reporting it

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

503 The replica is draining or a dependency did not answer; `retryable` says whether to try again.

The replica is draining or a dependency did not answer; retryable says whether to try again.

  • internal — a fault on our side; quote requestId when reporting it

application/problem+json · object

RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack.

typestringrequired

The kind of problem as a URN, urn:fin:error:<kind>; stable, compare against it

titlestringrequired

The kind's human title, for logs; never parse it

statusintegerrequired

The HTTP status, repeated in the body

Validation rules
Minimum
400
Maximum
599
reasonstringoptional

The machine-readable why. One of:

  • run_active (409) — a run already holds this conversation
  • budget_exhausted (409) — the user's spend headroom is gone, or an operator froze it
  • approval_not_pending (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation
  • execution_capacity (409) — no execution capacity is free right now; retryable says whether to try again
  • execution_unavailable (409) — the execution engine could not take the work
  • stop_pending (409) — a stop is already in progress and its cleanup is not yet confirmed
  • automation_changed (409) — the revision sent is stale; reload the automation
  • automation_held (409) — an operator holds the automation; it fires again when released
  • automation_invalid (409) — the automation's definition cannot run as written
  • automation_completed (409) — the automation has finished for good and cannot fire again
  • automation_limit (409) — the user already has as many automations as the deployment allows
  • profile_unknown_tool (409) — the run profile names a tool this deployment does not have
  • deployment_paused (409) — an operator paused a deployment control; nothing was admitted or fired
  • run_not_active (409) — the run named in the path is not the conversation's live run
  • withdrawal_changed (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress
  • credential_expired (401) — the user token has expired; obtain a fresh one
  • account_disabled (403) — an operator disabled the account
  • account_not_provisioned (412) — the identity is verified but has no account yet; call users.ensure first
  • provider_unavailable (503) — an external provider the call depends on did not answer
  • engine_unavailable (503) — the execution engine did not answer
  • invalid_input (400) — the body or query failed validation; issues names each field
  • internal (500) — a fault on our side; quote requestId when reporting it
  • partner_key_required (401) — no X-Api-Key header was sent
  • partner_key_invalid (401) — the X-Api-Key is unknown or revoked
  • subject_mismatch (403) — the {userId} in the path is not the token's user
  • origin_rejected (403) — a browser Origin other than the configured web origin
  • permission_required (403) — the operator credential lacks the scope this call needs
  • rate_limited (429) — the per-key or per-user limit is spent; honour Retry-After
  • stream_capacity (429) — no stream socket is free on this replica or for this user; honour Retry-After
  • invalid_cursor (400) — the cursor is not one this list minted
Validation rules
Allowed values
["run_active","budget_exhausted","approval_not_pending","execution_capacity","execution_unavailable","stop_pending","automation_changed","automation_held","automation_invalid","automation_completed","automation_limit","profile_unknown_tool","deployment_paused","run_not_active","withdrawal_changed","credential_expired","account_disabled","account_not_provisioned","provider_unavailable","engine_unavailable","invalid_input","internal","partner_key_required","partner_key_invalid","subject_mismatch","origin_rejected","permission_required","rate_limited","stream_capacity","invalid_cursor"]
requestIdstringrequired

The id Fin used for this request; quote it when reporting a problem

retryablebooleanrequired

Whether repeating the same request later can succeed without changing it

detailstringoptional

Only on invalid_input: which part of the request failed validation

issuesarrayoptional

Only on invalid_input: one entry per failing field

Show attributes

Only on invalid_input: one entry per failing field

Array items · object
pathstringrequired

The JSON pointer of the failing field; empty for the root object

messagestringrequired

Why the field failed

Complete OpenAPI definition

The exact operation and all referenced components, including recursive schemas.

{
  "operation": {
    "operationId": "automations.rotateWebhookSecret",
    "summary": "Rotate webhook secret",
    "tags": [
      "automations"
    ],
    "description": "Mints a new inbound webhook secret for the automation; the previous one stops working at once. Only works on an enabled automation whose rule has an event wake: anything else is refused as `automation_changed`, the same reason a stale `revision` gets, even when the revision sent is perfectly current. `revision` must match the automation's current one.",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "revision": {
                "type": "string",
                "pattern": "^[1-9]\\d*\\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
                "description": "The automation's concurrency token, `<definitionVersion>.<activationEpoch>`, unique to one exact version. Writes must echo the value just read back unchanged; a stale one is refused as `automation_changed`."
              }
            },
            "required": [
              "revision"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "parameters": [
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "userId",
        "required": true,
        "description": "The user in the path; must equal the token's own account."
      },
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "automationId",
        "required": true,
        "description": "The automation's id."
      }
    ],
    "security": [
      {
        "apiKey": [],
        "userToken": []
      }
    ],
    "responses": {
      "200": {
        "description": "The new webhook secret and where it is received.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "secret": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9_-]{43}$",
                  "description": "The new webhook secret. Shown once; it cannot be read back later."
                },
                "keyId": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "The new secret's id."
                },
                "path": {
                  "type": "string",
                  "description": "The path this automation's webhook receives requests on."
                },
                "definitionVersion": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "maximum": 9007199254740991,
                  "description": "The definition version this secret was minted for."
                }
              },
              "required": [
                "secret",
                "keyId",
                "path",
                "definitionVersion"
              ]
            }
          }
        }
      },
      "400": {
        "$ref": "#/components/responses/InvalidInput"
      },
      "401": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "403": {
        "$ref": "#/components/responses/Forbidden"
      },
      "404": {
        "$ref": "#/components/responses/NotFound"
      },
      "409": {
        "description": "The operation lost to the current state.\n\n- `automation_changed` — the `revision` sent is stale; reload the automation",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "412": {
        "$ref": "#/components/responses/AccountNotProvisioned"
      },
      "413": {
        "$ref": "#/components/responses/PayloadTooLarge"
      },
      "429": {
        "$ref": "#/components/responses/TooManyRequests"
      },
      "500": {
        "$ref": "#/components/responses/Internal"
      },
      "503": {
        "$ref": "#/components/responses/Unavailable"
      }
    }
  },
  "components": {
    "responses": {
      "InvalidInput": {
        "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "AccountNotProvisioned": {
        "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The body exceeds the size this deployment accepts.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Internal": {
        "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The kind of problem as a URN, `urn:fin:error:<kind>`; stable, compare against it"
          },
          "title": {
            "type": "string",
            "description": "The kind's human title, for logs; never parse it"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "The HTTP status, repeated in the body"
          },
          "reason": {
            "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted",
            "type": "string",
            "enum": [
              "run_active",
              "budget_exhausted",
              "approval_not_pending",
              "execution_capacity",
              "execution_unavailable",
              "stop_pending",
              "automation_changed",
              "automation_held",
              "automation_invalid",
              "automation_completed",
              "automation_limit",
              "profile_unknown_tool",
              "deployment_paused",
              "run_not_active",
              "withdrawal_changed",
              "credential_expired",
              "account_disabled",
              "account_not_provisioned",
              "provider_unavailable",
              "engine_unavailable",
              "invalid_input",
              "internal",
              "partner_key_required",
              "partner_key_invalid",
              "subject_mismatch",
              "origin_rejected",
              "permission_required",
              "rate_limited",
              "stream_capacity",
              "invalid_cursor"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "The id Fin used for this request; quote it when reporting a problem"
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether repeating the same request later can succeed without changing it"
          },
          "detail": {
            "description": "Only on `invalid_input`: which part of the request failed validation",
            "type": "string"
          },
          "issues": {
            "description": "Only on `invalid_input`: one entry per failing field",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string",
                  "description": "The JSON pointer of the failing field; empty for the root object"
                },
                "message": {
                  "type": "string",
                  "description": "Why the field failed"
                }
              },
              "required": [
                "path",
                "message"
              ]
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "requestId",
          "retryable"
        ],
        "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack."
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "userToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}
Fin documentation Built from the API contract · v1

Search all documentation

↑ ↓ to navigate ↵ to openesc to close