{ "openapi": "3.1.0", "info": { "title": "Instapaper API", "version": "2", "description": "Save, organize, and read articles in an Instapaper account. Requests and responses are JSON, authenticated with an OAuth 2 bearer token.", "termsOfService": "https://www.instapaper.com/developers/overview/api-terms", "license": { "name": "Instapaper API Terms of Service", "url": "https://www.instapaper.com/developers/overview/api-terms" }, "contact": { "name": "Instapaper Support", "email": "support@instapaper.com", "url": "https://www.instapaper.com/developers/v2" } }, "externalDocs": { "url": "https://www.instapaper.com/developers/v2" }, "servers": [ { "url": "https://www.instapaper.com/api/2" } ], "security": [ { "oauth2": [] }, { "bearerToken": [] } ], "tags": [ { "name": "Bookmarks", "description": "Save articles to a user's library, keep it in sync, and read the parsed text.", "externalDocs": { "url": "https://www.instapaper.com/developers/v2/reference/bookmarks" } } ], "paths": { "/bookmarks": { "get": { "operationId": "listBookmarks", "summary": "List bookmarks", "description": "Read one section of the user's library a page at a time, or pass `since` to get everything that changed across the whole account.\n\nIn `since` mode, changed bookmarks and deleted ids share each page, so a page can hold fewer than `limit` bookmarks. Advance `offset` by the number of bookmarks plus deleted ids you received, and stop when a page comes back with fewer than `limit` combined.", "parameters": [ { "name": "section", "in": "query", "required": false, "description": "Which list to read. Ignored when `since` is sent.", "schema": { "type": "string", "enum": [ "home", "archive", "liked", "folder", "tag" ], "default": "home" } }, { "name": "folder_id", "in": "query", "required": false, "description": "The folder to read. Required with `section=folder`, and implies it when sent on its own. Can't be combined with `tag`.", "schema": { "type": "integer" } }, { "name": "tag", "in": "query", "required": false, "description": "The tag name to read. Required with `section=tag`, and implies it when sent on its own.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of bookmarks to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "since", "in": "query", "required": false, "description": "Unix timestamp. Returns everything changed since then, plus `deleted_ids`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A page of bookmarks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkList" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Cannot specify both folder_id and tag\n- folder_id is required when section is folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "summary": "Cannot specify both folder_id and tag", "value": { "error": { "code": 400, "message": "Cannot specify both folder_id and tag" } } }, "InvalidFolderId": { "summary": "folder_id is required when section is folder", "value": { "error": { "code": 400, "message": "folder_id is required when section is folder" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] }, "post": { "operationId": "createBookmark", "summary": "Save a bookmark", "description": "Saving a URL the account already has doesn't create a duplicate. The existing bookmark is updated with whatever you sent and moved back to the top of the list.\n\nTo save content with no public URL, send `private_source` and `content` together and leave `url` out.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookmarkRequest" } } } }, "responses": { "200": { "description": "The saved bookmark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bookmark" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- url is required (unless using private_source)\n- Private bookmarks require supplied content\n- Invalid URL specified\n- Invalid or missing folder_id\n- Cannot add bookmarks to this folder\n- Invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MissingArgument": { "summary": "url is required (unless using private_source)", "value": { "error": { "code": 400, "message": "url is required (unless using private_source)" } } }, "PrivateBookmarkRequiresContent": { "summary": "Private bookmarks require supplied content", "value": { "error": { "code": 400, "message": "Private bookmarks require supplied content" } } }, "InvalidUrl": { "summary": "Invalid URL specified", "value": { "error": { "code": 400, "message": "Invalid URL specified" } } }, "InvalidFolderId": { "summary": "Invalid or missing folder_id", "value": { "error": { "code": 400, "message": "Invalid or missing folder_id" } } }, "CannotAddToFolder": { "summary": "Cannot add bookmarks to this folder", "value": { "error": { "code": 400, "message": "Cannot add bookmarks to this folder" } } }, "InvalidJson": { "summary": "Invalid JSON", "value": { "error": { "code": 400, "message": "Invalid JSON" } } } } } } }, "429": { "description": "Rate limited. Back off and retry later.\n\n- Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "error": { "code": 429, "message": "Rate limit exceeded" } } } } } } }, "500": { "description": "Something went wrong on our side. Retry with backoff.\n\n- Unexpected error when saving bookmark", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BookmarkSave": { "summary": "Unexpected error when saving bookmark", "value": { "error": { "code": 500, "message": "Unexpected error when saving bookmark" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}": { "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "description": "The bookmark to act on.", "schema": { "type": "integer" } } ], "post": { "operationId": "updateBookmark", "summary": "Update a bookmark", "description": "Send any combination of `title`, `description` and `progress`. Anything you leave out is unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookmarkRequest" } } } }, "responses": { "200": { "description": "The updated bookmark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bookmark" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found\n- Invalid or missing progress\n- Invalid or missing progress_timestamp\n- Invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } }, "InvalidProgress": { "summary": "Invalid or missing progress", "value": { "error": { "code": 400, "message": "Invalid or missing progress" } } }, "InvalidProgressTimestamp": { "summary": "Invalid or missing progress_timestamp", "value": { "error": { "code": 400, "message": "Invalid or missing progress_timestamp" } } }, "InvalidJson": { "summary": "Invalid JSON", "value": { "error": { "code": 400, "message": "Invalid JSON" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] }, "delete": { "operationId": "deleteBookmark", "summary": "Delete a bookmark", "description": "Deletion is permanent, and is not the same as archiving.", "responses": { "200": { "description": "Deleted. The response body is empty." }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}/move": { "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "description": "The bookmark to act on.", "schema": { "type": "integer" } } ], "post": { "operationId": "moveBookmark", "summary": "Move a bookmark", "description": "Move to the archive, back home, or into a folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveBookmarkRequest" } } } }, "responses": { "200": { "description": "The moved bookmark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bookmark" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found\n- `section` is required\n- Invalid section value\n- Invalid or missing folder_id\n- Invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } }, "MissingArgument": { "summary": "`section` is required", "value": { "error": { "code": 400, "message": "`section` is required" } } }, "InvalidRequest": { "summary": "Invalid section value", "value": { "error": { "code": 400, "message": "Invalid section value" } } }, "InvalidFolderId": { "summary": "Invalid or missing folder_id", "value": { "error": { "code": 400, "message": "Invalid or missing folder_id" } } }, "InvalidJson": { "summary": "Invalid JSON", "value": { "error": { "code": 400, "message": "Invalid JSON" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}/like": { "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "description": "The bookmark to act on.", "schema": { "type": "integer" } } ], "post": { "operationId": "likeBookmark", "summary": "Like a bookmark", "description": "Likes a bookmark. If bookmark is already liked, call succeeds as a no-op.", "responses": { "200": { "description": "The liked bookmark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bookmark" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] }, "delete": { "operationId": "unlikeBookmark", "summary": "Unlike a bookmark", "description": "Succeeds whether or not the bookmark was unliked.", "responses": { "200": { "description": "The unliked bookmark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bookmark" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}/tags": { "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "description": "The bookmark to act on.", "schema": { "type": "integer" } } ], "post": { "operationId": "updateBookmarkTags", "summary": "Tag a bookmark", "description": "Removals are applied before additions. `remove_tags` matches by id only; `add_tags` takes an id or a name, and a name that doesn't exist yet is created and returned in `created_tags`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookmarkTagsRequest" } } } }, "responses": { "200": { "description": "The bookmark's tags after the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkTags" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found\n- remove_tags or add_tags is required\n- Invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } }, "InvalidRequest": { "summary": "remove_tags or add_tags is required", "value": { "error": { "code": 400, "message": "remove_tags or add_tags is required" } } }, "InvalidJson": { "summary": "Invalid JSON", "value": { "error": { "code": 400, "message": "Invalid JSON" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } } }, "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}/parse": { "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "description": "The bookmark to act on.", "schema": { "type": "integer" } } ], "get": { "operationId": "getBookmarkContent", "summary": "Get article content", "description": "Instapaper's parsed version of a saved article: the cleaned-up body HTML plus the metadata extracted from the page.\n\nPersonal use, where the authenticated user registered the application, needs no key. Otherwise send your own `instaparser_api_key`.", "parameters": [ { "name": "use_cache", "in": "query", "required": false, "description": "Send 0 to bypass the parser cache.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "force", "in": "query", "required": false, "description": "Send 1 to force a re-parse rather than serving a stored copy.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "instaparser_api_key", "in": "query", "required": false, "description": "Your Instaparser key. Required for non-personal use by third-party applications.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The parsed article.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkParsedResult" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found\n- Parsed content unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } }, "ParsedContentUnavailable": { "summary": "Parsed content unavailable", "value": { "error": { "code": 400, "message": "Parsed content unavailable" } } } } } } }, "402": { "description": "An external content quota is exhausted.\n\n- Instaparser free credit limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserCreditsExceeded": { "summary": "Instaparser free credit limit exceeded", "value": { "error": { "code": 402, "message": "Instaparser free credit limit exceeded" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is not authorized for non-personal content access; an Instaparser API key is required\n- Invalid or unauthorized Instaparser API key\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserKeyRequired": { "summary": "Application is not authorized for non-personal content access; an Instaparser API key is required", "value": { "error": { "code": 403, "message": "Application is not authorized for non-personal content access; an Instaparser API key is required" } } }, "InvalidExternalParserKey": { "summary": "Invalid or unauthorized Instaparser API key", "value": { "error": { "code": 403, "message": "Invalid or unauthorized Instaparser API key" } } }, "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } }, "429": { "description": "Rate limited. Back off and retry later.\n\n- Instaparser rate-limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserRateLimit": { "summary": "Instaparser rate-limit exceeded", "value": { "error": { "code": 429, "message": "Instaparser rate-limit exceeded" } } } } } } }, "500": { "description": "Something went wrong on our side. Retry with backoff.\n\n- Error generating text version of this URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TextGeneration": { "summary": "Error generating text version of this URL", "value": { "error": { "code": 500, "message": "Error generating text version of this URL" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } } }, "tags": [ "Bookmarks" ] }, "post": { "operationId": "parseBookmarkContent", "summary": "Parse article content", "description": "The same as the GET form, with options in a JSON body. Send `content` to parse HTML you already have instead of fetching the URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseBookmarkRequest" } } } }, "responses": { "200": { "description": "The parsed article.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkParsedResult" } } } }, "400": { "description": "The request was malformed, or an argument was missing or invalid.\n\n- Bookmark not found\n- Parsed content unavailable\n- Invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidBookmarkId": { "summary": "Bookmark not found", "value": { "error": { "code": 400, "message": "Bookmark not found" } } }, "ParsedContentUnavailable": { "summary": "Parsed content unavailable", "value": { "error": { "code": 400, "message": "Parsed content unavailable" } } }, "InvalidJson": { "summary": "Invalid JSON", "value": { "error": { "code": 400, "message": "Invalid JSON" } } } } } } }, "402": { "description": "An external content quota is exhausted.\n\n- Instaparser free credit limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserCreditsExceeded": { "summary": "Instaparser free credit limit exceeded", "value": { "error": { "code": 402, "message": "Instaparser free credit limit exceeded" } } } } } } }, "403": { "description": "Authenticated, but not allowed.\n\n- Application is not authorized for non-personal content access; an Instaparser API key is required\n- Invalid or unauthorized Instaparser API key\n- Application is suspended\n- Application is not approved; unapproved applications may only be used with their owner's account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserKeyRequired": { "summary": "Application is not authorized for non-personal content access; an Instaparser API key is required", "value": { "error": { "code": 403, "message": "Application is not authorized for non-personal content access; an Instaparser API key is required" } } }, "InvalidExternalParserKey": { "summary": "Invalid or unauthorized Instaparser API key", "value": { "error": { "code": 403, "message": "Invalid or unauthorized Instaparser API key" } } }, "ApplicationSuspended": { "summary": "Application is suspended", "value": { "error": { "code": 403, "message": "Application is suspended" } } }, "ApplicationNotApproved": { "summary": "Application is not approved; unapproved applications may only be used with their owner's account", "value": { "error": { "code": 403, "message": "Application is not approved; unapproved applications may only be used with their owner's account" } } } } } } }, "429": { "description": "Rate limited. Back off and retry later.\n\n- Instaparser rate-limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalParserRateLimit": { "summary": "Instaparser rate-limit exceeded", "value": { "error": { "code": 429, "message": "Instaparser rate-limit exceeded" } } } } } } }, "500": { "description": "Something went wrong on our side. Retry with backoff.\n\n- Error generating text version of this URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TextGeneration": { "summary": "Error generating text version of this URL", "value": { "error": { "code": 500, "message": "Error generating text version of this URL" } } } } } } }, "401": { "description": "Authentication failed: the bearer token is missing, unknown, or revoked.\n\n- Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthenticationFailed": { "summary": "Authentication failed", "value": { "error": { "code": 401, "message": "Authentication failed" } } } } } } } }, "tags": [ "Bookmarks" ] } } }, "components": { "schemas": { "Bookmark": { "description": "Bookmark object", "properties": { "id": { "description": "Unique id for the bookmark, stable across requests.", "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The article's URL. Null for private content saved without one." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The article's title, as supplied or as found on the page." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The description you supplied, or the article's opening text." }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Thumbnail URL." }, "progress": { "$ref": "#/components/schemas/Progress", "description": "How far through the article the reader has got." }, "liked": { "description": "Whether it's in the liked list. Independent of archived.", "type": "boolean" }, "archived": { "description": "Whether it's in the archive. Independent of liked.", "type": "boolean" }, "time": { "description": "When it was saved, as a Unix timestamp.", "type": "integer" }, "pubtime": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "When the article was published, as a Unix timestamp." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Byline, when one was found." }, "folder_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "The folder it's in. Null when it's in the home list." }, "tags": { "description": "Every tag on the bookmark. Empty when it has none.", "items": { "$ref": "#/components/schemas/Tag" }, "type": "array" }, "private_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where private content came from, when it wasn't saved from a URL." }, "category": { "description": "0 article, 1 email, 2 video, 3 PDF, 4 social. Treat unknown values as an article, since more may be added.", "type": "integer" } }, "required": [ "id", "url", "title", "description", "image", "progress", "liked", "archived", "time", "pubtime", "author", "folder_id", "tags", "private_source", "category" ], "type": "object" }, "BookmarkAuthor": { "description": "Author of a parsed article", "properties": { "name": { "description": "The author's name, as printed on the page.", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Link to the author's page, when the page gives one." } }, "required": [ "name", "url" ], "type": "object" }, "BookmarkContent": { "description": "Body content for a parsed bookmark", "properties": { "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Article HTML, UTF-8, with scripts stripped." }, "images": { "default": [], "description": "URLs of the images kept in the body.", "items": { "type": "string" }, "type": "array" }, "words": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Word count of the parsed body." }, "paywalled": { "default": false, "description": "The page looked paywalled, so the body may be a preview.", "type": "boolean" }, "direction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ltr or rtl." } }, "required": [ "body", "images", "words", "paywalled", "direction" ], "type": "object" }, "BookmarkList": { "description": "A page of bookmarks", "properties": { "bookmarks": { "description": "This page of bookmarks, newest first unless you asked otherwise.", "items": { "$ref": "#/components/schemas/Bookmark" }, "type": "array" }, "total": { "description": "Size of the whole section, not of this page. In since mode, counts changed bookmarks and deleted ids together.", "type": "integer" }, "deleted_ids": { "description": "Bookmarks deleted since the timestamp. Present only in since mode.", "items": { "type": "integer" }, "type": "array" } }, "required": [ "bookmarks", "total" ], "type": "object" }, "BookmarkMetadata": { "description": "Descriptive metadata for parsed bookmark content", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title found on the page." }, "author": { "anyOf": [ { "$ref": "#/components/schemas/BookmarkAuthor" }, { "type": "null" } ], "default": null, "description": "Byline found on the page." }, "pubtime": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "When the article was published, as a Unix timestamp." }, "thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lead image for the article." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Short summary found on the page." }, "private_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where private content came from, when it wasn't parsed from a URL." }, "category": { "description": "0 article, 1 email, 2 video, 3 PDF, 4 social. Treat unknown values as an article, since more may be added.", "type": "integer" } }, "required": [ "title", "author", "pubtime", "thumbnail", "description", "private_source", "category" ], "type": "object" }, "BookmarkParsedResult": { "description": "Combined metadata + body returned by the parse endpoint", "properties": { "metadata": { "$ref": "#/components/schemas/BookmarkMetadata", "description": "What the page says about the article." }, "content": { "$ref": "#/components/schemas/BookmarkContent", "description": "The parsed article itself." } }, "required": [ "metadata", "content" ], "type": "object" }, "BookmarkTags": { "description": "Tags on a bookmark after an update", "properties": { "created_tags": { "description": "Only the tags this call brought into existence.", "items": { "$ref": "#/components/schemas/Tag" }, "type": "array" }, "tags": { "description": "The bookmark's full tag list afterwards.", "items": { "$ref": "#/components/schemas/Tag" }, "type": "array" } }, "required": [ "created_tags", "tags" ], "type": "object" }, "CreateBookmarkRequest": { "description": "Save a bookmark", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The URL to save. Required unless you send private_source." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "If omitted, the title is looked up before we respond, which slows the response. Send it if you have it." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "A short plaintext description or summary." }, "folder_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Save straight into this folder." }, "archived": { "default": false, "description": "Save directly to the archive.", "type": "boolean" }, "canonicalize": { "default": true, "description": "Set to false to skip resolving redirects and canonicalizing the URL.", "type": "boolean" }, "tags": { "default": [], "description": "Tags to apply to the new bookmark.", "items": { "$ref": "#/components/schemas/TagName" }, "type": "array" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Full HTML for the article, when you already have it. Required with private_source." }, "private_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "A short label naming where private content came from, e.g. \"Acme Reader\". Send it with content, instead of url." } }, "type": "object" }, "Error": { "description": "Error response body, as built by api.v2.errors.APIError.to_dict", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "What went wrong." } }, "required": [ "error" ], "type": "object" }, "ErrorDetail": { "description": "Error code and message", "properties": { "code": { "description": "Mirrors the HTTP status.", "type": "integer" }, "message": { "description": "Human-readable, and may be reworded over time. Don't match on it.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "MoveBookmarkRequest": { "description": "Move a bookmark", "properties": { "section": { "description": "\"archive\", \"home\", or a folder id as a string.", "examples": [ "archive", "home", "12345" ], "pattern": "^(archive|home|[0-9]+)$", "type": "string" } }, "required": [ "section" ], "type": "object" }, "ParseBookmarkRequest": { "description": "Options for fetching parsed article content", "properties": { "use_cache": { "default": true, "description": "Set to false to bypass the parser cache.", "type": "boolean" }, "force": { "default": false, "description": "Force a re-parse rather than serving a stored copy.", "type": "boolean" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTML you already have for the article, parsed instead of fetching the URL." }, "instaparser_api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Your Instaparser key. Required for non-personal use by third-party applications." } }, "type": "object" }, "Progress": { "description": "Progress information for a bookmark", "properties": { "percentage": { "description": "How far through the article the reader is, from 0.0 to 1.0.", "type": "number" }, "timestamp": { "description": "When that position was recorded, as a Unix timestamp.", "type": "integer" } }, "required": [ "percentage", "timestamp" ], "type": "object" }, "Tag": { "description": "Tag object", "properties": { "id": { "description": "Unique id for the tag, stable across requests.", "type": "integer" }, "name": { "description": "The tag as the user typed it.", "type": "string" }, "slug": { "description": "URL-safe form of the name.", "type": "string" }, "count": { "description": "Number of bookmarks with this tag.", "type": "integer" } }, "required": [ "id", "name", "slug", "count" ], "type": "object" }, "TagIdReference": { "description": "A tag, by id", "properties": { "id": { "description": "The id of the tag to remove.", "type": "integer" } }, "required": [ "id" ], "type": "object" }, "TagName": { "description": "A tag, by name", "properties": { "name": { "description": "Tag name. Created if it doesn't exist yet.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "TagReference": { "description": "A tag, by id or by name. A name that doesn't exist yet is created.", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "An existing tag's id. Takes precedence over name." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "A tag name. Created if it doesn't exist yet." } }, "type": "object" }, "UpdateBookmarkRequest": { "description": "Update any combination of a bookmark's fields", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replaces the stored title." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replaces the stored description." }, "progress": { "anyOf": [ { "$ref": "#/components/schemas/Progress" }, { "type": "null" } ], "default": null, "description": "Reading progress. An update older than the one on file is ignored." } }, "type": "object" }, "UpdateBookmarkTagsRequest": { "description": "Add and remove tags. At least one of the two is required.", "properties": { "add_tags": { "default": [], "description": "Tags to add, by id or by name.", "items": { "$ref": "#/components/schemas/TagReference" }, "type": "array" }, "remove_tags": { "default": [], "description": "Tags to remove, by id. Applied before add_tags.", "items": { "$ref": "#/components/schemas/TagIdReference" }, "type": "array" } }, "type": "object" } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Authorization code flow for acting on behalf of any user.", "flows": { "authorizationCode": { "authorizationUrl": "https://www.instapaper.com/oauth2/authorize", "tokenUrl": "https://www.instapaper.com/oauth2/token", "scopes": {} } } }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An access token from the authorization code flow, or one generated for your own account on the Applications page." } } } }