{ "openapi": "3.1.0", "info": { "title": "Omamo API", "version": "1.0.0", "description": "Read and save your Omamo spaces, boards, collections, links, and notes. Each key acts as the person who made it, with their permissions and their plan's limits. 120 requests a minute per key." }, "servers": [ { "url": "https://omamo.app/api/public/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Spaces" }, { "name": "Boards" }, { "name": "Collections" }, { "name": "Items" }, { "name": "Tags" }, { "name": "Search" } ], "paths": { "/spaces": { "get": { "operationId": "listSpaces", "tags": [ "Spaces" ], "summary": "List spaces", "description": "The spaces you belong to, including the ones other people share with you.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "boards": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many boards it has" }, "members": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people belong to it" } }, "required": [ "id", "name", "description", "boards", "members" ], "additionalProperties": false }, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/spaces/{spaceId}/boards": { "get": { "operationId": "listBoards", "tags": [ "Boards" ], "summary": "List boards", "description": "The boards in a space that you can open, in their order.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "spaceId", "in": "path", "required": true, "description": "The space's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "spaceId": { "type": "string", "description": "The space it is in" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "collections": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many collections it has" } }, "required": [ "id", "spaceId", "name", "description", "collections" ], "additionalProperties": false }, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "operationId": "createBoard", "tags": [ "Boards" ], "summary": "Create a board", "description": "Adds a board to the end of a space.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "spaceId", "in": "path", "required": true, "description": "The space's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Up to 100 characters" }, "description": { "type": "string", "maxLength": 500, "description": "Up to 500 characters" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "spaceId": { "type": "string", "description": "The space it is in" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "collections": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many collections it has" } }, "required": [ "id", "spaceId", "name", "description", "collections" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/boards/{boardId}": { "patch": { "operationId": "updateBoard", "tags": [ "Boards" ], "summary": "Update a board", "description": "Renames a board or changes its description. Send at least one of the two.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "The board's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Up to 100 characters" }, "description": { "type": "string", "maxLength": 500, "description": "Up to 500 characters" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "spaceId": { "type": "string", "description": "The space it is in" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "collections": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many collections it has" } }, "required": [ "id", "spaceId", "name", "description", "collections" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/boards/{boardId}/collections": { "get": { "operationId": "listCollections", "tags": [ "Collections" ], "summary": "List collections", "description": "The collections on a board, in their order.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "The board's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "boardId": { "type": "string", "description": "The board it is on" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items it holds" } }, "required": [ "id", "boardId", "name", "description", "items" ], "additionalProperties": false }, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "operationId": "createCollection", "tags": [ "Collections" ], "summary": "Create a collection", "description": "Adds a collection to the end of a board.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "The board's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Up to 100 characters" }, "description": { "type": "string", "maxLength": 500, "description": "Up to 500 characters" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "boardId": { "type": "string", "description": "The board it is on" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items it holds" } }, "required": [ "id", "boardId", "name", "description", "items" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/collections/{collectionId}": { "patch": { "operationId": "updateCollection", "tags": [ "Collections" ], "summary": "Update a collection", "description": "Renames a collection or changes its description. Send at least one of the two.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "description": "The collection's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Up to 100 characters" }, "description": { "type": "string", "maxLength": 500, "description": "Up to 500 characters" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "boardId": { "type": "string", "description": "The board it is on" }, "name": { "type": "string", "description": "Its name" }, "description": { "description": "What it is for, or null", "type": [ "string", "null" ] }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items it holds" } }, "required": [ "id", "boardId", "name", "description", "items" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/collections/{collectionId}/items": { "get": { "operationId": "listItems", "tags": [ "Items" ], "summary": "List items", "description": "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.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "description": "The collection's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, up to 100", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the page before. Leave it out for the first page.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "excerpt": { "description": "The start of the note or description, up to 240 characters", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "excerpt" ], "additionalProperties": false }, "description": "This page" }, "nextCursor": { "description": "Pass it as cursor for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/{itemId}": { "get": { "operationId": "getItem", "tags": [ "Items" ], "summary": "Get an item", "description": "One link or note, with a note's whole text.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "The item's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "description": { "description": "A link's description", "type": [ "string", "null" ] }, "text": { "description": "A note's whole text, as plain text", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "description", "text" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateItem", "tags": [ "Items" ], "summary": "Update an item", "description": "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.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "The item's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Up to 500 characters" }, "url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "An http or https address" }, "description": { "description": "A link's description, up to 5,000 characters", "type": "string", "maxLength": 5000 }, "text": { "description": "Plain text", "type": "string", "maxLength": 100000 }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 }, "description": "Tag names, up to 20. A name the space does not have yet becomes a new tag." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "description": { "description": "A link's description", "type": [ "string", "null" ] }, "text": { "description": "A note's whole text, as plain text", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "description", "text" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "deleteItem", "tags": [ "Items" ], "summary": "Delete an item", "description": "Moves a link or note to Omamo's trash. It can be restored in the app for 30 days.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "The item's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "restorableForDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long it waits in the trash" } }, "required": [ "id", "restorableForDays" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/{itemId}/article": { "get": { "operationId": "getArticle", "tags": [ "Items" ], "summary": "Get a link's article", "description": "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.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "The item's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "markdown": { "type": "string", "description": "The article as Omamo saved it, in markdown" }, "title": { "description": "The article's own title", "type": [ "string", "null" ] }, "author": { "description": "Who wrote it, when the page says", "type": [ "string", "null" ] }, "siteName": { "description": "The site it is from", "type": [ "string", "null" ] }, "published": { "description": "When it was published, when the page says", "type": [ "string", "null" ] }, "wordCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many words it has" } }, "required": [ "markdown", "title", "author", "siteName", "published", "wordCount" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/collections/{collectionId}/links": { "post": { "operationId": "saveLink", "tags": [ "Items" ], "summary": "Save a link", "description": "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.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "description": "The collection's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "An http or https address" }, "title": { "description": "Defaults to the address until Omamo reads the page", "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "description": "Up to 5,000 characters", "type": "string", "maxLength": 5000 }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 }, "description": "Tag names, up to 20. A name the space does not have yet becomes a new tag." } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "description": { "description": "A link's description", "type": [ "string", "null" ] }, "text": { "description": "A note's whole text, as plain text", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "description", "text" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/collections/{collectionId}/notes": { "post": { "operationId": "createNote", "tags": [ "Items" ], "summary": "Write a note", "description": "Writes a note into a collection. Each line of the text becomes a paragraph.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "description": "The collection's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Up to 500 characters" }, "text": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Plain text" }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 }, "description": "Tag names, up to 20. A name the space does not have yet becomes a new tag." } }, "required": [ "title", "text" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "description": { "description": "A link's description", "type": [ "string", "null" ] }, "text": { "description": "A note's whole text, as plain text", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "description", "text" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/{itemId}/move": { "post": { "operationId": "moveItem", "tags": [ "Items" ], "summary": "Move an item", "description": "Moves a link or note to the end of a collection.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "The item's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$", "description": "The collection's id" } }, "required": [ "collectionId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "description": { "description": "A link's description", "type": [ "string", "null" ] }, "text": { "description": "A note's whole text, as plain text", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "description", "text" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/bulk/move": { "post": { "operationId": "moveItems", "tags": [ "Items" ], "summary": "Move items", "description": "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.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" }, "description": "Item ids, up to 100" }, "collectionId": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$", "description": "The collection's id" } }, "required": [ "itemIds", "collectionId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The item's id" }, "ok": { "type": "boolean", "description": "Whether it was done" }, "error": { "description": "Why this item was left as it was", "type": "string" } }, "required": [ "id", "ok" ], "additionalProperties": false }, "description": "One result per item, in the order sent" } }, "required": [ "results" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/bulk/tag": { "post": { "operationId": "tagItems", "tags": [ "Items" ], "summary": "Tag items", "description": "Adds tags to up to 100 items, takes tags off, or both. Their other tags stay. Each item gets its own result.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" }, "description": "Item ids, up to 100" }, "add": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 }, "description": "Tag names, up to 20. A name the space does not have yet becomes a new tag." }, "remove": { "description": "Tag names to take off. Case does not matter.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } } }, "required": [ "itemIds" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The item's id" }, "ok": { "type": "boolean", "description": "Whether it was done" }, "error": { "description": "Why this item was left as it was", "type": "string" } }, "required": [ "id", "ok" ], "additionalProperties": false }, "description": "One result per item, in the order sent" } }, "required": [ "results" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/bulk/delete": { "post": { "operationId": "deleteItems", "tags": [ "Items" ], "summary": "Delete items", "description": "Moves up to 100 items to Omamo's trash, where they can be restored for 30 days. Each item gets its own result.\n\nNeeds a read and write key.", "x-omamo-scope": "write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" }, "description": "Item ids, up to 100" } }, "required": [ "itemIds" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The item's id" }, "ok": { "type": "boolean", "description": "Whether it was done" }, "error": { "description": "Why this item was left as it was", "type": "string" } }, "required": [ "id", "ok" ], "additionalProperties": false }, "description": "One result per item, in the order sent" } }, "required": [ "results" ], "additionalProperties": false, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/spaces/{spaceId}/tags": { "get": { "operationId": "listTags", "tags": [ "Tags" ], "summary": "List tags", "description": "The tags in a space, most used first.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "spaceId", "in": "path", "required": true, "description": "The space's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "name": { "type": "string", "description": "Its name" }, "color": { "type": "string", "description": "One of six inks: green, clay, indigo, ochre, plum, teal" }, "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items have it" } }, "required": [ "id", "name", "color", "items" ], "additionalProperties": false }, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/tags/{tagId}/items": { "get": { "operationId": "listTaggedItems", "tags": [ "Tags" ], "summary": "List tagged items", "description": "The links and notes with a tag, newest first, across the boards you can open in its space.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "tagId", "in": "path", "required": true, "description": "The tag's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, up to 100", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the page before. Leave it out for the first page.", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id" }, "type": { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, "title": { "type": "string", "description": "Its title" }, "url": { "description": "The address, for a link", "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names" }, "collectionId": { "type": "string", "description": "The collection it is in" }, "createdAt": { "type": "string", "description": "An ISO 8601 date and time" }, "updatedAt": { "type": "string", "description": "An ISO 8601 date and time" }, "excerpt": { "description": "The start of the note or description, up to 240 characters", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "tags", "collectionId", "createdAt", "updatedAt", "excerpt" ], "additionalProperties": false }, "description": "This page" }, "nextCursor": { "description": "Pass it as cursor for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/search": { "get": { "operationId": "search", "tags": [ "Search" ], "summary": "Search", "description": "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.\n\nAny key can call it.", "x-omamo-scope": "read", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The words to find", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "spaceId", "in": "query", "required": true, "description": "The space's id", "schema": { "type": "string", "format": "cuid", "pattern": "^[cC][0-9a-z]{6,}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Results, up to 50", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BOARD", "COLLECTION", "ITEM" ], "description": "What was found" }, "id": { "type": "string", "description": "Its id" }, "title": { "type": "string", "description": "Its title or name" }, "url": { "type": [ "string", "null" ] }, "itemType": { "anyOf": [ { "type": "string", "enum": [ "LINK", "NOTE", "IMAGE", "SCREENSHOT", "VIDEO" ], "description": "What the item is" }, { "type": "null" } ], "description": "For an item" }, "excerpt": { "type": [ "string", "null" ] }, "spaceId": { "type": "string", "description": "The space it is in" }, "boardId": { "type": [ "string", "null" ] }, "collectionId": { "description": "For an item", "type": [ "string", "null" ] } }, "required": [ "kind", "id", "title", "url", "itemType", "excerpt", "spaceId", "boardId", "collectionId" ], "additionalProperties": false }, "description": "The answer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from Omamo Settings: Authorization: Bearer omamo_…" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "invalid_request, unauthorized, payment_required, forbidden, insufficient_scope, not_found, conflict, too_large, rate_limited, unavailable, or server_error" }, "message": { "type": "string", "description": "What went wrong, in a sentence" }, "details": { "type": "array", "description": "For invalid_request: each field that is wrong", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } }, "responses": { "400": { "description": "The path, query, or body is not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not valid, revoked, or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Over the plan's limits, or a Pro feature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key cannot do this, or its owner may not", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not one its owner can open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: wait for Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }