Register an edge type
Registers an edge type and returns it. With evolve_constraints: true, widens a registered type's endpoint constraints and may rename its labels, without changing its edges. An edge type can't extend another.
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
An edge type to register.
id*stringThe identifier of the edge type, such as acme.list-member.
1 <= lengthlabel?stringThe name an app shows on the from end, such as Children on a parent. Leave it out and the last segment of the id makes it, such as List Member. On a change, leaving it out keeps the stored one.
reverse_label?stringThe name an app shows on the to end, such as Parent on a child. Leave it out and label names both ends. On a change, leaving it out keeps the stored one; send the label to make a type two-way.
1 <= lengthdescription?stringWhat the edge type is for.
cardinality*stringHow many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.
"one-to-one""one-to-many""many-to-one""many-to-many"from_type_constraints?array<>The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes. Leave it out to allow any type.
to_type_constraints?array<>The types the item an edge points to can have, in the same form as from_type_constraints. Leave it out to allow any type.
cascade_on_delete?stringWhat deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any. Leave it out for orphan.
"cascade""orphan""block""with-hosts"property_schema?The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list. Leave it out for none.
reverse_name?stringThe name the edge goes by when read from its to end, such as child-of for parent-of. No other edge type can use it as an ID or reverse name.
written_from?stringThe end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it. to needs a reverse_name. Leave it out for from.
"from""to""none"evolve_constraints?booleantrue updates a registered type in place: widen its endpoints (keep every constraint token, or allow all types with [] or *) and change its labels. Other members stay unchanged. Omit or false to register a new type. Not stored.
Returns the widened edge type, or its unchanged definition for a repeated request.
application/json- response
An edge type says how edges of that type behave: its cardinality, what a delete does to the items they join, and which item types they can join.
id*stringUnique identifier for the edge type.
label*stringThe name an app shows on the from end of an edge of this type, such as Children on a parent. Not the reverse_name, which is the code name a file writes.
reverse_label*stringThe name an app shows on the to end, such as Parent on a child. It is the same text as label when the relation is two-way, and an app then shows both directions as one list.
description?stringWhat the edge type is for.
cardinality*stringHow many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.
"one-to-one""one-to-many""many-to-one""many-to-many"from_type_constraints*array<string>The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes.
to_type_constraints*array<string>The types the item an edge points to can have, in the same form as from_type_constraints.
cascade_on_delete*stringWhat deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any.
"cascade""orphan""block""with-hosts"property_schema*The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list.
reverse_name?stringThe name the edge goes by when read from its to end, such as child-of for parent-of.
written_from*stringThe end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it.
"from""to""none"shipped*booleantrue if Marfa ships the edge type: it exists on every instance, and you can't register or delete it. false for one registered through POST /edge-types.
acyclic*booleantrue if the server refuses an edge of this type that closes a cycle through other edges of the type. Every edge type refuses an edge from an item to itself.
flat*booleantrue if the server refuses an edge of this type from an item whose type its to_type_constraints admit, so an item that an edge of the type can point to never points from one.
Returns the new edge type.
application/json- response
An edge type says how edges of that type behave: its cardinality, what a delete does to the items they join, and which item types they can join.
id*stringUnique identifier for the edge type.
label*stringThe name an app shows on the from end of an edge of this type, such as Children on a parent. Not the reverse_name, which is the code name a file writes.
reverse_label*stringThe name an app shows on the to end, such as Parent on a child. It is the same text as label when the relation is two-way, and an app then shows both directions as one list.
description?stringWhat the edge type is for.
cardinality*stringHow many edges of the type an item can hold. one-to-one: each item at either end holds one. one-to-many: each item at the to end holds one. many-to-one: each item at the from end holds one. many-to-many: no limit.
"one-to-one""one-to-many""many-to-one""many-to-many"from_type_constraints*array<string>The types the item an edge points from can have: *, a type identifier or role:<name>. A type matches its subtypes.
to_type_constraints*array<string>The types the item an edge points to can have, in the same form as from_type_constraints.
cascade_on_delete*stringWhat deleting an edge's end does. cascade: deleting the from item trashes the to item. orphan: the other stays. block: the delete fails. with-hosts: the from item is trashed with its last to item, restored with any.
"cascade""orphan""block""with-hosts"property_schema*The properties an edge of the type can carry, by name. Marfa checks an edge's properties against it each time the edge is written, and accepts a property it doesn't list.
reverse_name?stringThe name the edge goes by when read from its to end, such as child-of for parent-of.
written_from*stringThe end of an edge whose file writes it in a folder: from, or to under the reverse name. none means no file writes it, so a folder never renders it.
"from""to""none"shipped*booleantrue if Marfa ships the edge type: it exists on every instance, and you can't register or delete it. false for one registered through POST /edge-types.
acyclic*booleantrue if the server refuses an edge of this type that closes a cycle through other edges of the type. Every edge type refuses an edge from an item to itself.
flat*booleantrue if the server refuses an edge of this type from an item whose type its to_type_constraints admit, so an item that an edge of the type can point to never points from one.
validation_error: a field is invalid, such as a badidorreverse_name, arole:naming no role, orwritten_from: towith noreverse_name, orextendsis set.missing_required_field:idorcardinalityis missing.invalid_schema: a property'stypeisn't a field type, or the body has a key the schema doesn't define (details.errorsnames each path).
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 havemetadata.edge_types:write.edge_type_not_permitted: your edge map doesn't grant write onidorreverse_name.details.edge_typenames it.type_not_permitted: the edge type cascades on delete and holds edges that point to items of a type you can't write.details.grantnames the missing grant.
application/json- response
An error response.
error*What went wrong.
edge_type_not_found: constraint evolution names no registered edge type.
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.
conflict: id is the name of an edge type Marfa ships, id or reverse_name is already the ID or reverse name of an edge type, or reverse_name equals id, or constraint evolution would remove a constraint token without allowing every type or change a definition member other than the labels.
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/edge-types' \ -H 'Content-Type: application/json' \ -d '{ "id": "string", "cardinality": "one-to-one"}'{ "id": "acme.deal-contact", "label": "Contact", "reverse_label": "Deals", "cardinality": "many-to-many", "from_type_constraints": [ "acme.deal" ], "to_type_constraints": [ "acme.contact" ], "cascade_on_delete": "orphan", "property_schema": {}, "written_from": "from", "shipped": false, "acyclic": false, "flat": false}