Entries

Base path: /api/v1/entries. Entries are notes (markdown content). Read (GET list and get one) needs entries: read. Write (POST, PATCH, DELETE, POST …/restore) needs entries: read_write.

List entries

GET/api/v1/entries

Query parameters

Parameter	Type	Notes
`limit`	integer	Optional, 1–100, default 50
`memberId`	UUID	Optional; filter to entries linked to that member

Behavior

Returns active (non-trashed) entries for the account, newest updatedAt first, then by id. Each row includes resolved linked members.

Response

200

JSON array of list rows. Timestamps are Unix milliseconds.

JSON

[
  {
    "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "title": "Daily note",
    "content": "# Markdown\nBody text.",
    "createdAt": 1714233600000,
    "updatedAt": 1714237200000,
    "member": {
      "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "name": "string",
      "displayName": "string",
      "archived": false,
      "avatarUrl": null
    },
    "members": [
      {
        "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "name": "string",
        "displayName": "string",
        "archived": false,
        "avatarUrl": null
      }
    ]
  }
]

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries?limit=50"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/entries");
url.searchParams.set("limit", "50");
url.searchParams.set("memberId", "MEMBER_UUID"); // optional
const res = await fetch(url.toString(), {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const entries = await res.json();

Status codes

200: JSON array
400: invalid query parameters
401 / 403: JSON error (see Errors)

Create entry

POST/api/v1/entries

Request body (JSON)

Strict object: content (string, required), optional title, memberId (UUID), memberIds (UUID array). External markdown images may be re-hosted when storage is configured (same behavior as the app).

Response

201

Returns the new entry id.

JSON

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

403

Per-member note cap (body is not the generic scope error; see code).

JSON

{
  "code": "NOTE_LIMIT_REACHED",
  "message": "Note limit reached for MemberName (N per member on your plan). Upgrade to add more."
}

400 / 503

Validation / storage errors use BAD_REQUEST or PRECONDITION_FAILED with message: same envelope as Errors.

Examples

cURL

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello","title":"Note"}' \
  "https://api.floralitys.com/api/v1/entries"

JavaScript (fetch)

JavaScript

const res = await fetch("https://api.floralitys.com/api/v1/entries", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Hello", title: "Note" }),
});
if (!res.ok) throw new Error(await res.text());
const { id } = await res.json();

Status codes

201: created id
400: validation / bad body
403: note limit reached (NOTE_LIMIT_REACHED)
503: storage not configured when re-hosting images fails (PRECONDITION_FAILED)
401 / 403: auth / scope

Get entry by id

GET/api/v1/entries/{entryId}

Behavior

Returns one active entry. Trashed or unknown ids return 404 (same as dashboard entries.get).

List / detail row fields

Field	Type	Notes
`_id`	string	Entry id (UUID)
`title`	string \| null	Optional
`content`	string	Markdown body
`createdAt` / `updatedAt`	number	Unix ms
`member`	object \| null	First linked member summary
`members`	array	All linked members (summary)
`memberId` / `memberIds`	string \| null / string[] \| null	Present on GET one only (detail)

Response

200

Single detail row (includes memberId and memberIds).

JSON

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "title": "Daily note",
  "content": "# Markdown\nBody text.",
  "createdAt": 1714233600000,
  "updatedAt": 1714237200000,
  "member": {
    "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
    "name": "string",
    "displayName": "string",
    "archived": false,
    "avatarUrl": null
  },
  "members": [],
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"]
}

404

Unknown id, wrong account, or entry is trashed.

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
if (!res.ok) throw new Error(await res.text());
const entry = await res.json();

Status codes

200: JSON object
400: invalid id
404: not found or trashed
401 / 403: auth / scope

Update entry

PATCH/api/v1/entries/{entryId}

Request body (JSON)

Strict object; at least one of title, content, memberId (UUID or null to clear legacy single link), memberIds (UUID array) must be present. Cannot update a trashed entry; restore first.

Response

200

Full detail object after update (same shape as GET one).

JSON

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "title": "Daily note",
  "content": "# Markdown\nBody text.",
  "createdAt": 1714233600000,
  "updatedAt": 1714237200000,
  "member": {
    "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
    "name": "string",
    "displayName": "string",
    "archived": false,
    "avatarUrl": null
  },
  "members": [],
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"]
}

400 / 404 / 503

Error object { "code", "message" }; 404 when the entry is missing after update is unlikely but uses NOT_FOUND.

Examples

cURL

Shell

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated"}' \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title: "Updated" }),
  },
);
if (!res.ok) throw new Error(await res.text());
const entry = await res.json();

Status codes

200: JSON detail
400: validation, no fields, trash state, limits
404: missing entry after update (unexpected)
503: storage when re-hosting images
401 / 403: auth / scope

Delete entry

DELETE/api/v1/entries/{entryId}

Query parameters

permanent=true permanent=true (or 1 / yes): if the entry is active, moves to trash then purges immediately; if already trashed, purges only. Omit for soft delete (move to trash only).

Response

204

Success responses have no JSON body.

Plain text

// 204 No Content: empty response body

400 / 404

Typical error bodies when the delete cannot proceed.

JSON

{
  "code": "BAD_REQUEST",
  "message": "Entry is already in trash"
}

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL (soft)

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

cURL (permanent)

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID?permanent=true"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/entries/ENTRY_ID");
url.searchParams.set("permanent", "true"); // omit or false for soft delete (trash)
const res = await fetch(url.toString(), {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (res.status !== 204) throw new Error(await res.text());

Status codes

204: success
400: invalid id, already trashed on soft delete, not in trash for purge-only errors
404: unknown id or wrong account
401 / 403: auth / scope

Restore entry from trash

POST/api/v1/entries/{entryId}/restore

Response

204

Empty body on success.

Plain text

// 204 No Content: empty response body

400 / 404

Example 400 when the entry is not in trash. 404 uses the same envelope as other routes.

JSON

{
  "code": "BAD_REQUEST",
  "message": "Entry is not in trash"
}

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID/restore"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID/restore",
  { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
if (res.status !== 204) throw new Error(await res.text());

Status codes

204: restored
400: not in trash, restore would exceed limits, etc.
404: not found (wrong id / tenant)
401 / 403: auth / scope

Entries

List entries

GET/api/v1/entries

Query parameters

Parameter	Type	Notes
`limit`	integer	Optional, 1–100, default 50
`memberId`	UUID	Optional; filter to entries linked to that member

Behavior

Returns active (non-trashed) entries for the account, newest updatedAt first, then by id. Each row includes resolved linked members.

Response

200

JSON array of list rows. Timestamps are Unix milliseconds.

JSON

[
  {
    "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "title": "Daily note",
    "content": "# Markdown\nBody text.",
    "createdAt": 1714233600000,
    "updatedAt": 1714237200000,
    "member": {
      "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "name": "string",
      "displayName": "string",
      "archived": false,
      "avatarUrl": null
    },
    "members": [
      {
        "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "name": "string",
        "displayName": "string",
        "archived": false,
        "avatarUrl": null
      }
    ]
  }
]

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries?limit=50"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/entries");
url.searchParams.set("limit", "50");
url.searchParams.set("memberId", "MEMBER_UUID"); // optional
const res = await fetch(url.toString(), {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const entries = await res.json();

Status codes

200: JSON array
400: invalid query parameters
401 / 403: JSON error (see Errors)

Create entry

POST/api/v1/entries

Request body (JSON)

Strict object: content (string, required), optional title, memberId (UUID), memberIds (UUID array). External markdown images may be re-hosted when storage is configured (same behavior as the app).

Response

201

Returns the new entry id.

JSON

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

403

Per-member note cap (body is not the generic scope error; see code).

JSON

{
  "code": "NOTE_LIMIT_REACHED",
  "message": "Note limit reached for MemberName (N per member on your plan). Upgrade to add more."
}

400 / 503

Validation / storage errors use BAD_REQUEST or PRECONDITION_FAILED with message: same envelope as Errors.

Examples

cURL

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello","title":"Note"}' \
  "https://api.floralitys.com/api/v1/entries"

JavaScript (fetch)

JavaScript

const res = await fetch("https://api.floralitys.com/api/v1/entries", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Hello", title: "Note" }),
});
if (!res.ok) throw new Error(await res.text());
const { id } = await res.json();

Status codes

201: created id
400: validation / bad body
403: note limit reached (NOTE_LIMIT_REACHED)
503: storage not configured when re-hosting images fails (PRECONDITION_FAILED)
401 / 403: auth / scope

Get entry by id

GET/api/v1/entries/{entryId}

Behavior

Returns one active entry. Trashed or unknown ids return 404 (same as dashboard entries.get).

List / detail row fields

Field	Type	Notes
`_id`	string	Entry id (UUID)
`title`	string \| null	Optional
`content`	string	Markdown body
`createdAt` / `updatedAt`	number	Unix ms
`member`	object \| null	First linked member summary
`members`	array	All linked members (summary)
`memberId` / `memberIds`	string \| null / string[] \| null	Present on GET one only (detail)

Response

200

Single detail row (includes memberId and memberIds).

JSON

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "title": "Daily note",
  "content": "# Markdown\nBody text.",
  "createdAt": 1714233600000,
  "updatedAt": 1714237200000,
  "member": {
    "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
    "name": "string",
    "displayName": "string",
    "archived": false,
    "avatarUrl": null
  },
  "members": [],
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"]
}

404

Unknown id, wrong account, or entry is trashed.

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
if (!res.ok) throw new Error(await res.text());
const entry = await res.json();

Status codes

200: JSON object
400: invalid id
404: not found or trashed
401 / 403: auth / scope

Update entry

PATCH/api/v1/entries/{entryId}

Request body (JSON)

Strict object; at least one of title, content, memberId (UUID or null to clear legacy single link), memberIds (UUID array) must be present. Cannot update a trashed entry; restore first.

Response

200

Full detail object after update (same shape as GET one).

JSON

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "title": "Daily note",
  "content": "# Markdown\nBody text.",
  "createdAt": 1714233600000,
  "updatedAt": 1714237200000,
  "member": {
    "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
    "name": "string",
    "displayName": "string",
    "archived": false,
    "avatarUrl": null
  },
  "members": [],
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"]
}

400 / 404 / 503

Error object { "code", "message" }; 404 when the entry is missing after update is unlikely but uses NOT_FOUND.

Examples

cURL

Shell

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated"}' \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ title: "Updated" }),
  },
);
if (!res.ok) throw new Error(await res.text());
const entry = await res.json();

Status codes

200: JSON detail
400: validation, no fields, trash state, limits
404: missing entry after update (unexpected)
503: storage when re-hosting images
401 / 403: auth / scope

Delete entry

DELETE/api/v1/entries/{entryId}

Query parameters

permanent=true permanent=true (or 1 / yes): if the entry is active, moves to trash then purges immediately; if already trashed, purges only. Omit for soft delete (move to trash only).

Response

204

Success responses have no JSON body.

Plain text

// 204 No Content: empty response body

400 / 404

Typical error bodies when the delete cannot proceed.

JSON

{
  "code": "BAD_REQUEST",
  "message": "Entry is already in trash"
}

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL (soft)

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID"

cURL (permanent)

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID?permanent=true"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/entries/ENTRY_ID");
url.searchParams.set("permanent", "true"); // omit or false for soft delete (trash)
const res = await fetch(url.toString(), {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (res.status !== 204) throw new Error(await res.text());

Status codes

204: success
400: invalid id, already trashed on soft delete, not in trash for purge-only errors
404: unknown id or wrong account
401 / 403: auth / scope

Restore entry from trash

POST/api/v1/entries/{entryId}/restore

Response

204

Empty body on success.

Plain text

// 204 No Content: empty response body

400 / 404

Example 400 when the entry is not in trash. 404 uses the same envelope as other routes.

JSON

{
  "code": "BAD_REQUEST",
  "message": "Entry is not in trash"
}

JSON

{
  "code": "NOT_FOUND",
  "message": "Entry not found."
}

Examples

cURL

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID/restore"

JavaScript (fetch)

JavaScript

const res = await fetch(
  "https://api.floralitys.com/api/v1/entries/ENTRY_ID/restore",
  { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
if (res.status !== 204) throw new Error(await res.text());

Status codes

204: restored
400: not in trash, restore would exceed limits, etc.
404: not found (wrong id / tenant)
401 / 403: auth / scope