Get the configuration
Returns the instance configuration: its display name, enforcement levers and live settings, with its instance_id. A setting nobody has set is left out. Requires config.manage.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
Returns the configuration.
application/json- response
The instance configuration: its display name, enforcement levers and live settings, with the instance's ID.
instance_id*stringUnique identifier for the instance, the same value GET / returns.
version_recent_days?integerDays within which every version is kept. Zero makes this window empty. Absent: the environment default applies.
0 <= value <= 3650030version_daily_snapshot_days?integerDays within which a daily version is kept. Must be at least version_recent_days. Absent: the environment default applies.
0 <= value <= 3650090version_weekly_snapshot_days?integerDays within which a weekly version is kept. Must be at least version_daily_snapshot_days. Absent: the environment default applies.
0 <= value <= 36500365version_max_versions?integerMaximum versions per item, after applying the time windows. Per-type policy overrides these instance defaults.
1 <= value <= 1000000500grant_inactivity_days?integerDisconnect apps unused for this many days. Zero disables retirement.
0 <= value <= 36500365enrichment_enabled?booleantrue if Marfa reads text and dimensions from files. An active extraction can finish after disabling. Absent: the environment default applies.
trueenrichment_ocr_enabled?booleantrue if file reading includes image text. Enabling reconsiders previously skipped images. Absent: the environment default applies.
trueerror_reporting_enabled?booleantrue if exception reports are sent. Enabling requires both posthog_host and posthog_project_token. Absent: the environment default applies.
truetelemetry_enabled?booleantrue 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.
trueotel_sample_ratio?numberThe share of traces Marfa exports, from 0 to 1. A trace that holds an error is exported whatever this says. Absent: 0.05.
0 <= value <= 10.05otel_service_name?stringThe 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.
length <= 255otel_resource_attributes?stringAttributes 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.
length <= 4096heartbeat_enabled?booleantrue if scheduled heartbeat requests are sent. Enabling requires heartbeat_url. Absent: the environment default applies.
truename?stringThe instance's display name, without control or bidirectional formatting characters. Spaces at each end are trimmed. Absent: Marfa.
1 <= length <= 200enforcement?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?integerDays Marfa keeps audit log entries and outbound webhook delivery history. 0 keeps them with no age limit. Absent: the server's default applies.
0 <= value <= 3650090event_log_retention_days?integerDays 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.
0 <= value <= 3650030trash_retention_days?integerDays an item stays in the trash before Marfa purges it. 0 keeps them with no age limit. Absent: the server's default applies.
0 <= value <= 3650060row_log_retention_days?integerDays 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.
0 <= value <= 3650030inbound_handled_retention_days?integerDays Marfa keeps inbound webhook deliveries a connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.
0 <= value <= 365007inbound_pending_retention_days?integerDays Marfa keeps inbound webhook deliveries no connector has marked handled. 0 keeps them with no age limit. Absent: the server's default applies.
0 <= value <= 3650030addresses?array<string>The addresses people reach this instance at, each an origin with no path. The sign-in address is always one of them.
[]sign_in_address?stringThe address people sign in at, an origin with no path. Absent: this computer's own address.
backup_path?stringThe 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?stringThe 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.
length <= 255object_store_region?stringThe 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.
length <= 63"us-east-1"object_store_endpoint?stringThe 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.
uriobject_store_path_style?booleantrue 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.
trueobject_store_prefix?stringThe 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.
"marfa"object_store_access_key_id?stringThe access key ID for the object store.
length <= 256allow_private_addresses?booleantrue 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.
falsesecrets_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?integerThe 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.
1 <= value <= 10995116277761048576max_bulk_request_bytes?integerThe 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.
1 <= value <= 3355443216777216disk_reserve_bytes?integerFree 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.
0 <= value <= 1099511627776134217728blob_min_copies?integerThe fewest live copies Marfa keeps of each blob.
1 <= value <= 10000001blob_cleanup_enabled?booleantrue if the blob-orphans job purges blobs nothing references once they have stood in the orphan report for blob_cleanup_grace_seconds.
trueblob_cleanup_grace_seconds?integerHow long a blob nothing references stands in the orphan report before a later run purges it, in seconds.
0 <= value <= 3153600086400backup_interval_seconds?integerHow often Marfa makes a backup when anything it holds has changed, in seconds. 0 turns scheduled backups off.
0 <= value <= 315360003600rate_limit_enabled?booleantrue 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.
truerate_limit_requests?integerHow many requests one key or app may make in each rate-limit window, across every operation.
1 <= value <= 10000004000rate_limit_keys_requests?integerHow many requests one key may make in each rate-limit window to the operations under /keys.
1 <= value <= 1000000200rate_limit_window_seconds?integerHow long one rate-limit window lasts, in seconds.
1 <= value <= 8640060unapproved_app_retention_hours?integerHours Marfa keeps an app that registered itself and holds no grant. 0 keeps it with no age limit.
0 <= value <= 8760001revoked_grant_retention_days?integerDays Marfa keeps a revoked app grant. 0 keeps it with no age limit.
0 <= value <= 3650090enrichment_max_blob_bytes?integerThe 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.
1 <= value <= 109951162777620971520enrichment_max_text_chars?integerThe most Unicode characters of extracted text Marfa keeps, counted as characters and not UTF-16 code units. Marfa cuts longer text short.
1 <= value <= 100000000100000enrichment_max_inflated_bytes?integerThe 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.
1 <= value <= 109951162777667108864enrichment_max_memory_bytes?integerThe most memory the process that reads one file may take, in bytes. Marfa skips a file that needs more.
1 <= value <= 10995116277761073741824enrichment_max_attempts?integerHow many times Marfa tries to read a file that fails, or that stops the server, before it stops trying.
1 <= value <= 1003update_check_enabled?booleantrue if Marfa checks GitHub for new releases every few hours. When false, it makes no request for them and reports no release as newer.
trueevent_stream_max_viewers?integerThe most event-stream viewers one server serves at once. 0 sets no limit.
0 <= value <= 10000000mcp_fetch_enabled?booleantrue 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.
truemcp_fetch_max_bytes?integerThe largest file an MCP tool fetches from a web address to save, in bytes. Marfa refuses a larger file and stores nothing.
1 <= value <= 109951162777652428800mcp_fetch_timeout_seconds?integerHow long an MCP tool's fetch of a file from a web address may take, from connecting to the last byte, in seconds.
1 <= value <= 360060inbound_max_bytes?integerThe largest inbound webhook delivery Marfa stores, in bytes.
1 <= value <= 109951162777626214400rate_limit_inbound_requests?integerHow many requests one inbound endpoint's address takes in each rate-limit window, whatever each is answered.
1 <= value <= 1000000600inbound_in_flight_bytes?integerThe most bytes of inbound webhook deliveries Marfa holds in memory at once. One source holds at most half.
1 <= value <= 1099511627776104857600inbound_backlog_deliveries?integerThe unhandled deliveries one registration may hold before Marfa refuses more for it.
1 <= value <= 100000010000inbound_backlog_bytes?integerThe bytes of unhandled deliveries one registration may hold before Marfa refuses more for it.
1 <= value <= 10995116277761073741824inbound_retained_deliveries?integerThe most deliveries one registration retains across its live and retired endpoints.
1 <= value <= 100000010000inbound_retained_bytes?integerThe most bytes of bodies, headers and queries one registration retains across its live and retired endpoints.
1 <= value <= 10995116277761073741824cors_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.
[]validation_error: the query has a parameter this endpoint doesn't take.
application/json- 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.
application/json- response
An error response.
error*What went wrong.
forbidden: you don't holdconfig.manage.details.required_scopenames it.
application/json- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X GET 'http://localhost:8600/config'{ "instance_id": "01a10127-86fe-728c-8cf8-38e902e15d4f"}