Instance

Replace the configuration

Replaces the instance configuration with the body and returns it. A setting you leave out goes back to its default, so send the whole configuration with your change. To change only some settings, use PATCH. Requires config.manage.

PUT
/config

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Header parameters

X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body
instance_id?string

This instance's ID, accepted so you can send back what GET /config returned. It sets nothing.

Length1 <= length
version_recent_days?integer

Days within which every version is kept. Zero makes this window empty. Absent: the environment default applies.

Range0 <= value <= 36500
Default30
version_daily_snapshot_days?integer

Days within which a daily version is kept. Must be at least version_recent_days. Absent: the environment default applies.

Range0 <= value <= 36500
Default90
version_weekly_snapshot_days?integer

Days within which a weekly version is kept. Must be at least version_daily_snapshot_days. Absent: the environment default applies.

Range0 <= value <= 36500
Default365
version_max_versions?integer

Maximum versions per item, after applying the time windows. Per-type policy overrides these instance defaults.

Range1 <= value <= 1000000
Default500
grant_inactivity_days?integer

Disconnect apps unused for this many days. Zero disables retirement.

Range0 <= value <= 36500
Default365
enrichment_enabled?boolean

true if Marfa reads text and dimensions from files. An active extraction can finish after disabling. Absent: the environment default applies.

Defaulttrue
enrichment_ocr_enabled?boolean

true if file reading includes image text. Enabling reconsiders previously skipped images. Absent: the environment default applies.

Defaulttrue
error_reporting_enabled?boolean

true if exception reports are sent. Enabling requires both posthog_host and posthog_project_token. Absent: the environment default applies.

Defaulttrue
heartbeat_enabled?boolean

true if scheduled heartbeat requests are sent. Enabling requires heartbeat_url. Absent: the environment default applies.

Defaulttrue
name?string

The instance's display name, without control or bidirectional formatting characters. Spaces at each end are trimmed. Absent: Marfa.

Length1 <= length <= 200
enforcement?

The instance's enforcement levers. Each applies to every credential that doesn't set the same lever itself. Absent: no lever is on.

audit_retention_days?integer

Days Marfa keeps audit log entries and outbound webhook delivery history. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default90
event_log_retention_days?integer

Days Marfa keeps events, which a stream can replay from a cursor, and the answers it replays for an Idempotency-Key. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
trash_retention_days?integer

Days an item stays in the trash before Marfa purges it. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default60
row_log_retention_days?integer

Days a table keeps a batch in its change log, so you can undo it. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
inbound_handled_retention_days?integer

Days Marfa keeps inbound webhook deliveries a connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default7
inbound_pending_retention_days?integer

Days Marfa keeps inbound webhook deliveries no connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
addresses?array<string>

The addresses people reach this instance at, each an origin with no path. The sign-in address is always one of them.

Default[]
sign_in_address?string

The address people sign in at, an origin with no path. Absent: this computer's own address.

confirm_sign_in_address_change?boolean

true to confirm a change that moves the sign-in address of a claimed instance. It sets nothing.

skip_sign_in_address_check?boolean

true moves the sign-in address without first checking that it answers as this instance, for a host that answers only after the move. Only the private local command can send it.

backup_path?string

The absolute path of the folder Marfa backs itself up to and keeps a second copy of each file in, outside the data directory and the blob folder. Changing it needs a sign-in from the last fifteen minutes. Absent: no backup folder.

object_store_bucket?string

The bucket of an S3-compatible object store that also keeps each file and the backups: 1 to 255 ASCII letters, digits, ., :, - and _, other than . and ... Changing it needs a sign-in from the last fifteen minutes, and removes object_store_secret_access_key unless the same request sets it. Absent: no object store.

Lengthlength <= 255
object_store_region?string

The region of the object store: a name of 1 to 63 ASCII letters, digits, hyphens and underscores that can be part of a host name, such as us-east-1 or auto. Changing it needs a sign-in from the last fifteen minutes. Absent: us-east-1.

Lengthlength <= 63
Default"us-east-1"
object_store_endpoint?string

The endpoint of the object store, an http or https URL with no user name or password. Changing it needs a sign-in from the last fifteen minutes, and removes object_store_secret_access_key unless the same request sets it. Absent: the store's provider chooses it.

Formaturi
object_store_path_style?boolean

true if the store at object_store_endpoint is addressed by path. false puts the bucket, as lowercase host labels, before the endpoint's host, a name without the bucket. Changing it needs a sign-in from the last fifteen minutes. Absent: true.

Defaulttrue
object_store_prefix?string

The folder in the bucket Marfa keeps files and backups under, as /-joined segments. Changing it needs a sign-in from the last fifteen minutes. Absent: marfa.

Default"marfa"
object_store_access_key_id?string

The access key ID for the object store.

Lengthlength <= 256
allow_private_addresses?boolean

true if Marfa may send webhooks, the heartbeat, exception reports and object store requests to loopback, private and other addresses that aren't public. Changing it needs a sign-in from the last fifteen minutes. Absent: false.

Defaultfalse
object_store_secret_access_key?string

The secret access key for the object store, with no whitespace around it. Marfa never returns it. A PUT that leaves it out keeps it, unless the PUT changes object_store_bucket or object_store_endpoint; PATCH with null removes it.

Lengthlength <= 4096
heartbeat_url?string

The http or https URL Marfa requests on a schedule, so that something else can notice when the requests stop. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
posthog_host?string

The PostHog host Marfa sends a report of each of its own faults to, for PostHog's error tracking. It must be an https URL, or an http URL on this machine, with no user name or password, and it needs posthog_project_token set too. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
posthog_project_token?string

The PostHog project token Marfa sends its fault reports with, with no whitespace around it. It needs posthog_host set too. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Lengthlength <= 256
telemetry_enabled?boolean

true if Marfa sends telemetry about itself: traces, log records and metrics to the OTLP endpoints, and exception reports to posthog_host. false sends none of them and keeps every telemetry setting. Absent: true.

Defaulttrue
otel_exporter_otlp_endpoint?string

The base URL of the OTLP receiver Marfa exports traces to, under v1/traces, log records to, under v1/logs, and metrics to, under v1/metrics, keeping its query. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
otel_exporter_otlp_traces_endpoint?string

The URL Marfa posts traces to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
otel_exporter_otlp_logs_endpoint?string

The URL Marfa posts log records to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
otel_exporter_otlp_metrics_endpoint?string

The URL Marfa posts metrics to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Formaturi
otel_exporter_otlp_headers?string

The headers Marfa sends with every OTLP export, as comma-separated key=value pairs with percent-encoded values and no whitespace around them. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Lengthlength <= 8192
otel_exporter_otlp_traces_headers?string

The headers Marfa sends with trace exports, as comma-separated key=value pairs with percent-encoded values. One here replaces the one of the same name in otel_exporter_otlp_headers. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Lengthlength <= 8192
otel_exporter_otlp_logs_headers?string

The headers Marfa sends with log exports, as comma-separated key=value pairs with percent-encoded values. One here replaces the one of the same name in otel_exporter_otlp_headers. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Lengthlength <= 8192
otel_exporter_otlp_metrics_headers?string

The headers Marfa sends with metric exports, as comma-separated key=value pairs with percent-encoded values. One here replaces the one of the same name in otel_exporter_otlp_headers. Marfa never returns it. A PUT that leaves it out keeps it; PATCH with null removes it.

Lengthlength <= 8192
otel_sample_ratio?number

The share of traces Marfa exports, from 0 to 1. A trace that holds an error is exported whatever this says. Absent: 0.05.

Range0 <= value <= 1
Default0.05
otel_service_name?string

The service name on everything Marfa exports, in place of a service.name in otel_resource_attributes. Absent: marfa-server. An archive doesn't carry it.

Lengthlength <= 255
otel_resource_attributes?string

Attributes Marfa adds to everything it exports, as comma-separated key=value pairs with percent-encoded values. One named here replaces Marfa's own of the same name, such as service.version. An archive doesn't carry it.

Lengthlength <= 4096
secrets_set?array<string>

The secret settings GET /config says are set, accepted so you can send back what it returned. It sets nothing.

max_request_bytes?integer

The largest request body Marfa accepts, in bytes. Marfa waits 180 seconds for a body, so a body over about 21 MiB can't arrive in time over a 1 Mbit/s link. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default1048576
max_bulk_request_bytes?integer

The largest body the bulk operations accept, in bytes, and the largest row a restore reads. The most you can set is 33554432, half the 67108864 bytes a restore reads on one archive line. Absent: the server's default applies.

Range1 <= value <= 33554432
Default16777216
disk_reserve_bytes?integer

Free disk space an upload must leave on the blob volume, in bytes. 0 refuses no write for room, and health still reports the disk as degraded below 64 MiB. Absent: the server's default applies.

Range0 <= value <= 1099511627776
Default134217728
blob_min_copies?integer

The fewest live copies Marfa keeps of each blob. Absent: the server's default applies.

Range1 <= value <= 1000000
Default1
blob_cleanup_enabled?boolean

true if the blob-orphans job purges blobs nothing references once they have stood in the orphan report for blob_cleanup_grace_seconds. Absent: the server's default applies.

Defaulttrue
blob_cleanup_grace_seconds?integer

How long a blob nothing references stands in the orphan report before a later run purges it, in seconds. Absent: the server's default applies.

Range0 <= value <= 31536000
Default86400
backup_interval_seconds?integer

How often Marfa makes a backup when anything it holds has changed, in seconds. 0 turns scheduled backups off. Absent: the server's default applies.

Range0 <= value <= 31536000
Default3600
rate_limit_enabled?boolean

true if the rate limiter is on for requests a key or app makes, app registrations, device code requests, passkey sign-in challenges and deliveries to inbound addresses. Absent: the server's default applies.

Defaulttrue
rate_limit_requests?integer

How many requests one key or app may make in each rate-limit window, across every operation. Absent: the server's default applies.

Range1 <= value <= 1000000
Default4000
rate_limit_keys_requests?integer

How many requests one key may make in each rate-limit window to the operations under /keys. Absent: the server's default applies.

Range1 <= value <= 1000000
Default200
rate_limit_window_seconds?integer

How long one rate-limit window lasts, in seconds. Absent: the server's default applies.

Range1 <= value <= 86400
Default60
unapproved_app_retention_hours?integer

Hours Marfa keeps an app that registered itself and holds no grant. 0 keeps it with no age limit. Absent: the server's default applies.

Range0 <= value <= 876000
Default1
revoked_grant_retention_days?integer

Days Marfa keeps a revoked app grant. 0 keeps it with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default90
enrichment_max_blob_bytes?integer

The largest file Marfa reads whole to extract its text, in bytes. Marfa skips a larger file unread, and reads a sound or video from its headers whatever its size. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default20971520
enrichment_max_text_chars?integer

The most Unicode characters of extracted text Marfa keeps, counted as characters and not UTF-16 code units. Marfa cuts longer text short. Absent: the server's default applies.

Range1 <= value <= 100000000
Default100000
enrichment_max_inflated_bytes?integer

The most a document may inflate to when Marfa extracts its text, all its parts together, in bytes. Marfa skips a document that inflates past it. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default67108864
enrichment_max_memory_bytes?integer

The most memory the process that reads one file may take, in bytes. Marfa skips a file that needs more. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default1073741824
enrichment_max_attempts?integer

How many times Marfa tries to read a file that fails, or that stops the server, before it stops trying. Absent: the server's default applies.

Range1 <= value <= 100
Default3
update_check_enabled?boolean

true if Marfa checks GitHub for new releases every few hours. When false, it makes no request for them and reports no release as newer. Absent: the server's default applies.

Defaulttrue
event_stream_max_viewers?integer

The most event-stream viewers one server serves at once. 0 sets no limit. Absent: the server's default applies.

Range0 <= value <= 1000000
Default0
mcp_fetch_enabled?boolean

true if MCP tools fetch a file from a web address, or a file a chat attached, to save it. When false, a tool asked to fetch one is refused. Absent: the server's default applies.

Defaulttrue
mcp_fetch_max_bytes?integer

The largest file an MCP tool fetches from a web address to save, in bytes. Marfa refuses a larger file and stores nothing. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default52428800
mcp_fetch_timeout_seconds?integer

How long an MCP tool's fetch of a file from a web address may take, from connecting to the last byte, in seconds. Absent: the server's default applies.

Range1 <= value <= 3600
Default60
inbound_max_bytes?integer

The largest inbound webhook delivery Marfa stores, in bytes. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default26214400
rate_limit_inbound_requests?integer

How many requests one inbound endpoint's address takes in each rate-limit window, whatever each is answered. Absent: the server's default applies.

Range1 <= value <= 1000000
Default600
inbound_in_flight_bytes?integer

The most bytes of inbound webhook deliveries Marfa holds in memory at once. One source holds at most half. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default104857600
inbound_backlog_deliveries?integer

The unhandled deliveries one registration may hold before Marfa refuses more for it. Absent: the server's default applies.

Range1 <= value <= 1000000
Default10000
inbound_backlog_bytes?integer

The bytes of unhandled deliveries one registration may hold before Marfa refuses more for it. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default1073741824
inbound_retained_deliveries?integer

The most deliveries one registration retains across its live and retired endpoints. Absent: the server's default applies.

Range1 <= value <= 1000000
Default10000
inbound_retained_bytes?integer

The most bytes of bodies, headers and queries one registration retains across its live and retired endpoints. Absent: the server's default applies.

Range1 <= value <= 1099511627776
Default1073741824
cors_origins?array<string>

The browser origins allowed to call the API across origins with a token, beside the web pages the owner approves. Each is an origin with no path. Absent: the server's default applies.

Default[]

Response body

About errors

Returns the configuration as stored, with sign_in_moved when the write moved the sign-in address.

application/json
  1. response

The instance configuration: its display name, enforcement levers and live settings, with the instance's ID.

instance_id*string

Unique identifier for the instance, the same value GET / returns.

version_recent_days?integer

Days within which every version is kept. Zero makes this window empty. Absent: the environment default applies.

Range0 <= value <= 36500
Default30
version_daily_snapshot_days?integer

Days within which a daily version is kept. Must be at least version_recent_days. Absent: the environment default applies.

Range0 <= value <= 36500
Default90
version_weekly_snapshot_days?integer

Days within which a weekly version is kept. Must be at least version_daily_snapshot_days. Absent: the environment default applies.

Range0 <= value <= 36500
Default365
version_max_versions?integer

Maximum versions per item, after applying the time windows. Per-type policy overrides these instance defaults.

Range1 <= value <= 1000000
Default500
grant_inactivity_days?integer

Disconnect apps unused for this many days. Zero disables retirement.

Range0 <= value <= 36500
Default365
enrichment_enabled?boolean

true if Marfa reads text and dimensions from files. An active extraction can finish after disabling. Absent: the environment default applies.

Defaulttrue
enrichment_ocr_enabled?boolean

true if file reading includes image text. Enabling reconsiders previously skipped images. Absent: the environment default applies.

Defaulttrue
error_reporting_enabled?boolean

true if exception reports are sent. Enabling requires both posthog_host and posthog_project_token. Absent: the environment default applies.

Defaulttrue
telemetry_enabled?boolean

true if Marfa sends telemetry about itself: traces, log records and metrics to the OTLP endpoints, and exception reports to posthog_host. false sends none of them and keeps every telemetry setting. Absent: true.

Defaulttrue
otel_sample_ratio?number

The share of traces Marfa exports, from 0 to 1. A trace that holds an error is exported whatever this says. Absent: 0.05.

Range0 <= value <= 1
Default0.05
otel_service_name?string

The service name on everything Marfa exports, in place of a service.name in otel_resource_attributes. Absent: marfa-server. An archive doesn't carry it.

Lengthlength <= 255
otel_resource_attributes?string

Attributes Marfa adds to everything it exports, as comma-separated key=value pairs with percent-encoded values. One named here replaces Marfa's own of the same name, such as service.version. An archive doesn't carry it.

Lengthlength <= 4096
heartbeat_enabled?boolean

true if scheduled heartbeat requests are sent. Enabling requires heartbeat_url. Absent: the environment default applies.

Defaulttrue
name?string

The instance's display name, without control or bidirectional formatting characters. Spaces at each end are trimmed. Absent: Marfa.

Length1 <= length <= 200
enforcement?

The instance's enforcement levers. Each applies to every credential that doesn't set the same lever itself. Absent: no lever is on.

audit_retention_days?integer

Days Marfa keeps audit log entries and outbound webhook delivery history. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default90
event_log_retention_days?integer

Days Marfa keeps events, which a stream can replay from a cursor, and the answers it replays for an Idempotency-Key. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
trash_retention_days?integer

Days an item stays in the trash before Marfa purges it. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default60
row_log_retention_days?integer

Days a table keeps a batch in its change log, so you can undo it. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
inbound_handled_retention_days?integer

Days Marfa keeps inbound webhook deliveries a connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default7
inbound_pending_retention_days?integer

Days Marfa keeps inbound webhook deliveries no connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.

Range0 <= value <= 36500
Default30
addresses?array<string>

The addresses people reach this instance at, each an origin with no path. The sign-in address is always one of them.

Default[]
sign_in_address?string

The address people sign in at, an origin with no path. Absent: this computer's own address.

backup_path?string

The absolute path of the folder Marfa backs itself up to and keeps a second copy of each file in, outside the data directory and the blob folder. Changing it needs a sign-in from the last fifteen minutes. Absent: no backup folder.

object_store_bucket?string

The bucket of an S3-compatible object store that also keeps each file and the backups: 1 to 255 ASCII letters, digits, ., :, - and _, other than . and ... Changing it needs a sign-in from the last fifteen minutes. Absent: no object store.

Lengthlength <= 255
object_store_region?string

The region of the object store: a name of 1 to 63 ASCII letters, digits, hyphens and underscores that can be part of a host name, such as us-east-1 or auto. Changing it needs a sign-in from the last fifteen minutes. Absent: us-east-1.

Lengthlength <= 63
Default"us-east-1"
object_store_endpoint?string

The endpoint of the object store, an http or https URL with no user name or password. Changing it needs a sign-in from the last fifteen minutes. Absent: the store's provider chooses it.

Formaturi
object_store_path_style?boolean

true if the store at object_store_endpoint is addressed by path. false puts the bucket, as lowercase host labels, before the endpoint's host, a name without the bucket. Changing it needs a sign-in from the last fifteen minutes. Absent: true.

Defaulttrue
object_store_prefix?string

The folder in the bucket Marfa keeps files and backups under, as /-joined segments. Changing it needs a sign-in from the last fifteen minutes. Absent: marfa.

Default"marfa"
object_store_access_key_id?string

The access key ID for the object store.

Lengthlength <= 256
allow_private_addresses?boolean

true if Marfa may send webhooks, the heartbeat, exception reports and object store requests to loopback, private and other addresses that aren't public. Changing it needs a sign-in from the last fifteen minutes. Absent: false.

Defaultfalse
secrets_set?array<string>

The key of each secret setting stored with a value Marfa can read, present only while one is. Marfa never returns a secret's value.

sign_in_moved?

What the move did and what the owner does next. Present only in the answer to the write that moved the sign-in address.

max_request_bytes?integer

The largest request body Marfa accepts, in bytes. Marfa waits 180 seconds for a body, so a body over about 21 MiB can't arrive in time over a 1 Mbit/s link.

Range1 <= value <= 1099511627776
Default1048576
max_bulk_request_bytes?integer

The largest body the bulk operations accept, in bytes, and the largest row a restore reads. The most you can set is 33554432, half the 67108864 bytes a restore reads on one archive line.

Range1 <= value <= 33554432
Default16777216
disk_reserve_bytes?integer

Free disk space an upload must leave on the blob volume, in bytes. 0 refuses no write for room, and health still reports the disk as degraded below 64 MiB.

Range0 <= value <= 1099511627776
Default134217728
blob_min_copies?integer

The fewest live copies Marfa keeps of each blob.

Range1 <= value <= 1000000
Default1
blob_cleanup_enabled?boolean

true if the blob-orphans job purges blobs nothing references once they have stood in the orphan report for blob_cleanup_grace_seconds.

Defaulttrue
blob_cleanup_grace_seconds?integer

How long a blob nothing references stands in the orphan report before a later run purges it, in seconds.

Range0 <= value <= 31536000
Default86400
backup_interval_seconds?integer

How often Marfa makes a backup when anything it holds has changed, in seconds. 0 turns scheduled backups off.

Range0 <= value <= 31536000
Default3600
rate_limit_enabled?boolean

true if the rate limiter is on for requests a key or app makes, app registrations, device code requests, passkey sign-in challenges and deliveries to inbound addresses.

Defaulttrue
rate_limit_requests?integer

How many requests one key or app may make in each rate-limit window, across every operation.

Range1 <= value <= 1000000
Default4000
rate_limit_keys_requests?integer

How many requests one key may make in each rate-limit window to the operations under /keys.

Range1 <= value <= 1000000
Default200
rate_limit_window_seconds?integer

How long one rate-limit window lasts, in seconds.

Range1 <= value <= 86400
Default60
unapproved_app_retention_hours?integer

Hours Marfa keeps an app that registered itself and holds no grant. 0 keeps it with no age limit.

Range0 <= value <= 876000
Default1
revoked_grant_retention_days?integer

Days Marfa keeps a revoked app grant. 0 keeps it with no age limit.

Range0 <= value <= 36500
Default90
enrichment_max_blob_bytes?integer

The largest file Marfa reads whole to extract its text, in bytes. Marfa skips a larger file unread, and reads a sound or video from its headers whatever its size.

Range1 <= value <= 1099511627776
Default20971520
enrichment_max_text_chars?integer

The most Unicode characters of extracted text Marfa keeps, counted as characters and not UTF-16 code units. Marfa cuts longer text short.

Range1 <= value <= 100000000
Default100000
enrichment_max_inflated_bytes?integer

The most a document may inflate to when Marfa extracts its text, all its parts together, in bytes. Marfa skips a document that inflates past it.

Range1 <= value <= 1099511627776
Default67108864
enrichment_max_memory_bytes?integer

The most memory the process that reads one file may take, in bytes. Marfa skips a file that needs more.

Range1 <= value <= 1099511627776
Default1073741824
enrichment_max_attempts?integer

How many times Marfa tries to read a file that fails, or that stops the server, before it stops trying.

Range1 <= value <= 100
Default3
update_check_enabled?boolean

true if Marfa checks GitHub for new releases every few hours. When false, it makes no request for them and reports no release as newer.

Defaulttrue
event_stream_max_viewers?integer

The most event-stream viewers one server serves at once. 0 sets no limit.

Range0 <= value <= 1000000
Default0
mcp_fetch_enabled?boolean

true if MCP tools fetch a file from a web address, or a file a chat attached, to save it. When false, a tool asked to fetch one is refused.

Defaulttrue
mcp_fetch_max_bytes?integer

The largest file an MCP tool fetches from a web address to save, in bytes. Marfa refuses a larger file and stores nothing.

Range1 <= value <= 1099511627776
Default52428800
mcp_fetch_timeout_seconds?integer

How long an MCP tool's fetch of a file from a web address may take, from connecting to the last byte, in seconds.

Range1 <= value <= 3600
Default60
inbound_max_bytes?integer

The largest inbound webhook delivery Marfa stores, in bytes.

Range1 <= value <= 1099511627776
Default26214400
rate_limit_inbound_requests?integer

How many requests one inbound endpoint's address takes in each rate-limit window, whatever each is answered.

Range1 <= value <= 1000000
Default600
inbound_in_flight_bytes?integer

The most bytes of inbound webhook deliveries Marfa holds in memory at once. One source holds at most half.

Range1 <= value <= 1099511627776
Default104857600
inbound_backlog_deliveries?integer

The unhandled deliveries one registration may hold before Marfa refuses more for it.

Range1 <= value <= 1000000
Default10000
inbound_backlog_bytes?integer

The bytes of unhandled deliveries one registration may hold before Marfa refuses more for it.

Range1 <= value <= 1099511627776
Default1073741824
inbound_retained_deliveries?integer

The most deliveries one registration retains across its live and retired endpoints.

Range1 <= value <= 1000000
Default10000
inbound_retained_bytes?integer

The most bytes of bodies, headers and queries one registration retains across its live and retired endpoints.

Range1 <= value <= 1099511627776
Default1073741824
cors_origins?array<string>

The browser origins allowed to call the API across origins with a token, beside the web pages the owner approves. Each is an origin with no path.

Default[]
  • missing_required_field: a lever lacks types or sources.
  • validation_error: the body names a setting Marfa doesn't know, a value is out of range, the effective version windows are out of order, reporting is turned from off to on without a configured receiver, the name is invalid, or instance_id names a different instance.
application/json
  1. response

An error response.

error*

What went wrong.

  • unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.
  • insufficient_user_authentication: your app's owner signed in more than fifteen minutes ago. Send them through GET /oauth/authorize with max_age.
application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: you don't hold config.manage, which details.required_scope names, or the body sets skip_sign_in_address_check, which only the private local command can send.
  • app_sign_in_required: the change needs a recent sign-in, and you are an API key. A person makes it from an app they signed in to, or with the private local command.
application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

  • conflict: the settings changed during the address check. Send it again.
  • instance_changed: X-Marfa-Instance-Id names another instance.
  • sign_in_address_change_unconfirmed: the body lacks confirm_sign_in_address_change: true. details.consequences lists the effects.
  • sign_in_address_check_failed: the new sign-in address did not answer as this instance. details.reason says why.
application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X PUT 'http://localhost:8600/config' \  -H 'Content-Type: application/json' \  -d '{}'
About errors
{  "instance_id": "01a10127-86fe-728c-8cf8-38e902e15d4f",  "name": "Example instance"}