Register a connector
Registers your key as a connector and returns it. Repeating registration replaces its name, description and read_only_types and keeps its ID. A successor key inherits its own source's inbound endpoints and retained deliveries.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
X-Marfa-Instance-Id?stringThe 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.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- body
name*stringThe connector's name.
1 <= length <= 200description?stringWhat the connector does. Leave it out for none: registering again without it clears the old one.
length <= 2000read_only_types?array<string>The types whose items the connector holds read only, putting back any edit made in Marfa. An item reads read_only as true when every connector for its source whose live key may write its type lists the type. The types needn't be registered. Leaving it out clears the list.
items <= 1000Returns the existing connector with its name, description and read_only_types replaced. Its id and registered_at don't change.
application/json- response
A connector is a program outside Marfa that registers under an API key of its own, sends heartbeats and reports its runs.
id*stringUnique identifier for the connector.
key_id*stringThe ID of the API key the connector registered under.
source*stringThe source of that key. The connector's state document and agreements belong to this source.
name*stringThe connector's name.
description*|What the connector does; null if none was given.
registered_at*stringWhen the connector first registered.
updated_at*stringWhen the connector's name, description or read_only_types was last set.
last_heartbeat_at*|When the connector last sent a heartbeat; null if never.
read_only_types*array<string>The types whose items the connector holds read only, putting back any edit made in Marfa. [] if it declared none.
last_run*|The connector's most recently reported run; null if it has reported none.
problems*The source's current problems, by opaque key; {} if there are none.
hold_expires_at*|When the hold on the connector lapses; null if no process holds it or its hold has lapsed.
Returns the new connector.
application/json- response
A connector is a program outside Marfa that registers under an API key of its own, sends heartbeats and reports its runs.
id*stringUnique identifier for the connector.
key_id*stringThe ID of the API key the connector registered under.
source*stringThe source of that key. The connector's state document and agreements belong to this source.
name*stringThe connector's name.
description*|What the connector does; null if none was given.
registered_at*stringWhen the connector first registered.
updated_at*stringWhen the connector's name, description or read_only_types was last set.
last_heartbeat_at*|When the connector last sent a heartbeat; null if never.
read_only_types*array<string>The types whose items the connector holds read only, putting back any edit made in Marfa. [] if it declared none.
last_run*|The connector's most recently reported run; null if it has reported none.
problems*The source's current problems, by opaque key; {} if there are none.
hold_expires_at*|When the hold on the connector lapses; null if no process holds it or its hold has lapsed.
missing_required_field:nameis missing.validation_error:nameisn't 1 to 200 characters,descriptionis over 2,000 characters,read_only_typesholds a malformed type identifier or over 1,000 entries, or the body has a top-level field 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: your credential is an app's access token, not a key, or local authority.
application/json- 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- response
An error response.
error*What went wrong.
instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.
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.
request_too_large: the request body is larger than this instance accepts.
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 POST 'http://localhost:8600/connectors' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "id": "01a10123-4825-7ff1-8fde-fb30a676e02b", "key_id": "01a1011b-b5e5-7be6-8f3b-77492475b5a4", "source": "crm", "name": "crm", "description": null, "registered_at": "2026-10-03T10:01:55.251Z", "updated_at": "2026-10-03T10:02:55.417Z", "last_heartbeat_at": null, "read_only_types": [ "acme.deal" ], "last_run": null, "hold_expires_at": null, "problems": {}}