Skip to content
Omamo docs

API reference

Every path starts with https://omamo.app/api/public/v1. Every request needs your key in Authorization: Bearer <key>. Answers are JSON: data, or error with a code and a message. See the API guide for keys, pages, limits, and errors. The OpenAPI file describes the same endpoints for tools.

Spaces

Section titled “Spaces”

List spaces

Section titled “List spaces”

GET /spaces

The spaces you belong to, including the ones other people share with you. Any key can call it.

Answer (200)

Field Type Description
data object list The answer
data[].id string Its id
data[].name string Its name
data[].description string or null What it is for, or null
data[].boards integer How many boards it has
data[].members integer How many people belong to it 
curl "https://omamo.app/api/public/v1/spaces" \
  -H "Authorization: Bearer $OMAMO_KEY"

Boards

Section titled “Boards”

List boards

Section titled “List boards”

GET /spaces/{spaceId}/boards

The boards in a space that you can open, in their order. Any key can call it.

Path

Name Type Description
spaceId id The space’s id

Answer (200)

Field Type Description
data object list The answer
data[].id string Its id
data[].spaceId string The space it is in
data[].name string Its name
data[].description string or null What it is for, or null
data[].collections integer How many collections it has 
curl "https://omamo.app/api/public/v1/spaces/<spaceId>/boards" \
  -H "Authorization: Bearer $OMAMO_KEY"

Create a board

Section titled “Create a board”

POST /spaces/{spaceId}/boards

Adds a board to the end of a space. Needs a read and write key.

Path

Name Type Description
spaceId id The space’s id

Body (JSON)

Field Type Required Description
name string Yes Up to 100 characters
description string No Up to 500 characters

Answer (201)

Field Type Description
data object The answer
data.id string Its id
data.spaceId string The space it is in
data.name string Its name
data.description string or null What it is for, or null
data.collections integer How many collections it has 
curl -X POST "https://omamo.app/api/public/v1/spaces/<spaceId>/boards" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My name"}'

Update a board

Section titled “Update a board”

PATCH /boards/{boardId}

Renames a board or changes its description. Send at least one of the two. Needs a read and write key.

Path

Name Type Description
boardId id The board’s id

Body (JSON)

Field Type Required Description
name string No Up to 100 characters
description string No Up to 500 characters

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.spaceId string The space it is in
data.name string Its name
data.description string or null What it is for, or null
data.collections integer How many collections it has 
curl -X PATCH "https://omamo.app/api/public/v1/boards/<boardId>" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reading"}'

Collections

Section titled “Collections”

List collections

Section titled “List collections”

GET /boards/{boardId}/collections

The collections on a board, in their order. Any key can call it.

Path

Name Type Description
boardId id The board’s id

Answer (200)

Field Type Description
data object list The answer
data[].id string Its id
data[].boardId string The board it is on
data[].name string Its name
data[].description string or null What it is for, or null
data[].items integer How many items it holds 
curl "https://omamo.app/api/public/v1/boards/<boardId>/collections" \
  -H "Authorization: Bearer $OMAMO_KEY"

Create a collection

Section titled “Create a collection”

POST /boards/{boardId}/collections

Adds a collection to the end of a board. Needs a read and write key.

Path

Name Type Description
boardId id The board’s id

Body (JSON)

Field Type Required Description
name string Yes Up to 100 characters
description string No Up to 500 characters

Answer (201)

Field Type Description
data object The answer
data.id string Its id
data.boardId string The board it is on
data.name string Its name
data.description string or null What it is for, or null
data.items integer How many items it holds 
curl -X POST "https://omamo.app/api/public/v1/boards/<boardId>/collections" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My name"}'

Update a collection

Section titled “Update a collection”

PATCH /collections/{collectionId}

Renames a collection or changes its description. Send at least one of the two. Needs a read and write key.

Path

Name Type Description
collectionId id The collection’s id

Body (JSON)

Field Type Required Description
name string No Up to 100 characters
description string No Up to 500 characters

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.boardId string The board it is on
data.name string Its name
data.description string or null What it is for, or null
data.items integer How many items it holds 
curl -X PATCH "https://omamo.app/api/public/v1/collections/<collectionId>" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Later"}'

Items

Section titled “Items”

List items

Section titled “List items”

GET /collections/{collectionId}/items

The links and notes in a collection, in their order, a page at a time. Each has an excerpt; get an item for its whole text. Any key can call it.

Path

Name Type Description
collectionId id The collection’s id

Query

Name Type Required Description
limit integer No Items per page, up to 100. Default 50.
cursor string No nextCursor from the page before. Leave it out for the first page.

Answer (200)

Field Type Description
data object list This page
data[].id string Its id
data[].type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data[].title string Its title
data[].url string or null The address, for a link
data[].tags string list Tag names
data[].collectionId string The collection it is in
data[].createdAt string An ISO 8601 date and time
data[].updatedAt string An ISO 8601 date and time
data[].excerpt string or null The start of the note or description, up to 240 characters
nextCursor string or null Pass it as cursor for the next page. null on the last page. 
curl "https://omamo.app/api/public/v1/collections/<collectionId>/items" \
  -H "Authorization: Bearer $OMAMO_KEY"

Get an item

Section titled “Get an item”

GET /items/{itemId}

One link or note, with a note’s whole text. Any key can call it.

Path

Name Type Description
itemId id The item’s id

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data.title string Its title
data.url string or null The address, for a link
data.tags string list Tag names
data.collectionId string The collection it is in
data.createdAt string An ISO 8601 date and time
data.updatedAt string An ISO 8601 date and time
data.description string or null A link’s description
data.text string or null A note’s whole text, as plain text 
curl "https://omamo.app/api/public/v1/items/<itemId>" \
  -H "Authorization: Bearer $OMAMO_KEY"

Get a link’s article

Section titled “Get a link’s article”

GET /items/{itemId}/article

The page behind a link as Omamo saved it, in markdown. Part of Omamo Pro: on Free this answers 402. A link without a saved article answers 404. Any key can call it.

Path

Name Type Description
itemId id The item’s id

Answer (200)

Field Type Description
data object The answer
data.markdown string The article as Omamo saved it, in markdown
data.title string or null The article’s own title
data.author string or null Who wrote it, when the page says
data.siteName string or null The site it is from
data.published string or null When it was published, when the page says
data.wordCount integer How many words it has 
curl "https://omamo.app/api/public/v1/items/<itemId>/article" \
  -H "Authorization: Bearer $OMAMO_KEY"
Section titled “Save a link”

POST /collections/{collectionId}/links

Saves a web address into a collection. Omamo then reads the page for its title, picture, and description. A YouTube video is saved with type VIDEO and YouTube’s own picture. Needs a read and write key.

Path

Name Type Description
collectionId id The collection’s id

Body (JSON)

Field Type Required Description
url URL Yes An http or https address
title string No Defaults to the address until Omamo reads the page
description string No Up to 5,000 characters
tags string list No Tag names, up to 20. A name the space does not have yet becomes a new tag.

Answer (201)

Field Type Description
data object The answer
data.id string Its id
data.type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data.title string Its title
data.url string or null The address, for a link
data.tags string list Tag names
data.collectionId string The collection it is in
data.createdAt string An ISO 8601 date and time
data.updatedAt string An ISO 8601 date and time
data.description string or null A link’s description
data.text string or null A note’s whole text, as plain text 
curl -X POST "https://omamo.app/api/public/v1/collections/<collectionId>/links" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/"}'

Write a note

Section titled “Write a note”

POST /collections/{collectionId}/notes

Writes a note into a collection. Each line of the text becomes a paragraph. Needs a read and write key.

Path

Name Type Description
collectionId id The collection’s id

Body (JSON)

Field Type Required Description
title string Yes Up to 500 characters
text string Yes Plain text
tags string list No Tag names, up to 20. A name the space does not have yet becomes a new tag.

Answer (201)

Field Type Description
data object The answer
data.id string Its id
data.type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data.title string Its title
data.url string or null The address, for a link
data.tags string list Tag names
data.collectionId string The collection it is in
data.createdAt string An ISO 8601 date and time
data.updatedAt string An ISO 8601 date and time
data.description string or null A link’s description
data.text string or null A note’s whole text, as plain text 
curl -X POST "https://omamo.app/api/public/v1/collections/<collectionId>/notes" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"My title","text":"My text"}'

Update an item

Section titled “Update an item”

PATCH /items/{itemId}

Changes a link’s or note’s title, address, description, text, or tags. Send at least one. text is for notes and replaces the whole note; description and url are for links. tags replaces the item’s whole set of tags. Needs a read and write key.

Path

Name Type Description
itemId id The item’s id

Body (JSON)

Field Type Required Description
title string No Up to 500 characters
url URL No An http or https address
description string No A link’s description, up to 5,000 characters
text string No Plain text
tags string list No Tag names, up to 20. A name the space does not have yet becomes a new tag.

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data.title string Its title
data.url string or null The address, for a link
data.tags string list Tag names
data.collectionId string The collection it is in
data.createdAt string An ISO 8601 date and time
data.updatedAt string An ISO 8601 date and time
data.description string or null A link’s description
data.text string or null A note’s whole text, as plain text 
curl -X PATCH "https://omamo.app/api/public/v1/items/<itemId>" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"A better title","tags":["reading"]}'

Move an item

Section titled “Move an item”

POST /items/{itemId}/move

Moves a link or note to the end of a collection. Needs a read and write key.

Path

Name Type Description
itemId id The item’s id

Body (JSON)

Field Type Required Description
collectionId id Yes The collection’s id

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data.title string Its title
data.url string or null The address, for a link
data.tags string list Tag names
data.collectionId string The collection it is in
data.createdAt string An ISO 8601 date and time
data.updatedAt string An ISO 8601 date and time
data.description string or null A link’s description
data.text string or null A note’s whole text, as plain text 
curl -X POST "https://omamo.app/api/public/v1/items/<itemId>/move" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collectionId":"<collectionId>"}'

Delete an item

Section titled “Delete an item”

DELETE /items/{itemId}

Moves a link or note to Omamo’s trash. It can be restored in the app for 30 days. Needs a read and write key.

Path

Name Type Description
itemId id The item’s id

Answer (200)

Field Type Description
data object The answer
data.id string Its id
data.restorableForDays integer How long it waits in the trash 
curl -X DELETE "https://omamo.app/api/public/v1/items/<itemId>" \
  -H "Authorization: Bearer $OMAMO_KEY"

Move items

Section titled “Move items”

POST /items/bulk/move

Moves up to 100 items to the end of one collection, in the order given. Each item gets its own result, so one you may not move does not stop the rest. Needs a read and write key.

Body (JSON)

Field Type Required Description
itemIds id list Yes Item ids, up to 100
collectionId id Yes The collection’s id

Answer (200)

Field Type Description
data object The answer
data.results object list One result per item, in the order sent
data.results[].id string The item’s id
data.results[].ok boolean Whether it was done
data.results[].error string Why this item was left as it was 
curl -X POST "https://omamo.app/api/public/v1/items/bulk/move" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":["<itemId>"],"collectionId":"<collectionId>"}'

Tag items

Section titled “Tag items”

POST /items/bulk/tag

Adds tags to up to 100 items, takes tags off, or both. Their other tags stay. Each item gets its own result. Needs a read and write key.

Body (JSON)

Field Type Required Description
itemIds id list Yes Item ids, up to 100
add string list No Tag names, up to 20. A name the space does not have yet becomes a new tag.
remove string list No Tag names to take off. Case does not matter.

Answer (200)

Field Type Description
data object The answer
data.results object list One result per item, in the order sent
data.results[].id string The item’s id
data.results[].ok boolean Whether it was done
data.results[].error string Why this item was left as it was 
curl -X POST "https://omamo.app/api/public/v1/items/bulk/tag" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":["<itemId>"],"add":["reading"]}'

Delete items

Section titled “Delete items”

POST /items/bulk/delete

Moves up to 100 items to Omamo’s trash, where they can be restored for 30 days. Each item gets its own result. Needs a read and write key.

Body (JSON)

Field Type Required Description
itemIds id list Yes Item ids, up to 100

Answer (200)

Field Type Description
data object The answer
data.results object list One result per item, in the order sent
data.results[].id string The item’s id
data.results[].ok boolean Whether it was done
data.results[].error string Why this item was left as it was 
curl -X POST "https://omamo.app/api/public/v1/items/bulk/delete" \
  -H "Authorization: Bearer $OMAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":["<itemId>"]}'

Tags

Section titled “Tags”

List tags

Section titled “List tags”

GET /spaces/{spaceId}/tags

The tags in a space, most used first. Any key can call it.

Path

Name Type Description
spaceId id The space’s id

Answer (200)

Field Type Description
data object list The answer
data[].id string Its id
data[].name string Its name
data[].color string One of six inks: green, clay, indigo, ochre, plum, teal
data[].items integer How many items have it 
curl "https://omamo.app/api/public/v1/spaces/<spaceId>/tags" \
  -H "Authorization: Bearer $OMAMO_KEY"

List tagged items

Section titled “List tagged items”

GET /tags/{tagId}/items

The links and notes with a tag, newest first, across the boards you can open in its space. Any key can call it.

Path

Name Type Description
tagId id The tag’s id

Query

Name Type Required Description
limit integer No Items per page, up to 100. Default 50.
cursor string No nextCursor from the page before. Leave it out for the first page.

Answer (200)

Field Type Description
data object list This page
data[].id string Its id
data[].type LINK, NOTE, IMAGE, SCREENSHOT, VIDEO What the item is
data[].title string Its title
data[].url string or null The address, for a link
data[].tags string list Tag names
data[].collectionId string The collection it is in
data[].createdAt string An ISO 8601 date and time
data[].updatedAt string An ISO 8601 date and time
data[].excerpt string or null The start of the note or description, up to 240 characters
nextCursor string or null Pass it as cursor for the next page. null on the last page. 
curl "https://omamo.app/api/public/v1/tags/<tagId>/items" \
  -H "Authorization: Bearer $OMAMO_KEY"
Section titled “Search”

Search

Section titled “Search”

GET /search

Finds boards, collections, links, and notes in a space by the words in their titles and text. To search several spaces, make one request for each. Any key can call it.

Query

Name Type Required Description
q string Yes The words to find
spaceId id Yes The space’s id
limit integer No Results, up to 50. Default 20.

Answer (200)

Field Type Description
data object list The answer
data[].kind BOARD, COLLECTION, ITEM What was found
data[].id string Its id
data[].title string Its title or name
data[].url string or null
data[].itemType LINK, NOTE, IMAGE, SCREENSHOT, VIDEO or null For an item
data[].excerpt string or null
data[].spaceId string The space it is in
data[].boardId string or null
data[].collectionId string or null For an item 
curl "https://omamo.app/api/public/v1/search" \
  -H "Authorization: Bearer $OMAMO_KEY"