Connectors

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.

POST
/connectors

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
name*string

The connector's name.

Length1 <= length <= 200
description?string

What the connector does. Leave it out for none: registering again without it clears the old one.

Lengthlength <= 2000
read_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.

Itemsitems <= 1000

Response body

About errors

Returns the existing connector with its name, description and read_only_types replaced. Its id and registered_at don't change.

application/json
  1. response

A connector is a program outside Marfa that registers under an API key of its own, sends heartbeats and reports its runs.

id*string

Unique identifier for the connector.

key_id*string

The ID of the API key the connector registered under.

source*string

The source of that key. The connector's state document and agreements belong to this source.

name*string

The connector's name.

description*|

What the connector does; null if none was given.

registered_at*string

When the connector first registered.

updated_at*string

When 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
  1. response

A connector is a program outside Marfa that registers under an API key of its own, sends heartbeats and reports its runs.

id*string

Unique identifier for the connector.

key_id*string

The ID of the API key the connector registered under.

source*string

The source of that key. The connector's state document and agreements belong to this source.

name*string

The connector's name.

description*|

What the connector does; null if none was given.

registered_at*string

When the connector first registered.

updated_at*string

When 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: name is missing.
  • validation_error: name isn't 1 to 200 characters, description is over 2,000 characters, read_only_types holds a malformed type identifier or over 1,000 entries, or the body has a top-level field 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: your credential is an app's access token, not a key, or local authority.
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.

instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.

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 POST 'http://localhost:8600/connectors' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
About errors
{  "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": {}}