API v1
v1
View as Markdown

Create a record

POST /api/v1/vaults/{vault}/entity-types/{entityType}/entities

Write down a record of one kind in one vault, with what its template asks.

The record is written on the published version of the template the vault uses for this kind, or on the one you name in structure_version_id. Everything is written together or nothing is: a value refused in any section leaves no record behind.

A field you leave out starts with the default its template gives it, as it would on a new contact. Send it empty to leave it empty.

A type the vault does not show answers 404. A type the vault still shows because it holds records of it answers 422 with the reason on name when the type was turned off, when the vault has no published template for it and you name none, or when that template requires something that cannot be filled in here.

A relation field takes the id of the record it names: a contact, or a record of the kind the field points at. It has to be in the same vault, and anything else answers 422 on that field.

Parameters

Sent as JSON. Anything not listed here is ignored.

vault string Required

The vault the records live in, named either by the readable name it reports as slug or by its id. Both answer.

entityType uuid Required

The kind of record. A type the vault does not use, which is one with no published template set for it there and no record in it, answers 404.

name string Required

What the record is called, up to 255 characters.

structure_version_id integer Optional

The published version of one of your active templates for this kind, which says what the record holds. Left out, the record starts from the template the vault uses for this kind. A version of another kind, of a template turned off or belonging to somebody else answers 422 on this field, and so does a version that is no longer the one its template publishes.

fields object Optional

The values, keyed by the id of the field they fill in, each checked against what its field accepts. A field left out writes nothing. Files are sent as multipart under fields[id].

labels object Optional

The label picked beside a value, keyed by field id, for a field that carries one.

label_wordings object Optional

The wording typed when the picked label is the open one, keyed by field id.

year_is_unknown object Optional

True for a recurring date whose year nobody knows, keyed by field id.

month_is_unknown object Optional

True for a recurring date whose month nobody knows, keyed by field id.

Returns

The entity object that was written down. A vault or a type belonging to somebody else answers 404.

data object

The record.

data.type string

Always entity. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.

data.id string

The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.

data.attributes object

Everything the record holds.

data.attributes.name string

What the record is called, up to 255 characters. It is how the record is listed and sorted, and it is reduced to plain text when it is written down.

data.attributes.entity_type_id uuid

The kind of record it is. It never changes.

data.attributes.initials string

The first letter of the first two words of the name, drawn on the generated avatar.

data.attributes.avatar_colour string

The background the generated avatar is drawn on. It is picked when the record is written down and kept afterwards.

data.attributes.avatar object

The picture standing in for the record, with its id and url, or null when it is drawn as its initials.

data.attributes.is_archived boolean

Whether the record was put away. An archived record is still listed.

data.attributes.structure_version_id integer

The exact version of the template the record was written on. A record stays on that version until somebody moves it.

data.attributes.template_name string

The name of the template that version belongs to.

data.attributes.fields array

The values the record holds, in no particular order. A field left empty is not listed.

data.attributes.fields[] object

One value.

data.attributes.fields[].field_id string

The id of the field, which is the key a value is written under when the record is updated.

data.attributes.fields[].key string

How the field is named in an import or an export. It is unique inside its section only.

data.attributes.fields[].label string

What the field is called on the record.

data.attributes.fields[].type string

The kind of field: text, date, select, address and so on.

data.attributes.fields[].row integer

For a field inside a repeating group, the id of the repetition it belongs to, which is the id an update keeps that repetition by. Null otherwise.

data.attributes.fields[].value string

The value, written as the page of the record shows it. A file field gives the name of the file. Null when hidden.

data.attributes.fields[].is_hidden boolean

Whether the value was held back because the field is sensitive and the key does not hold the sensitive-fields scope.

data.attributes.created_at timestamp

When the record was written down, as a count of seconds since 1970.

data.attributes.updated_at timestamp

When it last changed, as a count of seconds, or null.

data.links object

Where to find this record.

data.links.self string

The absolute address this record is read from.

data.links.web string

The page of the record in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

POST
curl https://my.monicahq.com/api/v1/vaults/schrute-farms/entity-types/4c2b9f10-5e37-4a6d-8b91-0f7c3d2a8e64/entities \
-X POST \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Mose\u2019s goat",
"structure_version_id": 12,
"fields": {
"381": "Goat"
}
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/schrute-farms/entity-types/4c2b9f10-5e37-4a6d-8b91-0f7c3d2a8e64/entities', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Mose’s goat',
structure_version_id: 12,
fields: {"381":"Goat"},
}),
})
const data = await response.json()
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/schrute-farms/entity-types/4c2b9f10-5e37-4a6d-8b91-0f7c3d2a8e64/entities', [
'name' => 'Mose’s goat',
'structure_version_id' => 12,
'fields' => ['381' => 'Goat'],
]);
Response 201
{
"data": {
"type": "entity",
"id": "9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031",
"attributes": {
"name": "Mose’s goat",
"entity_type_id": "4c2b9f10-5e37-4a6d-8b91-0f7c3d2a8e64",
"initials": "MG",
"avatar_colour": "#22c55e",
"avatar": null,
"is_archived": false,
"structure_version_id": 12,
"template_name": "Basic animal",
"fields": [
{
"field_id": "381",
"key": "species",
"label": "Species",
"type": "text",
"row": null,
"value": "Goat",
"is_hidden": false
}
],
"created_at": 1758844800,
"updated_at": 1758844800
},
"links": {
"self": "https://my.monicahq.com/api/v1/vaults/schrute-farms/entities/9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031",
"web": "https://my.monicahq.com/vaults/schrute-farms/entities/animals/9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031"
}
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.