Reference

OpenAPI

The API contract below is imported from the shared package used by the Worker.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Lyrithm API",
    "version": "0.1.0",
    "description": "Provider-backed lyrics search and retrieval API."
  },
  "servers": [
    {
      "url": "https://api.lyrithm.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:8787",
      "description": "Local Wrangler dev"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "Worker is responding"
          }
        }
      }
    },
    "/lyrics": {
      "get": {
        "summary": "Fetch lyrics directly by artist and title",
        "security": [
          {},
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "artist",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "a",
            "in": "query",
            "description": "Short alias for artist.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title",
            "in": "query",
            "description": "Song title. Required unless t is provided.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "t",
            "in": "query",
            "description": "Short alias for title.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "album",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "al",
            "in": "query",
            "description": "Short alias for album.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "durationMs",
            "in": "query",
            "description": "Strongly recommended. Used for strict cache hits and better remix/live/cover matching. Requests without duration perform provider discovery.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "yt",
            "in": "query",
            "description": "Optional YouTube pointer hint used for fast cache lookup."
          },
          {
            "name": "sp",
            "in": "query",
            "description": "Optional Spotify pointer hint used for fast cache lookup."
          },
          {
            "name": "d",
            "in": "query",
            "description": "Short alias for durationMs.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "description": "Optional output mode. Omit for the highest available token stream, or use plain for plain text.",
            "schema": {
              "enum": [
                "plain"
              ]
            }
          },
          {
            "name": "g",
            "in": "query",
            "description": "Short alias for granularity. Only plain is supported.",
            "schema": {
              "enum": [
                "plain"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved lyrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LyricsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "Error": {
        "description": "JSON error response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "TimedLyric": {
        "type": "object",
        "required": [
          "text",
          "startMs",
          "endMs",
          "index"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "startMs": {
            "type": "integer",
            "minimum": 0
          },
          "endMs": {
            "type": "integer",
            "minimum": 0
          },
          "index": {
            "type": "string",
            "description": "Token position as line.word. Group by the line prefix to render line views."
          }
        }
      },
      "Lyrics": {
        "type": "object",
        "required": [
          "title",
          "artist",
          "granularity",
          "lyrics"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "artist": {
            "type": "string"
          },
          "album": {
            "type": "string"
          },
          "durationMs": {
            "type": "integer"
          },
          "granularity": {
            "enum": [
              "word",
              "line",
              "plain"
            ],
            "description": "Timing precision of the source. Timed lyrics are tokenized; line granularity means tokens share line-level timing."
          },
          "lyrics": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TimedLyric"
                }
              }
            ]
          }
        }
      },
      "LyricsResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Lyrics"
          },
          "meta": {
            "type": "object",
            "required": [
              "cache"
            ],
            "properties": {
              "cache": {
                "enum": [
                  "hit",
                  "miss"
                ]
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "enum": [
                  "BAD_REQUEST",
                  "UNAUTHORIZED",
                  "FORBIDDEN",
                  "RATE_LIMITED",
                  "NOT_FOUND",
                  "PROVIDER_ERROR",
                  "INTERNAL_ERROR"
                ]
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}