On this page

Good to know
The Folder object
List the subfolders of a folder
Create a folder
Retrieve a folder
Update a folder
Delete a folder

Folders organize the library, five levels deep at most. Colour and icon only apply to top-level folders; asking for them on a subfolder answers 403 forbidden.

Good to know

GET /v1/folders lists the subfolders of a parent (the top level without parentId); the contents of a folder are read with GET /v1/contents?folderId=….
Deleting a folder deletes its subfolders and their contents.

The Folder object

A folder of the library ("My contents"). Folders nest five levels deep at most.

Field	Type	Description
`id`always present	`string (uuid)`	Folder identifier (UUID).
`name`always present	`string`	Name of the folder.
`parentId`always present	`string \| null`	Parent folder, or null for a top-level folder.
`description`always present	`string \| null`	Description, or null.
`color`always present	`string \| null`	Colour `#RRGGBB` (top-level folders only), or null.
`icon`always present	`string \| null`	Icon name (top-level folders only), or null.
`updatedAt`always present	`string (date-time)`	Last update instant (ISO 8601, UTC).

Folder

{
  "id": "7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60",
  "name": "Biology",
  "parentId": null,
  "description": "Year 12 biology.",
  "color": "#3B82F6",
  "icon": "leaf",
  "updatedAt": "2026-10-02T08:30:12.000Z"
}

List the subfolders of a folder

GET/v1/foldersScope folders:read

Folders stored directly in the parent (the top level when parentId is omitted), in library order, paginated.

Parameters

Field	In	Type	Description
`parentId`optional	query	`string (uuid)`	Parent folder (UUID). Omit it to list the top-level folders.
`limit`optional	query	`integer`from 1 to 100 · default 50	Number of items per page, 1 to 100 (default 50).
`cursor`optional	query	`string`at most 200 characters	Opaque cursor: the `nextCursor` of the previous page. Keep the same `limit` from one page to the next.

Response 200

A page of folders — A page of Folder { data, nextCursor, hasMore }

Errors

HTTP	Meaning
`400`	`validation_error` or `invalid_cursor`
`401`	`invalid_api_key` or `revoked_api_key`
`403`	`insufficient_scope`, `account_suspended`, `live_not_enabled` or `forbidden`
`404`	`not_found` — the parent does not exist or is not visible to this key
`406`	`not_acceptable` — the `Accept` header excludes `application/json`
`429`	`rate_limited` or `test_quota_exceeded` — see the `Retry-After` and `RateLimit-*` headers
`500`	`internal_error`
`503`	`unavailable` — see the `Retry-After` header

Request

curl "https://api.memojin.com/v1/folders?limit=50" \
  -H "Authorization: Bearer $MEMOJIN_API_KEY"

Response 200

{
  "data": [
    {
      "id": "7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60",
      "name": "Biology",
      "parentId": null,
      "description": "Year 12 biology.",
      "color": "#3B82F6",
      "icon": "leaf",
      "updatedAt": "2026-10-02T08:30:12.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Create a folder

POST/v1/foldersScope folders:write

Creates a folder at the top level or inside a parent (five levels at most). Colour and icon apply to top-level folders only.

Parameters

Field	In	Type	Description
`Idempotency-Key`optional	header	`string`	Strongly recommended. A unique value per operation (UUID v4), reused unchanged on every retry. Within 24 hours, the same key and the same request replay the first response (`Idempotent-Replayed: true`) without a second effect or charge; another request with the same key → 422 `idempotency_key_reused`; still running → 409 `idempotency_in_progress`.

Request body `CreateFolderRequest`

A new folder.

Field	Type	Description
`name`required	`string`1 to 200 characters	Name of the folder (1 to 200 characters).
`parentId`optional	`string (uuid) \| null`	Parent folder; omitted or null = top level.
`description`optional	`string \| null`at most 2000 characters	Description (2,000 characters at most).
`color`optional	`string \| null`	Colour `#RRGGBB` (top-level folders only), or null.
`icon`optional	`string \| null`at most 64 characters	Icon name (top-level folders only).

Response 201

The folder created — A Folder object

Errors

HTTP	Meaning
`400`	`validation_error` or `bad_request`
`401`	`invalid_api_key` or `revoked_api_key`
`403`	`insufficient_scope`, `account_suspended`, `live_not_enabled` or `forbidden`
`404`	`not_found` — the parent does not exist or is not visible to this key
`406`	`not_acceptable` — the `Accept` header excludes `application/json`
`409`	`idempotency_in_progress` — retry after `Retry-After` (1 s)
`413`	`payload_too_large`
`415`	`unsupported_media_type`
`422`	`idempotency_key_reused`, or a business rule (see the description)
`429`	`rate_limited` or `test_quota_exceeded` — see the `Retry-After` and `RateLimit-*` headers
`500`	`internal_error`
`503`	`unavailable` — see the `Retry-After` header

Request

curl -X POST "https://api.memojin.com/v1/folders" \
  -H "Authorization: Bearer $MEMOJIN_API_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f7e-9a51-3c2d1e0f9b87" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Biology",
  "color": "#3B82F6",
  "icon": "leaf"
}'

Response 201

{
  "id": "7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60",
  "name": "Biology",
  "parentId": null,
  "description": "Year 12 biology.",
  "color": "#3B82F6",
  "icon": "leaf",
  "updatedAt": "2026-10-02T08:30:12.000Z"
}

Retrieve a folder

GET/v1/folders/{folderId}Scope folders:read

One folder of the account the API key acts for. Answers 304 to a matching If-None-Match.

Parameters

Field	In	Type	Description
`folderId`required	path	`string (uuid)`	Folder identifier (UUID).

Response 200

The folder — A Folder object

Errors

HTTP	Meaning
`400`	`validation_error` — an identifier is not a UUID
`401`	`invalid_api_key` or `revoked_api_key`
`403`	`insufficient_scope`, `account_suspended`, `live_not_enabled` or `forbidden`
`404`	`not_found`
`406`	`not_acceptable` — the `Accept` header excludes `application/json`
`429`	`rate_limited` or `test_quota_exceeded` — see the `Retry-After` and `RateLimit-*` headers
`500`	`internal_error`
`503`	`unavailable` — see the `Retry-After` header

Request

curl "https://api.memojin.com/v1/folders/7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60" \
  -H "Authorization: Bearer $MEMOJIN_API_KEY"

Response 200

{
  "id": "7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60",
  "name": "Biology",
  "parentId": null,
  "description": "Year 12 biology.",
  "color": "#3B82F6",
  "icon": "leaf",
  "updatedAt": "2026-10-02T08:30:12.000Z"
}

Update a folder

PATCH/v1/folders/{folderId}Scope folders:write

Changes the name, the description, the colour or the icon (colour and icon: top-level folders only, 403 forbidden otherwise).

Parameters

Field	In	Type	Description
`folderId`required	path	`string (uuid)`	Folder identifier (UUID).

Request body `UpdateFolderRequest`

The fields to change; the others stay as they are.

Field	Type	Description
`name`optional	`string`1 to 200 characters	New name (1 to 200 characters).
`description`optional	`string \| null`at most 2000 characters	New description, or null to clear it.
`color`optional	`string \| null`	Colour `#RRGGBB` (top-level folders only), or null.
`icon`optional	`string \| null`at most 64 characters	New icon name, or null.

Response 200

The folder updated — A Folder object

Errors

HTTP	Meaning
`400`	`validation_error` or `bad_request`
`401`	`invalid_api_key` or `revoked_api_key`
`403`	`insufficient_scope`, `account_suspended`, `live_not_enabled` or `forbidden`
`404`	`not_found`
`406`	`not_acceptable` — the `Accept` header excludes `application/json`
`412`	`precondition_failed` — `If-Match` does not match the current `ETag`
`413`	`payload_too_large`
`415`	`unsupported_media_type`
`429`	`rate_limited` or `test_quota_exceeded` — see the `Retry-After` and `RateLimit-*` headers
`500`	`internal_error`
`503`	`unavailable` — see the `Retry-After` header

Request

curl -X PATCH "https://api.memojin.com/v1/folders/7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60" \
  -H "Authorization: Bearer $MEMOJIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Biology — Year 12"
}'

Response 200

{
  "id": "7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60",
  "name": "Biology",
  "parentId": null,
  "description": "Year 12 biology.",
  "color": "#3B82F6",
  "icon": "leaf",
  "updatedAt": "2026-10-02T08:30:12.000Z"
}

Delete a folder

DELETE/v1/folders/{folderId}Scope folders:write

Deletes the folder, its subfolders and their contents. Answers 204 without a body.

Parameters

Field	In	Type	Description
`folderId`required	path	`string (uuid)`	Folder identifier (UUID).

Response 204

Deleted — No response body.

Errors

HTTP	Meaning
`400`	`validation_error` — an identifier is not a UUID
`401`	`invalid_api_key` or `revoked_api_key`
`403`	`insufficient_scope`, `account_suspended`, `live_not_enabled` or `forbidden`
`404`	`not_found`
`406`	`not_acceptable` — the `Accept` header excludes `application/json`
`412`	`precondition_failed` — `If-Match` does not match the current `ETag`
`429`	`rate_limited` or `test_quota_exceeded` — see the `Retry-After` and `RateLimit-*` headers
`500`	`internal_error`
`503`	`unavailable` — see the `Retry-After` header

Request

curl -X DELETE "https://api.memojin.com/v1/folders/7a2d9c41-0b3e-4c5f-8e6a-1d2c3b4a5f60" \
  -H "Authorization: Bearer $MEMOJIN_API_KEY"

Memojin for

Features

Subjects

Resources

Folders

Good to know

The Folder object

List the subfolders of a folder

Parameters

Response 200

Errors

Create a folder

Parameters

Request body `CreateFolderRequest`

Response 201

Errors

Retrieve a folder

Parameters

Response 200

Errors

Update a folder

Parameters

Request body `UpdateFolderRequest`

Response 200

Errors

Delete a folder

Parameters

Response 204

Errors

Folders

Good to know

The Folder object

List the subfolders of a folder

Parameters

Response 200

Errors

Create a folder

Parameters

Request body CreateFolderRequest

Response 201

Errors

Retrieve a folder

Parameters

Response 200

Errors

Update a folder

Parameters

Request body UpdateFolderRequest

Response 200

Errors

Delete a folder

Parameters

Response 204

Errors

Request body `CreateFolderRequest`

Request body `UpdateFolderRequest`