{
  "openapi": "3.1.0",
  "info": {
    "title": "satchitananda",
    "version": "1",
    "summary": "Search the guided meditations on sat-chit-ananda.com.",
    "description": "One public, read-only endpoint: search, by words and by meaning, returning each meditation's page, audio links, length and the passage that matched. No key, no sign-in, no cookies. Nothing about who searched is stored or logged. The day's total of searches is counted. The words of a search that found nothing are counted by day, as ideas for what to make next. To match by meaning, the words are sent once to Google's embedding model (gemini-embedding-001), with nothing about who sent them. 100 searches per address per day (UTC). Over that, a 429 with Retry-After until midnight UTC.",
    "contact": {
      "url": "https://sat-chit-ananda.com/contact/"
    }
  },
  "servers": [
    {
      "url": "https://sat-chit-ananda.com"
    }
  ],
  "externalDocs": {
    "description": "The reference, in Markdown",
    "url": "https://sat-chit-ananda.com/docs/api.md"
  },
  "paths": {
    "/api/v1/search/": {
      "get": {
        "operationId": "search",
        "summary": "Find meditations by what they are for, how you feel, or a line you remember",
        "description": "Results come in order of relevance, with the filters' counts. 100 searches per address per day (UTC). Over that, a 429 with Retry-After until midnight UTC.",
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "What to look for, in your own words: what it is for, how you feel, or a line you remember. Also accepted as query or search.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "example": "help me fall asleep"
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "What to search. Meditations today; more kinds will come. Also accepted as type.",
            "schema": {
              "type": "string",
              "enum": [
                "meditation"
              ],
              "default": "meditation"
            },
            "example": "meditation"
          },
          {
            "name": "for",
            "in": "query",
            "required": false,
            "description": "Only those in this playlist (its slug), as the Meditations page's For filter. Also accepted as playlist.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,80}$"
            },
            "example": "sleep"
          },
          {
            "name": "sound",
            "in": "query",
            "required": false,
            "description": "Only those with this natural sound (rain, ocean, forest), as the Meditations page's Sound filter.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,80}$"
            },
            "example": "rain"
          },
          {
            "name": "length",
            "in": "query",
            "required": false,
            "description": "Only those of this length, in whole minutes as the cards show.",
            "schema": {
              "type": "string",
              "enum": [
                "under-20",
                "20-30",
                "over-30"
              ]
            },
            "example": "20-30"
          },
          {
            "name": "setting",
            "in": "query",
            "required": false,
            "description": "Only those for this setting: in bed, or sitting or lying down.",
            "schema": {
              "type": "string",
              "enum": [
                "bed",
                "sit-or-lie"
              ]
            },
            "example": "bed"
          },
          {
            "name": "voice",
            "in": "query",
            "required": false,
            "description": "Only those read in this kind of voice (the first voice you hear).",
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            },
            "example": "female"
          },
          {
            "name": "purpose",
            "in": "query",
            "required": false,
            "description": "Only those for this purpose, as their label says: for sleep, or to stay alert.",
            "schema": {
              "type": "string",
              "enum": [
                "sleep",
                "alert"
              ]
            },
            "example": "alert"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results to answer with. Also accepted as per_page or page_size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "example": 3
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "How many to skip: the previous answer's next_offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000,
              "default": 0
            },
            "example": 10
          },
          {
            "name": "prefix",
            "in": "query",
            "required": false,
            "description": "While someone types: the last word also matches as the start of a word.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "example": true
          }
        ],
        "responses": {
          "200": {
            "description": "The matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchAnswer"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is missing or not one the API knows; the body says which, and what to send instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Only GET and HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Over the day's 100 searches from this address.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until midnight UTC.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Search is busy.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "required": [
          "error",
          "suggestion",
          "next_steps"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong."
          },
          "suggestion": {
            "type": "string",
            "description": "What to do instead."
          },
          "did_you_mean": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "A close, known name or value, keyed by what was sent."
          },
          "next_steps": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Where to go next.",
              "required": [
                "action",
                "method",
                "url"
              ],
              "properties": {
                "action": {
                  "type": "string",
                  "description": "What it does, in a few words."
                },
                "method": {
                  "type": "string",
                  "enum": [
                    "GET"
                  ],
                  "description": "The HTTP method."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Where."
                }
              }
            },
            "description": "Where to go instead."
          }
        }
      },
      "SearchAnswer": {
        "type": "object",
        "required": [
          "query",
          "total",
          "offset",
          "limit",
          "next_offset",
          "results",
          "facets",
          "next_steps"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "The query, as searched (spaces tidied)."
          },
          "total": {
            "type": "integer",
            "description": "How many match, across every page."
          },
          "offset": {
            "type": "integer",
            "description": "How many were skipped."
          },
          "limit": {
            "type": "integer",
            "description": "How many were asked for."
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The offset for the next page, or null on the last."
          },
          "degraded": {
            "type": "string",
            "enum": [
              "words only"
            ],
            "description": "Present when matching by meaning was unavailable, so only words were matched."
          },
          "results": {
            "type": "array",
            "description": "The matches, most relevant first.",
            "items": {
              "type": "object",
              "required": [
                "kind",
                "slug",
                "title",
                "subtitle",
                "url",
                "duration_seconds",
                "length",
                "voices",
                "artist",
                "playlists",
                "cover",
                "audio",
                "match"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "description": "What it is: meditation."
                },
                "slug": {
                  "type": "string",
                  "description": "Its stable name in URLs."
                },
                "title": {
                  "type": "string",
                  "description": "Its title."
                },
                "subtitle": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "What it is for, in a line."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Its page, with the full transcript, notes and credits."
                },
                "duration_seconds": {
                  "type": "integer",
                  "description": "How long it is, in seconds."
                },
                "length": {
                  "type": "string",
                  "description": "As the site shows it, such as \"29 min\"."
                },
                "voices": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The voices you hear, by first name (each a clone of that person's own voice, with consent)."
                },
                "artist": {
                  "type": "string",
                  "description": "The voice with the Twins, such as \"Jessi + Twins\"."
                },
                "playlists": {
                  "type": "array",
                  "description": "The playlists it's in.",
                  "items": {
                    "type": "object",
                    "required": [
                      "title",
                      "url"
                    ],
                    "properties": {
                      "title": {
                        "type": "string",
                        "description": "The playlist's title."
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Its page."
                      }
                    }
                  }
                },
                "cover": {
                  "type": "string",
                  "format": "uri",
                  "description": "Its cover art, a square JPEG."
                },
                "audio": {
                  "type": "object",
                  "required": [
                    "m4a",
                    "mp3",
                    "flac"
                  ],
                  "description": "Direct links to the audio: AAC, a smaller MP3, and lossless FLAC.",
                  "properties": {
                    "m4a": {
                      "type": "string",
                      "format": "uri",
                      "description": "AAC, about 256 kbps."
                    },
                    "mp3": {
                      "type": "string",
                      "format": "uri",
                      "description": "MP3, smaller, for slow connections."
                    },
                    "flac": {
                      "type": "string",
                      "format": "uri",
                      "description": "Lossless FLAC."
                    }
                  }
                },
                "match": {
                  "type": "object",
                  "description": "What matched, and where in the track it is.",
                  "required": [
                    "text",
                    "highlights",
                    "chapter",
                    "by"
                  ],
                  "properties": {
                    "text": {
                      "type": "string",
                      "description": "The passage that matched, as plain text."
                    },
                    "highlights": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": {
                          "type": "integer"
                        },
                        "minItems": 2,
                        "maxItems": 2
                      },
                      "description": "[start, end) character ranges of the matched words in text."
                    },
                    "chapter": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "required": [
                        "title",
                        "at"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The part's title."
                        },
                        "at": {
                          "type": "number",
                          "description": "Where the part starts, in seconds."
                        }
                      },
                      "description": "The part of the track the passage is from, or null when it's from the notes."
                    },
                    "by": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "words",
                          "meaning"
                        ]
                      },
                      "description": "How it was found."
                    }
                  }
                }
              }
            }
          },
          "facets": {
            "type": "object",
            "properties": {
              "for": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              },
              "sound": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              },
              "length": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              },
              "setting": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              },
              "voice": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              },
              "purpose": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Results left by each value."
              }
            },
            "description": "For each filter, how many results each value would leave (with the other filters applied)."
          },
          "next_steps": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Where to go next.",
              "required": [
                "action",
                "method",
                "url"
              ],
              "properties": {
                "action": {
                  "type": "string",
                  "description": "What it does, in a few words."
                },
                "method": {
                  "type": "string",
                  "enum": [
                    "GET"
                  ],
                  "description": "The HTTP method."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Where."
                }
              }
            },
            "description": "Where to go next: the top result, and the next page."
          }
        }
      }
    }
  }
}