Instance

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.

GET
/config

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Response body

About errors

Returns the configuration.

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[]
  • validation_error: the query has a parameter this endpoint doesn't take.
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.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: you don't hold config.manage. details.required_scope names it.
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.

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 GET 'http://localhost:8600/config'
About errors
{  "instance_id": "01a10127-86fe-728c-8cf8-38e902e15d4f"}