{
  "openapi": "3.1.0",
  "info": {
    "title": "Siftivo Agent API",
    "version": "0.1.0",
    "description": "Book discovery and a reader's library, callable by agents. The same tools are available over MCP at https://api.siftivo.com/mcp",
    "contact": {
      "url": "https://siftivo.com/blog/siftivo-for-agents/"
    }
  },
  "servers": [
    {
      "url": "https://api.siftivo.com"
    }
  ],
  "paths": {
    "/api/agent/search_books": {
      "get": {
        "operationId": "search_books",
        "summary": "Search books",
        "description": "Keyword search over the Siftivo book catalog. Matches titles, authors, and descriptions. Returns works with the ids other Siftivo tools accept.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Words to search for",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Words to search for"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          },
          {
            "name": "isFiction",
            "in": "query",
            "required": false,
            "description": "Restrict to fiction (true) or nonfiction (false)",
            "schema": {
              "type": "boolean",
              "description": "Restrict to fiction (true) or nonfiction (false)"
            }
          }
        ]
      }
    },
    "/api/agent/get_book": {
      "get": {
        "operationId": "get_book",
        "summary": "Get a book",
        "description": "Full detail for one book: synopsis, authors, series position, genres, and its page on siftivo.com. Accepts a work id, an edition id, or a slug.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "A Siftivo work id, edition id, or URL slug",
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A Siftivo work id, edition id, or URL slug"
            }
          }
        ]
      }
    },
    "/api/agent/what_to_read_next": {
      "get": {
        "operationId": "what_to_read_next",
        "summary": "What to read next",
        "description": "Given one book, what to read after it: the next books in its series, more by the same author, and books that read like it. This is the same set the book page on siftivo.com shows.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "workId",
            "in": "query",
            "required": true,
            "description": "A workId from search_books, get_book, or a URL slug",
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A workId from search_books, get_book, or a URL slug"
            }
          }
        ]
      }
    },
    "/api/agent/get_author": {
      "get": {
        "operationId": "get_author",
        "summary": "Get an author",
        "description": "An author, their biography, and the works Siftivo holds for them. Accepts an author id or slug.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ]
      }
    },
    "/api/agent/get_series": {
      "get": {
        "operationId": "get_series",
        "summary": "Get a series",
        "description": "A series and its works in reading order. Accepts a series id or slug.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ]
      }
    },
    "/api/agent/get_reading_index": {
      "get": {
        "operationId": "get_reading_index",
        "summary": "Get the Siftivo Reading Index",
        "description": "The weekly Siftivo Reading Index: the fiction and nonfiction books moving most in cultural circulation this week, ranked.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "week",
            "in": "query",
            "required": false,
            "description": "Edition week, YYYY-MM-DD. Omit for the current edition.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Edition week, YYYY-MM-DD. Omit for the current edition."
            }
          }
        ]
      }
    },
    "/api/agent/recommend_from_titles": {
      "post": {
        "operationId": "recommend_from_titles",
        "summary": "Recommend books from titles",
        "description": "Give Siftivo a few books someone liked, by title, and get books like them. Titles are resolved against the catalog first; anything that does not resolve is reported back rather than guessed at.",
        "tags": [
          "catalog"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "titles": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "Book titles, optionally \"Title by Author\""
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 5
                  },
                  "isFiction": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "titles"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        }
      }
    },
    "/api/agent/get_my_library": {
      "get": {
        "operationId": "get_my_library",
        "summary": "Get my library",
        "description": "The signed-in reader's own Siftivo library: what they want to read, are reading, finished, or set down, with their ratings.",
        "tags": [
          "library"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "No linked Siftivo account. The WWW-Authenticate header names the protected-resource metadata to begin OAuth from."
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [
          {
            "siftivoOAuth": [
              "profile",
              "email"
            ]
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter to one shelf. Omit for the whole library.",
            "schema": {
              "type": "string",
              "enum": [
                "NOT_STARTED",
                "READING",
                "FINISHED",
                "DNF"
              ],
              "description": "Filter to one shelf. Omit for the whole library."
            }
          }
        ]
      }
    },
    "/api/agent/add_to_library": {
      "post": {
        "operationId": "add_to_library",
        "summary": "Add a book to my library",
        "description": "Put a book on one of the signed-in reader's shelves, or move it to a different shelf. Pass a workId from search_books, get_book, or recommend_from_titles.",
        "tags": [
          "library"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "No linked Siftivo account. The WWW-Authenticate header names the protected-resource metadata to begin OAuth from."
          },
          "404": {
            "description": "No such entity"
          }
        },
        "security": [
          {
            "siftivoOAuth": [
              "profile",
              "email"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "readingStatus": {
                    "type": "string",
                    "enum": [
                      "NOT_STARTED",
                      "READING",
                      "FINISHED",
                      "DNF"
                    ],
                    "default": "NOT_STARTED"
                  }
                },
                "required": [
                  "workId"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "siftivoOAuth": {
        "type": "oauth2",
        "description": "Per-reader consent through Siftivo. Only the library tools require it; every catalog tool is open.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.siftivo.com/oauth/authorize",
            "tokenUrl": "https://api.siftivo.com/oauth/token",
            "scopes": {
              "profile": "Read which reader is calling",
              "email": "Read the reader's email address"
            }
          }
        }
      }
    }
  }
}