> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Update settings
> _Requires the `settings:write` scope (or a broader one that includes it)._
Performs a sparse update of settings. Only properties present in the request body are updated — omitted properties are left unchanged.
Nested sections follow the same rule: include only the fields you want to change within each section.
**Contact stages and account stages** are an exception — when the `contactStages` or `accountStages` array is present, all 8 stages must be provided with unique IDs (1–8).
## OpenAPI
````yaml /api-reference/bundled.yaml patch /v3/settings
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: User Account
description: Account information and authentication verification
- name: Accounts
description: Manage accounts (companies/organizations)
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, generated step types, and playbook/knowledge-base connections
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
- name: Account Lists
description: Manage account lists and account membership
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Custom Fields
description: Manage custom contact fields
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Contacts
description: Manage individual contacts
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Email Templates
description: Manage email templates and template folders
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads and per-team thread categories — list/filter, read
state, replies, category assignment, and meeting-intent flagging
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: Schedules
description: Manage email send schedules and timing
- name: Settings
description: Manage team and user settings
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Sequences
description: Manage email automation sequences
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: Tasks
description: Manage tasks and to-do items
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
paths:
/v3/settings:
patch:
tags:
- Settings
summary: Update settings
description: >-
_Requires the `settings:write` scope (or a broader one that
includes it)._
Performs a sparse update of settings. Only properties present in the
request body are updated — omitted properties are left unchanged.
Nested sections follow the same rule: include only the fields you want
to change within each section.
**Contact stages and account stages** are an exception — when the
`contactStages` or `accountStages` array is present, all 8 stages must
be provided with unique IDs (1–8).
operationId: UpdateSettings
requestBody:
required: true
content:
application/json:
schema:
type: object
title: Settings
description: >-
Team and user settings. All properties are nullable — on GET,
null means the setting is not configured or not applicable. On
PATCH, only properties present in the JSON body are updated.
properties:
account:
type: object
description: User profile settings
properties:
firstName:
type: string
nullable: true
maxLength: 48
description: User's first name
lastName:
type: string
nullable: true
maxLength: 48
description: User's last name
company:
type: string
nullable: true
maxLength: 48
description: Company name
phone:
type: string
nullable: true
description: Phone number
title:
type: string
nullable: true
maxLength: 72
description: Job title
timezone:
type: string
nullable: true
description: IANA timezone identifier (e.g. "America/New_York")
emails:
type: object
description: Email-related settings
properties:
isEmailQualityCheckEnabled:
type: boolean
nullable: true
description: Whether email quality checks are enabled before sending
safety:
type: object
description: Email safety and throttling settings
properties:
firstStepDelay:
type: integer
nullable: true
minimum: 0
description: >-
Delay in minutes before sending the first step of a
sequence
prospectEmailsPerDayLimit:
type: integer
nullable: true
minimum: 1
description: >-
Maximum number of emails sent to a single prospect
per day
nonRepliesHandlingType:
type: integer
nullable: true
minimum: 0
maximum: 2
description: >-
How to handle non-replies: 0 = do nothing, 1 =
pause, 2 = mark as finished
inboxNonRepliesHandlingType:
type: integer
nullable: true
minimum: 0
maximum: 1
description: >-
How to handle inbox non-replies: 0 = do nothing, 1 =
pause
inbox:
type: object
description: Email inbox settings
properties:
bccList:
type: string
nullable: true
description: >-
Comma-separated list of BCC email addresses for
outgoing emails
repliesBccList:
type: string
nullable: true
description: >-
Comma-separated list of BCC email addresses for
replies
forwardOnlyReplies:
type: boolean
nullable: true
description: >-
Whether to forward only replies (not all incoming
emails)
outOfOffice:
type: object
description: Out-of-office detection and handling settings
properties:
isResumeOutOfOfficeContactsEnabled:
type: boolean
nullable: true
description: >-
Whether to automatically resume contacts who return
from out-of-office
isUseSmartReturnDateEnabled:
type: boolean
nullable: true
description: >-
Whether to use smart return date detection from
out-of-office messages
defaultDaysToWaitBeforeResumingOutOfOffice:
type: integer
nullable: true
minimum: 1
description: >-
Default number of days to wait before resuming a
contact after out-of-office
maximumDaysThresholdBeforeResumingOutOfOffice:
type: integer
nullable: true
minimum: 1
description: >-
Maximum number of days to wait before resuming a
contact after out-of-office
isOpenTrackingDisabled:
type: boolean
nullable: true
description: Whether open tracking is disabled for emails
isAutomaticEmailValidationEnabled:
type: boolean
nullable: true
description: >-
Whether automatic email validation is enabled for new
contacts
reassignSequenceProspectsWhenEmailAccountAdded:
type: boolean
nullable: true
description: >-
Whether to reassign sequence prospects when a new email
account is added
linkedIn:
type: object
description: LinkedIn-related settings
properties:
reassignSequenceProspectsWhenLinkedInAccountAdded:
type: boolean
nullable: true
description: >-
Whether to reassign sequence prospects when a new
LinkedIn account is added
calls:
type: object
description: Call-related settings
properties:
isTeamCallsEnabled:
type: boolean
nullable: true
description: >-
Whether team cloud calls are enabled. Only the team
owner can change this setting.
resolutions:
type: array
nullable: true
description: List of call resolution options
items:
type: object
description: A call resolution option
required:
- name
properties:
id:
type: integer
nullable: true
description: >-
Resolution ID. Null when creating a new
resolution.
name:
type: string
maxLength: 128
description: Display name of the resolution
defaultResolutionValue:
type: integer
nullable: true
minimum: 0
maximum: 2
description: >-
Default resolution value: 0 = interested, 1 = not
interested, 2 = not reached. Required when
creating a new resolution (id is null).
isDefault:
type: boolean
description: Whether this is the default resolution
contacts:
type: object
description: Contact-related settings
properties:
handling:
type: object
description: Contact handling behavior settings
properties:
pauseProspectOrganizationMode:
type: boolean
nullable: true
description: >-
Whether to pause contacts from the same organization
when one replies
pauseProspectOrganizationValue:
type: integer
nullable: true
minimum: 1
maximum: 2
description: >-
Organization pause scope: 1 = same sequence, 2 = all
sequences
pauseProspectInAllCampaignMode:
type: boolean
nullable: true
description: >-
Whether to pause a contact in all sequences when
they reply in one
pauseProspectInAllCampaignValue:
type: integer
nullable: true
minimum: 1
maximum: 2
description: >-
All-campaign pause scope: 1 = pause, 2 = mark as
finished
leaveProspectsInSequenceWhenMovingToAnother:
type: boolean
nullable: true
description: >-
Whether to keep contacts in the original sequence
when moving them to another
enrichProspectWhenLinkedInUrlIsMissing:
type: boolean
nullable: true
description: >-
Whether to attempt LinkedIn URL enrichment when a
contact's LinkedIn URL is missing
contactAccounts:
type: object
description: Contact account (company) settings
properties:
autoPopulate:
type: boolean
nullable: true
description: >-
Whether to automatically populate contact accounts
from contact data
overwriteFields:
type: boolean
nullable: true
description: >-
Whether to overwrite existing contact account fields
with new data
contactStages:
type: array
nullable: true
description: >-
Custom contact stage definitions. When updating, all 8
stages must be provided.
items:
type: object
description: A custom contact stage definition
required:
- id
- name
properties:
id:
type: integer
minimum: 1
maximum: 8
description: Stage ID (1–8)
name:
type: string
maxLength: 21
description: Display name of the stage
colorId:
type: integer
nullable: true
description: Color identifier for the stage
description:
type: string
nullable: true
description: Description of the stage
accountStages:
type: array
nullable: true
description: >-
Custom account stage definitions. When updating, all 8
stages must be provided.
items:
type: object
description: A custom account stage definition
required:
- id
- name
properties:
id:
type: integer
minimum: 1
maximum: 8
description: Stage ID (1–8)
name:
type: string
maxLength: 64
description: Display name of the stage
colorId:
type: integer
nullable: true
description: Color identifier for the stage
beta:
type: object
description: Beta features settings
properties:
isBetaFeaturesEnabled:
type: boolean
nullable: true
description: >-
Whether beta features are enabled for this team. Only
the team owner can change this setting.
responses:
'200':
description: >-
Settings updated successfully — returns the full settings object
after applying changes
content:
application/json:
schema:
type: object
title: Settings
description: >-
Team and user settings. All properties are nullable — on GET,
null means the setting is not configured or not applicable. On
PATCH, only properties present in the JSON body are updated.
properties:
account:
type: object
description: User profile settings
properties:
firstName:
type: string
nullable: true
maxLength: 48
description: User's first name
lastName:
type: string
nullable: true
maxLength: 48
description: User's last name
company:
type: string
nullable: true
maxLength: 48
description: Company name
phone:
type: string
nullable: true
description: Phone number
title:
type: string
nullable: true
maxLength: 72
description: Job title
timezone:
type: string
nullable: true
description: IANA timezone identifier (e.g. "America/New_York")
emails:
type: object
description: Email-related settings
properties:
isEmailQualityCheckEnabled:
type: boolean
nullable: true
description: >-
Whether email quality checks are enabled before
sending
safety:
type: object
description: Email safety and throttling settings
properties:
firstStepDelay:
type: integer
nullable: true
minimum: 0
description: >-
Delay in minutes before sending the first step of
a sequence
prospectEmailsPerDayLimit:
type: integer
nullable: true
minimum: 1
description: >-
Maximum number of emails sent to a single prospect
per day
nonRepliesHandlingType:
type: integer
nullable: true
minimum: 0
maximum: 2
description: >-
How to handle non-replies: 0 = do nothing, 1 =
pause, 2 = mark as finished
inboxNonRepliesHandlingType:
type: integer
nullable: true
minimum: 0
maximum: 1
description: >-
How to handle inbox non-replies: 0 = do nothing, 1
= pause
inbox:
type: object
description: Email inbox settings
properties:
bccList:
type: string
nullable: true
description: >-
Comma-separated list of BCC email addresses for
outgoing emails
repliesBccList:
type: string
nullable: true
description: >-
Comma-separated list of BCC email addresses for
replies
forwardOnlyReplies:
type: boolean
nullable: true
description: >-
Whether to forward only replies (not all incoming
emails)
outOfOffice:
type: object
description: Out-of-office detection and handling settings
properties:
isResumeOutOfOfficeContactsEnabled:
type: boolean
nullable: true
description: >-
Whether to automatically resume contacts who
return from out-of-office
isUseSmartReturnDateEnabled:
type: boolean
nullable: true
description: >-
Whether to use smart return date detection from
out-of-office messages
defaultDaysToWaitBeforeResumingOutOfOffice:
type: integer
nullable: true
minimum: 1
description: >-
Default number of days to wait before resuming a
contact after out-of-office
maximumDaysThresholdBeforeResumingOutOfOffice:
type: integer
nullable: true
minimum: 1
description: >-
Maximum number of days to wait before resuming a
contact after out-of-office
isOpenTrackingDisabled:
type: boolean
nullable: true
description: Whether open tracking is disabled for emails
isAutomaticEmailValidationEnabled:
type: boolean
nullable: true
description: >-
Whether automatic email validation is enabled for new
contacts
reassignSequenceProspectsWhenEmailAccountAdded:
type: boolean
nullable: true
description: >-
Whether to reassign sequence prospects when a new
email account is added
linkedIn:
type: object
description: LinkedIn-related settings
properties:
reassignSequenceProspectsWhenLinkedInAccountAdded:
type: boolean
nullable: true
description: >-
Whether to reassign sequence prospects when a new
LinkedIn account is added
calls:
type: object
description: Call-related settings
properties:
isTeamCallsEnabled:
type: boolean
nullable: true
description: >-
Whether team cloud calls are enabled. Only the team
owner can change this setting.
resolutions:
type: array
nullable: true
description: List of call resolution options
items:
type: object
description: A call resolution option
required:
- name
properties:
id:
type: integer
nullable: true
description: >-
Resolution ID. Null when creating a new
resolution.
name:
type: string
maxLength: 128
description: Display name of the resolution
defaultResolutionValue:
type: integer
nullable: true
minimum: 0
maximum: 2
description: >-
Default resolution value: 0 = interested, 1 =
not interested, 2 = not reached. Required when
creating a new resolution (id is null).
isDefault:
type: boolean
description: Whether this is the default resolution
contacts:
type: object
description: Contact-related settings
properties:
handling:
type: object
description: Contact handling behavior settings
properties:
pauseProspectOrganizationMode:
type: boolean
nullable: true
description: >-
Whether to pause contacts from the same
organization when one replies
pauseProspectOrganizationValue:
type: integer
nullable: true
minimum: 1
maximum: 2
description: >-
Organization pause scope: 1 = same sequence, 2 =
all sequences
pauseProspectInAllCampaignMode:
type: boolean
nullable: true
description: >-
Whether to pause a contact in all sequences when
they reply in one
pauseProspectInAllCampaignValue:
type: integer
nullable: true
minimum: 1
maximum: 2
description: >-
All-campaign pause scope: 1 = pause, 2 = mark as
finished
leaveProspectsInSequenceWhenMovingToAnother:
type: boolean
nullable: true
description: >-
Whether to keep contacts in the original sequence
when moving them to another
enrichProspectWhenLinkedInUrlIsMissing:
type: boolean
nullable: true
description: >-
Whether to attempt LinkedIn URL enrichment when a
contact's LinkedIn URL is missing
contactAccounts:
type: object
description: Contact account (company) settings
properties:
autoPopulate:
type: boolean
nullable: true
description: >-
Whether to automatically populate contact accounts
from contact data
overwriteFields:
type: boolean
nullable: true
description: >-
Whether to overwrite existing contact account
fields with new data
contactStages:
type: array
nullable: true
description: >-
Custom contact stage definitions. When updating, all 8
stages must be provided.
items:
type: object
description: A custom contact stage definition
required:
- id
- name
properties:
id:
type: integer
minimum: 1
maximum: 8
description: Stage ID (1–8)
name:
type: string
maxLength: 21
description: Display name of the stage
colorId:
type: integer
nullable: true
description: Color identifier for the stage
description:
type: string
nullable: true
description: Description of the stage
accountStages:
type: array
nullable: true
description: >-
Custom account stage definitions. When updating, all 8
stages must be provided.
items:
type: object
description: A custom account stage definition
required:
- id
- name
properties:
id:
type: integer
minimum: 1
maximum: 8
description: Stage ID (1–8)
name:
type: string
maxLength: 64
description: Display name of the stage
colorId:
type: integer
nullable: true
description: Color identifier for the stage
beta:
type: object
description: Beta features settings
properties:
isBetaFeaturesEnabled:
type: boolean
nullable: true
description: >-
Whether beta features are enabled for this team. Only
the team owner can change this setting.
'400':
description: |-
Validation failure on the request body, or a business rule rejection
(e.g. a sparse-update rule that requires all 8 contact stages when
`contactStages` is present).
content:
application/problem+json:
schema:
oneOf:
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail
string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures
the pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message
on body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when
the request body
fails binding, FluentValidator rules, or when
route/query parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]`
array — clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the
form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling;
use `detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a
given resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced
error slug.
Emitted for most 4xx responses (business 400, 403,
404, 409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
examples:
validation_failed:
summary: Body validation failure (FluentValidator)
value:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /contacts/contactStages
detail: Exactly 8 contact stages required, got 6.
business_invalid_op:
summary: Domain rule rejection
value:
title: Bad Request
status: 400
detail: Cannot update settings while the team is suspended.
code: settings.invalidOperation
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: Non-owner user tried to change an owner-only field
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
example:
title: Forbidden
status: 403
detail: >-
Only the team owner can change: isTeamCallsEnabled,
isBetaFeaturesEnabled.
code: settings.forbidden
'404':
description: User or team settings not found
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Not Found
status: 404
detail: The requested resource was not found.
code: sequence.notFound
example:
title: Not Found
status: 404
detail: User settings not found.
code: settings.notFound
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: Rate limit exceeded. Retry after 60 seconds.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````