Types

Move items to another type

Moves every item of the type you can see, in any state, to another type as a bulk-action job. Once none remains, it rewrites the folders, views and webhooks that name the type. dry_run: true returns what it would do.

POST
/types/{id}/move

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path parameters

id*string

The identifier of the type to move items out of, such as acme.deal.

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

The identifier of the type to move items to, such as acme.contract. It must be registered.

properties?

Properties to merge into every item as it moves, such as a field the new type requires. A null value removes a property.

dry_run?boolean

true returns the items and settings the move would change and writes nothing. Defaults to false.

Response body

About errors

With dry_run: true, returns what the move would do.

application/json
  1. response

What a type move would do, written nowhere.

dry_run*true

Always true.

Value intrue
from*string

The type the items are in now.

to*string

The type the items would move to.

matched*integer

How many items of from the move would take, in any state. Items your source filter hides aren't counted or moved.

ids*array<string>

The IDs of those items.

settings*array<>

Every folder, view and webhook setting that names from, which the move rewrites to name to once no item of from remains.

grants*array<>

The keys and apps whose type map names from, which the move doesn't change. Keys are listed if you have keys.manage, and apps if you have grants.manage.

Returns the queued job. Poll it with GET /items/bulk-actions/jobs/{id}. Its result lists the first 100 items it couldn't move in errors, counts the items of the type still left in remaining and remaining_hidden, and says in settings_rewritten whether it rewrote settings. Run the move again to move what remains.

application/json
  1. response

A bulk action Marfa runs in the background, with its progress.

id*string

Unique identifier for the job.

action*string

The action, such as purge.

status*string

Where the job is.

Value in"queued""in_progress""completed""failed""canceled"
matched*integer

How many items the job acts on, fixed when Marfa queued it.

processed*integer

How many of the matched items the job has reached so far, changed or not.

succeeded*integer

How many items the job has changed so far.

errored*integer

How many items the job has left unchanged so far.

started_at?string

When the job started running, in UTC. Absent until then.

finished_at?string

When the job completed, failed or was canceled, in UTC. Absent until then.

error?string

Why the job failed, for a person to read. Present only when status is failed.

result?

What the job did. Present once status is completed or failed.

  • missing_required_field: to is missing.
  • validation_error: to is malformed or names the type itself.
  • unknown_type: no type has the identifier to.
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.

  • core_type_immutable: Marfa ships the type, and its items stay in it.
  • type_not_permitted: your type map doesn't grant write on both types.
application/json
  1. response

An error response.

error*

What went wrong.

type_not_found: no type has this identifier.

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.

  • type_move_blocked: a folder, view or webhook names the type in a way the move can't rewrite. details.settings lists each, with its reason. Change them, then move.
  • type_move_blocked: an item holds rows in a table the target type doesn't declare. details.tables lists them.
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/types/string/move' \  -H 'Content-Type: application/json' \  -d '{  "to": "string"}'
About errors
{  "dry_run": true,  "from": "acme.lead",  "to": "acme.contact",  "matched": 1,  "ids": [    "01a1011a-4902-76cf-a4a9-88e99c038c8d"  ],  "settings": [    {      "kind": "view",      "id": "01a10126-6c86-74b2-a04a-1fe68e721fde",      "field": "query.types"    }  ],  "grants": [    {      "kind": "key",      "id": "01a1011b-b5e5-7be6-8f3b-77492475b5a4",      "label": "CRM sync"    }  ]}